Create Card Token

Create a hosted page for a customer to save card details and manage cards.

Prerequisites

Create Customer

Note

Certain card operations on the hosted page require 3DS authentication by the cardholder. To simulate the cardholder's action in the sandbox, see Simulating 3DS Authentication.
Before you run this method, verify that the payment method can be tokenized. See List Payment Methods by Country.
In the sandbox, card tokens are removed after six months.

Rapyd sends you webhooks for the following customer actions:

Add a card.
- Customer Payment Method Created Webhook - Contains the same information as the response to Add Payment Method to Customer.
- Customer Updated Webhook - Contains the same information as the response to Update Customer.
- Payment Succeeded Webhook (card verification) - Contains the same information as the response to Create Payment.
Change the default card.
- Customer Updated Webhook - Contains the same information as the response to Update Customer.
Delete a card.
- Payment Method Canceled Webhook

Parameters

Request Header Parameters

Request Body Parameters

- billing_address_collect
- Indicates whether the hosted page displays address fields to fill in.
  true - The address fields are displayed.
  false - The address fields are displayed only for country codes US, GB and CA.
- cancel_url
- URL where the customer is redirected after pressing Back to Website to exit the hosted page. This URL overrides the merchant_website URL. Does not support localhost URLs.
- card_fields
- Contains details about the card.
  - recurrence_type
    Specifies the primary intended purpose of the saved payment method. See Saving a European Card While Creating a Payment. One of the following values:
    installment - Regular payments for a defined number of payment cycles.
    recurring - Regular payments for an indefinite period.
    unscheduled - Individual unrelated payments.
    unscheduled
- complete_url
- URL where the customer is redirected after pressing Close to exit the hosted page. This URL overrides the merchant_website URL. Does not support localhost URLs.
- complete_payment_url
- URL where the customer is redirected when payment is successful, after returning from an external page such as a 3DS page. Does not support localhost URLs.
- country
- The two-letter ISO 3166-1 ALPHA-2 code for the country.
- currency
- When specified in the request, defines a currency that is not the country's default currency. When not specified in the request, the country's default currency. Three-letter ISO 4217 code.
- customer
- ID of the customer, a string starting with cus_.
- error_payment_url
- URL where the customer is redirected when payment is not successful, after returning from an external page, such as a 3DS page. Does not support localhost URLs.
- language
- Determines the default language of the hosted page. For a list of values, see List Supported Languages.
  When this parameter is null, the language of the user's browser is used.
  If the language of the user's browser cannot be determined, the default language is English.
- page_expiration
- End of the time when the customer can use the hosted page, in Unix time. If page_expiration is not set, the hosted page expires 14 days after creation.
  Range: 1 minute to 30 days.
- payment_method_type
- Limits the page to a specific type of payment method. For example, dk_visa_card. For a list of payment methods, use List Payment Methods by Country.

Response Parameters

- billing_address_collect
- Indicates whether the hosted page displays address fields to fill in.
  true - The address fields are displayed.
  false - The address fields are displayed only for country codes US, GB and CA.
- cancel_url
- URL where the customer is redirected after pressing Back to Website to exit the hosted page. This URL overrides the merchant_website URL. Does not support localhost URLs.
card_fields
Contains details about the card.
- - recurrence_type
  - Specifies the primary intended purpose of the saved payment method. See also Saving a European Card While Creating a Payment. One of the following values:
    installment - Regular payments for a defined number of payment cycles.
    recurring - Regular payments for an indefinite period.
    unscheduled - Individual unrelated payments.
- category
- Category of payment method: card.
- complete_payment_url
- URL where the customer is redirected when payment is successful, after returning from an external page such as a 3DS page. Does not support localhost URLs.
- complete_url
- URL where the customer is redirected after pressing Close to exit the hosted page. This URL overrides the merchant_website URL. Does not support localhost URLs.
- country
- The two-letter ISO 3166-1 ALPHA-2 code for the country.
- currency
- When specified in the request, defines a currency that is not the country's default currency. When not specified in the request, the country's default currency. Three-letter ISO 4217 code.
- customer
- ID of the customer, a string starting with cus_.
- error_code
- Relevant error message and ID number of the error.
- error_payment_url
- URL where the customer is redirected when payment is not successful, after returning from an external page, such as a 3DS page. Does not support localhost URLs.
- id
- ID of the card token hosted page, a string starting with hp_card_.
- language
- Determines the default language of the hosted page. For a list of values, see List Supported Languages.
  When this parameter is null, the language of the user's browser is used.
  If the language of the user's browser cannot be determined, the default language is English.
- merchant_alias
- Reserved.
  Rapyd
- merchant_color
- Color of the call-to-action (CTA) button on the hosted page.
  To configure this field, use the Client Portal. See Customizing Your Hosted Page.
- merchant_customer_support
- Contains details of the client’s customer support. To configure these fields, use the Client Portal. See Customizing Your Hosted Page.
  email
  Email address.
  url
  URL for the client's customer support service.
  phone_number
  Phone number for contacting the client's customer support service.
- merchant_logo
- URL for the image of the client's logo.
  To configure this field, use the Client Portal. See Customizing Your Hosted Page.
- merchant_website
- The URL where the customer is redirected after exiting the hosted page. Relevant when one or both of the following fields is unset:
  - cancel_url
  - complete_url
  To configure this field, use the Fallback URL field in the Client Portal. See Customizing Your Hosted Page.
- page_expiration
- End of the time when the customer can use the hosted page, in Unix time. If page_expiration is not set, the hosted page expires 14 days after creation.
  Range: 1 minute to 30 days.
- payment_method_type
- Limits the page to a specific type of payment method. For example, dk_visa_card.
  For a list of payment method types, use List Payment Methods by Country.
- payment_params
- Contains the following fields. When these fields do not include values, the user is redirected to the hosted page, and a related status message appears at the top of the page.
  - complete_payment_url
    URL where the customer is redirected when payment is successful, after returning from an external page such as a 3DS page. Does not support localhost URLs.
  - error_payment_url
    URL where the customer is redirected when payment is not successful, after returning from an external page, such as a 3DS page. Does not support localhost URLs.
- redirect_url
- URL of the hosted page that is shown to the customer.
- status
- Status of the hosted page. One of the following:
  - NEW - The hosted page was created.
  - DON - Done. The card was added to the customer profile.
  - EXP - The hosted page expired.

/v1/hosted/collect/card

Create Card Token

curl -X post 'https://sandboxapi.rapyd.net/v1/hosted/collect/card' \
-H 'access_key: your-access-key-here' \
-H 'Content-Type: application/json' \
-H 'idempotency: your-idempotency-parameter-here' \
-H 'salt: your-random-string-here' \
-H 'signature: your-calculated-signature-here' \
-H 'timestamp: your-unix-timestamp-here' \
--data-raw '{
    "country": "GB",
    "customer": "cus_4e25112ac20e144ad073a614dc46934b",
    "complete_payment_url": "https://complete.rapyd.net/",
    "error_payment_url": "https://error.rapyd.net/",
    "card_fields": {
        "recurrence_type": "unscheduled"
    }
}'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "1c1bb5dc-4712-4afe-a253-b17ca129855f"
    },
    "data": {
        "id": "hp_card_dffdf3cfaa42472779c75f3e869ae964",
        "status": "NEW",
        "cancel_url": "https://example1234.net",
        "complete_url": "https://example1234.net",
        "language": null,
        "merchant_color": "323fff",
        "merchant_logo": null,
        "merchant_website": "https://example1234.net",
        "merchant_customer_support": {
            "url": "https://example1234.net",
            "email": "support@example1234.net",
            "phone_number": "121255551213"
        },
        "merchant_alias": "Doc Team",
        "page_expiration": 1764770507,
        "redirect_url": "https://sandboxhosted.rapyd.net/collect/card?token=hp_card_dffdf3cfaa42472779c75f3e869ae964",
        "category": "card",
        "country": "GB",
        "currency": "GBP",
        "customer": "cus_4e25112ac20e144ad073a614dc46934b",
        "payment_method_type": null,
        "payment_params": {
            "complete_payment_url": "https://complete.rapyd.net/",
            "error_payment_url": "https://error.rapyd.net/"
        },
        "billing_address_collect": false,
        "customer_card_payment_methods": null,
        "auto_set_default": false,
        "card_fields": {
            "recurrence_type": "unscheduled"
        }
    }
}

Bad Request - Payment Method Not Supported in Country

curl -X post 'https://sandboxapi.rapyd.net/v1/hosted/collect/card' \
-H 'access_key: your-access-key-here' \
-H 'Content-Type: application/json' \
-H 'idempotency: your-idempotency-parameter-here' \
-H 'salt: your-random-string-here' \
-H 'signature: your-calculated-signature-here' \
-H 'timestamp: your-unix-timestamp-here' \
--data-raw '{
	"country": "ES",
	"customer": "cus_2549026c92bd7cb5b02ba608daeb424b",
	"payment_method_type": "us_mastercard_card"
}'

{
    "status": {
        "error_code": "ERROR_HOSTED_PAGE_COLLECT_CARD_PAYMENT_METHOD_TYPE_NOT_SUPPORTED",
        "status": "ERROR",
        "message": "Please contact Rapyd Client Support.",
        "response_code": "ERROR_HOSTED_PAGE_COLLECT_CARD_PAYMENT_METHOD_TYPE_NOT_SUPPORTED",
        "operation_id": "b1e7792a-ac2f-4c35-8695-cedad3b74b51"
    }
}

Bad Request - Customer Not Found

curl -X post 'https://sandboxapi.rapyd.net/v1/hosted/collect/card' \
-H 'access_key: your-access-key-here' \
-H 'Content-Type: application/json' \
-H 'idempotency: your-idempotency-parameter-here' \
-H 'salt: your-random-string-here' \
-H 'signature: your-calculated-signature-here' \
-H 'timestamp: your-unix-timestamp-here' \
--data-raw '{
	"country": "ES",
	"customer": "cus_2549026c92bd7cb5b02ba608daeb424",
	"payment_method_type": "es_mastercard_card"
}'

{
    "status": {
        "error_code": "ERROR_HOSTED_PAGE_COLLECT_CARD_CUSTOMER_NOT_FOUND",
        "status": "ERROR",
        "message": "The request attempted a hosted page operation, but the customer was not found. The request was rejected. Corrective action: For 'customer', provide a valid customer ID, a string starting with 'cus_'.",
        "response_code": "ERROR_HOSTED_PAGE_COLLECT_CARD_CUSTOMER_NOT_FOUND",
        "operation_id": "7bb83aba-ed17-4aea-8d7b-e45e5dc2ef50"
    }
}

Related Information

In this section:

Documentation

Create Card Token

Note

Parameters

Request Header Parameters

Request Body Parameters

Response Parameters

Related Information

Search results