Save Card Details with Rapyd Checkout

Tokenize customer payment details to charge customers later.

Rapyd Checkout is the fastest way to collect customer payment details for top-ups, and recurring payment scenarios when an immediate authorization/capture is not necessary.

The Save Card Details feature simply enables your customers to use a web form to save (tokenize) card details for a future charge. Rapyd conducts a $0 auth to verify the card.

The Save Card Details page is also used by customers to manage their existing cards on file by selecting their default card, delete or add multiple cards.


Customers can Save their Card Details During their First Payment

The full Rapyd Checkout experience provides the option for customers to “save card details” during their first payment. See the Hosted Checkout Page Integration Steps for more payment and checkout details.

User Flow

User experience for the hosted Save Card Details Page:

  1. The customer enters all the card details in the Save Card Details hosted page and clicks Save.

  2. Once the card is saved, the customer is redirected to the Card Management screen where they can see their saved card (Rapyd saves it as a default_payment_method in the customer object).

Card management:
  • If the customer has more than one card, they can see all their saved cards.
  • The card that was added last is saved as the default card to the customer object.
  • The customer can select a different card OR remove an existing card OR add a new card.
  • The selected card is set as default.

For Toolkit integrations:

  • If the card is successfully saved, the customer is returned to your website, according to the code you entered for the onSaveCardDetailsSuccess event.
  • If the process fails, the customer is returned to your website, according to the code you entered for the onSaveCardDetailsFailure event.

How It Works

Save Card Details page is an iteration of Rapyd’s Hosted Checkout Page and Checkout Toolkit integration specific to only collecting card information. There are few steps and endpoints outlined here that differ from the complete Checkout experience.


  • Customize a Save Card Details page in the Branding section in Client Portal
  • Create a customer object
  • Generate your Save Card Details page with customer ID to collect payment information
  • Redirect your customer or embed the page in an iframe, using the toolkit

Save Card Details Using Hosted Checkout Integration

Step 1 - Customize the look and feel of your page to match your brand and website experience as described in Hosted Checkout Page.

Step 2 - Make sure to create a customer.

Step 3 - Generate the Save Card Details page with a customer param.

Step 4 - Redirect your customer

Redirect your customer to the URL you received in the response to Create Save Card Details page. The redirect URL appears in the redirect_url field.

  • Note: The page expires 14 days after creation by default.

Save Card Details Using Checkout Toolkit Method

Rapyd Checkout Toolkit has been specially designed to embed directly into your website to give your business more control over the entire experience.

Step 1 - Before embedding the iframe into your page, follow steps 1, 2 and 3 in the section above to create your Save Card Details Page.

Step 2 - In step 3 (when generating the page), make sure to also specify a complete_payment_url and error_payment_url






URL where the customer is redirected after completing the authentication on the third party site.

Relevant to a 3D Secure flow.



URL where the customer is redirected after an error occurs on the third party site.

Relevant to a 3D Secure flow.

Step 3 - Once you create the Save Card Details page, in the response you’ll receive the ID of the page object, a string starting with ‘hp_card_’, (for example: id: "hp_card_bd334669c8a80bc68c124b144c350b7f").

Step 4 - Add the following code to your page:

<script src=""></script>

Note: To run this method in the sandbox, use the following code:

<script src=""></script>

Add a <div> tag with id="rapyd-checkout":

<div id="rapyd-checkout"></div>

Initialize the Checkout Page object with the following fields:

let checkout = new RapydCheckoutToolkit({   
   pay_button_text: "Save",
          /* Text that appears on the Save button. 
             String. Maximum length is 16 characters.
            Default is "Save". Optional. */
   pay_button_color: "blue",
          /* Color of the 'Save' button. String.
             Standard CSS color name or hexadecimal code such as #323fff.
             Default is the color that is returned in the 'merchant_color'
             field of the response to 'Create ___ Page'. Optional.*/
   id: "hp_card_bd334669c8a80bc68c124b144c350b7f",
          /* ID of the 'Create __ Page' response. String. Required.*/
   close_on_complete: true,
          /* Causes the embedded Rapyd Toolkit window to close
             when the action is complete. Boolean. Default is 'true'. Optional.*/      
   page_type: “card_token”
         /* Mandatory for save card details page
            Default is "collection". */

Call display Checkout() to display the checkout page:


Optional step. If close_on_complete is set to false, call checkout.closeCheckout() to close the Rapyd Checkout Toolkit window.


Insert your code that runs when the following events occur. Use your code to read the event field in the 'window' object.

window.addEventListener('onSaveCardDetailsSuccess', (event) => {
                    // Returns ‘Payment’ object.
                    // Client code.
window.addEventListener('onSaveCardDetailsFailure', (event) => {
                    // Returns an error message from the API.
                    // Client code.

window.addEventListener('onLoading', (event) => {
                   // Returns true or false depending on the loading state
                    // Client code.



3D Secure flow: In case the customer is required to go through a 3DS authentication process, the required URL will be provided in the redirect_url field (part of the payment object). Make sure to redirect the customer to this page.

Using the Saved Card for Payments

If the card is successfully saved, Rapyd sends a CUSTOMER_UPDATED webhook (with the Customer Object, which includes the card token in the default_payment_method field).

For the payment, there are two options:

Option 1 - Use Rapyd API directly using the Create Payment method.
  1. Get the Required Fields for the Payment Method Type.
  2. Initiate your Customer's payment using the Create Payment method, with one of the following two ways:
  • Payment by payment method ID (the card token)
// Request URL: POST

// Message body:

 "amount": 100,
 "currency": "USD",
 "description": "Payment by card token",
 "payment_method": "card_fe2e4ae68af029321106c3ac1c0b30de"
  • Payment by default payment method (using the customer id)
// Request URL: POST

// Message body:

 "amount": 100,
 "currency": "USD",
 "customer": "cus_66ab4342703a84ce4d7ad2467d9d0322",
 "description": "Payment by customer's default payment method"
Option 2 - Initiate your Customer's payments using the saved card with Rapyd Checkout Page.

When passing the customer id in the Create Checkout request, the saved card/s will be displayed in the hosted checkout page and will be available for use.



Rapyd triggers an authorization payment behind the scenes, with the amount of 0. This payment is not captured, but you will see it as a 0 amount transaction in the client portal > Payments table.
These payments are automatically voided by Rapyd.

Updated 17 days ago

Save Card Details with Rapyd Checkout

Tokenize customer payment details to charge customers later.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.