--- title: "Create Card Token" source_url: https://docs.rapyd.net/en/create-card-token.html lang: en --- # Create Card Token Create a hosted page for a customer to save card details and manage cards. Prerequisites - [Create Customer](https://docs.rapyd.net/en/create-customer.md "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](https://docs.rapyd.net/en/simulating-3ds-authentication.md "Simulating 3DS Authentication"). > - Before you run this method, verify that the payment method can be tokenized. See [List Payment Methods by Country](https://docs.rapyd.net/en/list-payment-methods-by-country.md "List Payment Methods by Country"). > - In the sandbox, card tokens are removed after six months. > - The code samples include successful requests (200) and bad requests (400). > > - For error messages that appear due to bad requests (400), see: > > - [General Errors](https://docs.rapyd.net/en/general-errors.md "General Errors") > - [Card Token Errors](https://docs.rapyd.net/en/card-token-errors.md "Card Token Errors") > - For information about unauthorized request (401) and other authentication errors, see [Troubleshooting Authentication and Authorization Errors](https://docs.rapyd.net/en/troubleshooting-authentication-and-authorization-errors.md "Troubleshooting Authentication and Authorization Errors"). Rapyd sends you webhooks for the following customer actions: - Add a card. - [Customer Payment Method Created Webhook](https://docs.rapyd.net/en/customer-payment-method-created-webhook.md "Customer Payment Method Created Webhook") - Contains the same information as the response to [Add Payment Method to Customer](https://docs.rapyd.net/en/add-payment-method-to-customer.md "Add Payment Method to Customer"). - [Customer Updated Webhook](https://docs.rapyd.net/en/customer-updated-webhook.md "Customer Updated Webhook") - Contains the same information as the response to [Update Customer](https://docs.rapyd.net/en/update-customer.md "Update Customer"). - [Payment Succeeded Webhook](https://docs.rapyd.net/en/payment-succeeded-webhook.md "Payment Succeeded Webhook") (card verification) - Contains the same information as the response to [Create Payment](https://docs.rapyd.net/en/create-payment.md "Create Payment"). - Change the default card. - [Customer Updated Webhook](https://docs.rapyd.net/en/customer-updated-webhook.md "Customer Updated Webhook") - Contains the same information as the response to [Update Customer](https://docs.rapyd.net/en/update-customer.md "Update Customer"). - Delete a card. - [Payment Method Canceled Webhook](https://docs.rapyd.net/en/payment-method-canceled-webhook.md "Payment Method Canceled Webhook") ### Parameters ### Request Header Parameters - - access_key - Unique access key provided by Rapyd for each authorized user. See [Developers](https://docs.rapyd.net/en/developers.md "Developers"). - - Content-Type - Indicates that the data appears in JSON format. Set to **application/json**. - - idempotency - A unique key that prevents the platform from creating the same object twice. See [Idempotency](https://docs.rapyd.net/en/idempotency.md "Idempotency"). - - salt - Random string. Recommended length: 8-16 characters. - - signature - Signature calculated for each request individually. See [Request Signatures](https://docs.rapyd.net/en/request-signatures.md "Request Signatures"). - - timestamp - Timestamp for the request, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds). ### 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](https://docs.rapyd.net/en/saving-a-european-card-while-creating-a-payment.md "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](https://docs.rapyd.net/en/list-supported-languages.md "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](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "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](https://docs.rapyd.net/en/list-payment-methods-by-country.md "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](https://docs.rapyd.net/en/saving-a-european-card-while-creating-a-payment.md "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](https://docs.rapyd.net/en/list-supported-languages.md "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](https://docs.rapyd.net/en/customizing-your-hosted-page.md "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](https://docs.rapyd.net/en/customizing-your-hosted-page.md "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](https://docs.rapyd.net/en/customizing-your-hosted-page.md "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](https://docs.rapyd.net/en/customizing-your-hosted-page.md "Customizing Your Hosted Page"). - - page_expiration - End of the time when the customer can use the hosted page, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "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](https://docs.rapyd.net/en/list-payment-methods-by-country.md "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 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" } }' ``` - ```json { "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 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" }' ``` - ```json { "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 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" }' ``` - ```json { "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 - [Save Card Details With Rapyd Checkout](https://docs.rapyd.net/en/save-card-details-with-rapyd-checkout.md "Save Card Details With Rapyd Checkout") - [Card Numbers for Testing](https://docs.rapyd.net/en/card-numbers-for-testing.md "Card Numbers for Testing")