---
title: "Card on File"
source_url: https://docs.rapyd.net/en/card-on-file.html
lang: en
---

# Card on File

Store customer payment information for recurring and subscription purchases.

Streamline the card on file process and lower your [PCI](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_pci "Payment Card Industry") Compliance burden by generating a secure token for customers who opt to save their payment information with your business.

A typical use case may follow these steps:

1. While on your website, your customer selects to save their card for future use.
2. Rapyd stores the card details and links the card to your customer's Rapyd unique personal identifier.
3. Your customer buys an item for 9.99 USD (U.S. Dollars), with the stored card.
4. A month later, they return to purchase another item for 9.99 USD (U.S. Dollars).
5. Your website displays the stored card as the selected payment method.
6. You customer just clicks to pay.

> **Note:**
>
> The use case discusses a customer who stores a single payment method with Rapyd. However, customers can store multiple payment methods if they choose.

### Card on File Checkout

1. Select the card to use for the payment.
2. Click the **pencil** icon to edit the card details.

   ![6480836056ec8.png](image/img-3e4e54b03eef378747c4658b28cd20d6.png)
3. Optional: You can update the card details. Click **Update** to save the changes.
4. Click **Place Your Order**.

   ![64808363331dc.png](image/img-db5d30289001b4e0a3497f6b0439ad7d.png)
5. Redirect to the **Payment Success** page.
6. Click **Finish**.

   ![64808365aaab4.png](image/img-3821a2aa54da17acd73960f91c8ed70e.png)

### Card on File Workflow

Finding the specific card payment methods you'll accept and the corresponding required fields that customers fill out is described under How it Works.

### Step 1: Store a Customer Card

![store-customer-card.jpg](image/img-b807b15857022d988b959e6492923727.jpg)

1. A customer on your website adds an item to the shopping cart and presses the checkout button. The customer fills in the card information and selects **Store the card details for future use**. Then the customer clicks **Pay now**.
2. Your website asks Rapyd to create a Customer ID.
3. Then your website asks Rapyd to create a $0 [Auth](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_authorization "Authorization") payment to validate the card using the Customer ID.
4. Rapyd sends your website the Customer ID to use the card on file as the customer's default payment method.

> **Note:**
>
> For more information on how to save customer card information using a hosted page, see [Save Card Details With Rapyd Checkout](https://docs.rapyd.net/en/save-card-details-with-rapyd-checkout.md "Save Card Details With Rapyd Checkout").

### Step 2: Process First-Time Payment

![process-first-time.jpg](image/img-363d0d8d45e38615072b523b715c6ff6.jpg)

1. The website back end asks Rapyd to process the customer's payment, specifying the amount, currency, and Customer ID.
2. Rapyd processes the transaction using the stored card that's linked to the Customer ID. When successfully completed, Rapyd notifies the website back end.
3. Your website displays a page informing the customer that the purchase was successfully completed.

### Step 3: Start a Subsequent Purchase

![subsequent-purchase.jpg](image/img-96b71bf154e35695660d2fe76790d390.jpg)

1. Your customer returns a month later, adds a new eBook to the shopping cart, and checks out.
2. Based on information exchanged with Rapyd, your website displays the stored card as the selected payment method.
3. The customer clicks **Pay now** .

### Step 4: Process a Subsequent Payment

![process-next-payment.jpg](image/img-535a4378459758ee194d60e68814ce08.jpg)

1. The website back end asks Rapyd to process the customer's payment, specifying the amount, currency, and Customer ID.
2. Rapyd processes the transaction using the stored card that's linked to the Customer ID. When successfully completed, Rapyd notifies the website's back end.
3. Your website displays a "purchase succeeded" page to your customer.

### How Card on File Works

### Find Available Payment Methods

Decide which card payment methods you will accept, so that your customer can specify their payment methods on your payment page. Use [List Payment Methods by Country](https://docs.rapyd.net/en/list-payment-methods-by-country.md "List Payment Methods by Country") with the following parameters:

- US and USD is displayed as an example for country and currency.

Description of Query Parameters

| Query Parameter | Description |
| --- | --- |
| country | Enter **US** as the country code. |
| currency | Enter **USD** as the currency code. |

### List Payment Methods by Country Request

Create a request for a list of all available US payment methods.

- - Request

    - ```
      // Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/country?country=US&currency=USD

      // Message body absent
      ```
- - .NET Core

    - ```
      using System;

      namespace RapydApiRequestSample
      {
          class Program
          {
              static void Main(string[] args)
              {
                  try
                  {
                      string country = "US";
                      string currency = "USD";

                      string result = RapydApiRequestSample.Utilities.MakeRequest("GET", $"/v1/payment_methods/country?country={country}&currency={currency}");

                      Console.WriteLine(result);
                  }
                  catch (Exception e)
                  {
                      Console.WriteLine("Error completing request: " + e.Message);
                  }
              }
          }
      }
      ```
- - JavaScript

    - ```
      const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

      async function main() {
        try {
          const result = await makeRequest('GET', '/v1/payment_methods/country?country=US&currency=USD');

          console.log(result);
        } catch (error) {
          console.error('Error completing request', error);
        }
      }
      ```
- - PHP

    - ```
      <?php
      $path = $_SERVER['DOCUMENT_ROOT'];
      $path .= "/<path-to-your-utility-file>/utilities.php";
      include($path);

      try {
          $object = make_request('get', '/v1/payment_methods/country?country=US&currency=USD');
          var_dump($object);
      } catch (Exception $e) {
          echo "Error: $e";
      }
      ?>
      ```
- - Python

    - ```
      from pprint import pprint

      from utilities import make_request

      country = 'US'
      currency = 'USD'
      results = make_request(method='get',
                             path=f'/v1/payment_methods/country?country={country}&currency={currency}')
      pprint(results)
      ```

### List Payment Methods by Country Response

[Payment Method Type](https://docs.rapyd.net/en/payment-method-type.md "Payment Method Type") describes the fields in the response.

- - Response

    - ```
      {
          "status": {
              "error_code": "",
              "status": "SUCCESS",
              "message": "",
              "response_code": "",
              "operation_id": "cfa35a73-aa0b-4e7e-839c-4c3b6149edd7"
          },
          "data": [{
                  "type": "us_debit_visa_card",
                  "name": "Visa",
                  "category": "card",
                  "image": "https://iconslib.rapyd.net/checkout/us_visa_card.png",
                  "country": "us",
                  "payment_flow_type": "card",
                  "currencies": [
                      "USD"
                  ],
                  "status": 1,
                  "is_cancelable": false,
                  "payment_options": [{
                          "name": "customer",
                          "type": "customer",
                          "regex": "",
                          "description": "make sure a customer was created with first_name, last_name and email",
                          "is_required": true,
                          "is_updatable": false
                      }
                  ],
                  "is_expirable": false,
                  "is_online": false,
                  "minimum_expiration_seconds": null,
                  "maximum_expiration_seconds": null
              }
          ]
      }
      ```

The `data` section of the response shows that a Visa card is an acceptable payment option.

> **Note:**
>
> A real response usually lists many payment methods.

### Find Required Fields for the Payment Method

You need to identify the fields that the customer must complete for the payment method.

To identify the fields, you'll use the [Get Payment Method Required Fields](https://docs.rapyd.net/en/get-payment-method-required-fields.md "Get Payment Method Required Fields") with the following parameter.

Description of Path Parameters

| Path Parameter | Description |
| --- | --- |
| type | Enter **us_debit_visa_card** as the payment method type. |

### Get Payment Method Required Fields Request

Create a request for the set of required fields for a Visa card.

- - Request

    - ```
      // Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/us_debit_visa_card/required_fields

      // Message body absent
      ```
- - .NET Core

    - ```
      using System;

      namespace RapydApiRequestSample
      {
          class Program
          {
              static void Main(string[] args)
              {
                  try
                  {
                      string type = "us_visa_card";

                      string result = RapydApiRequestSample.Utilities.MakeRequest("GET", $"/v1/payment_methods/{type}/required_fields");

                      Console.WriteLine(result);
                  }
                  catch (Exception e)
                  {
                      Console.WriteLine("Error completing request: " + e.Message);
                  }
              }
          }
      }
      ```
- - JavaScript

    - ```
      const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

      async function main() {
        try {
          const result = await makeRequest('GET', '/v1/payment_methods/us_visa_card/required_fields');

          console.log(result);
        } catch (error) {
          console.error('Error completing request', error);
        }
      }
      ```
- - PHP

    - ```
      <?php
      $path = $_SERVER['DOCUMENT_ROOT'];
      $path .= "/<path-to-your-utility-file>/utilities.php";
      include($path);

      try {
          $object = make_request('get', '/v1/payment_methods/us_visa_card/required_fields');
          var_dump($object);
      } catch (Exception $e) {
          echo "Error: $e";
      }
      ?>
      ```
- - Python

    - ```
      from pprint import pprint

      from utilities import make_request

      payment_method = 'us_visa_card'
      results = make_request(method='get',
                             path=f'/v1/payment_methods/{payment_method}/required_fields')
      pprint(results)rom pprint import pprint

      from utilities import make_request

      country = 'US'
      currency = 'USD'
      results = make_request(method='get',
                             path=f'/v1/payment_methods/country?country={country}&currency={currency}')
      pprint(results)
      ```

### Get Payment Method Required Fields Response

[Payment Method Type](https://docs.rapyd.net/en/payment-method-type.md "Payment Method Type") describes the fields in the response.

- - Response

    - ```
      {
          “status”: {
              “error_code”: “”,
              “status”: “SUCCESS”,
              “message”: “”,
              “response_code”: “”,
              “operation_id”: “598b1a00-e302-4037-b0ef-aac895974e9e”
          },
          “data”: {
              “type”: “us_visa_card”,
              “fields”: [
                  {
                      “name”: “number”,
                      “type”: “string”,
                      “regex”: “”,
                      “is_required”: true,
                      “instructions”: “card number”
                  },
                  {
                      “name”: “expiration_month”,
                      “type”: “string”,
                      “regex”: “”,
                      “is_required”: true,
                      “instructions”: “expiration month as string, 01-12”
                  },
                  {
                      “name”: “expiration_year”,
                      “type”: “string”,
                      “regex”: “”,
                      “is_required”: true,
                      “instructions”: “expiration year in to digits as string, 18-99"
                  },
                  {
                      “name”: “cvv”,
                      “type”: “string”,
                      “regex”: “”,
                      “is_required”: false,
                      “instructions”: “card cvv”
                  },
                  {
                      “name”: “name”,
                      “type”: “string”,
                      “regex”: “”,
                      “is_required”: false,
                      “instructions”: “card holder name”
                  },
                  {
                      “name”: “address”,
                      “type”: “Address”,
                      “regex”: “”,
                      “is_required”: false,
                      “instructions”: “card billing address. see Address object for more details”
                  }
              ],
              “payment_method_options”: [
                  {
                      “name”: “3d_required”,
                      “type”: “string”,
                      “regex”: “”,
                      “description”: “”,
                      “is_required”: false,
                      “is_updatable”: false
                  }
              ],
              “payment_options”: [
                  {
                      “name”: “customer”,
                      “type”: “customer”,
                      “regex”: “”,
                      “description”: “make sure a customer was created with first_name, last_name and email”,
                      “is_required”: true,
                      “is_updatable”: false
                  }
              ],
              “minimum_expiration_seconds”: null,
              “maximum_expiration_seconds”: null
          }
      }
         
      ```

The response shows that for a US Visa card, you must provide:

- `number`
- `expiration_month`
- `expiration_year`
- `name`
- `cvv`

Ensure that the customer completes these fields.

### Create the Customer ID and Store the Card

When your customer saves their card details, Rapyd creates a unique Customer ID, stores their card, and links it to their ID. Use this ID whenever you need Rapyd to handle a request for this customer. The minimum we need for the ID is the customer name. Send Rapyd a request for the Customer ID and stored card.

For that, you'll use [Create Customer](https://docs.rapyd.net/en/create-customer.md "Create Customer") with the following parameters:

Description of Body Parameters

| Body Parameter | Description |
| --- | --- |
| name | Enter **Jane Doe** as the customer name. |
| payment_method | Enter an object with the following fields:  - `type` - **us_debit_visa_card** - `fields` - Enter an object with the following fields:  - `number` - **4111111111111111**   - `expiration_month` - **10**   - `expiration_year` - **20**   - `cvv` - **123**   - `name` - **Jane Doe** |

### Create Customer Request

You ask Rapyd to create a Customer ID and a payment method for your customer.

- - Request

    - ```
      // Request URL: POST https://sandboxapi.rapyd.net/v1/customers

      // Message body: 
      {
          "name": "Jane Doe",
          "payment_method": {
              "type": "us_debit_visa_card",
              "fields": {
                  "number": "4111111111111111",
                  "expiration_month": "10",
                  "expiration_year": "20",
                  "cvv": "123",
                  "name": "Jane Doe"
              }
          }
      }
      ```
- - Python

    - ```python
      from pprint import pprint

      from utilities import make_request
                                                  
      customer_body = {
          "name": "Jane Doe",
          "payment_method": {
              "type": "us_visa_card",
              "fields": {
                  "number": "4111111111111111",
                  "expiration_month": "10",
                  "expiration_year": "20",
                  "cvv": "123",
                  "name": "Jane Doe"
              }
          }
      }
                                                  
      create_customer_response = make_request(method='post',
                                              path='/v1/customers',
                                              body=customer_body)
      pprint(create_customer_response)
      ```

### Create Customer Response

[Customer Object](https://docs.rapyd.net/en/customer.md "Customer") describes the fields in the response.

- - Response

    - ```
      {
          "status": {
              "error_code": "",
              "status": "SUCCESS",
              "message": "",
              "response_code": "",
              "operation_id": "92b400c5-6c1d-484c-b327-bb7015897f89"
          },
          "data": {
              "id": "cus_8ded332b08966abf51bdc28c106acb7c",

              //      ...

              "name": "Jane Doe",
              "default_payment_method": "card_dbc9f6743ec2ab00486843edfdca42d9",

              //      ...

              "payment_methods": {
                  "data": [
                      {
                          "id": "card_dbc9f6743ec2ab00486843edfdca42d9",
                          "type": "us_debit_visa_card",
                          "category": "card",
                          "metadata": null,
                          "image": "https://iconslib.rapyd.net/checkout/us_visa_card.png",
                          "name": "Jane Doe",
                          "last4": "1111",
                          "cvv_check": "unchecked",

                          //      ...

                          "expiration_year": "20",
                          "expiration_month": "10",

                          //      ...

                      }
                  ],

                  //      ...

                  "url": "/v1/customers/cus_8ded332b08966abf51bdc28c106acb7c/payment_methods"
              },

              //      ...

              "created_at": 1581246256,

              //      ...

          }
      }
         
      ```

The `data` section of this response shows that:

- Rapyd creates a Customer ID for your customer. The Customer ID starts with **cus_**. The customer's `id` value in the example code above, is **cus_8ded332b08966abf51bdc28c106acb7c**. When you run this example in your own sandbox, you will get a different customer ID.
- Rapyd also creates a card ID for your customer. The card ID starts with **card_**. The card  `id` in the example code above is  **card_dbc9f6743ec2ab00486843edfdca42d9**. This card is now stored as the `default_payment_method`.

### Process the Payment

When your customer pays with their stored card, you submit the payment to Rapyd for processing.

To submit the customer's payment, use [Create Payment](https://docs.rapyd.net/en/create-payment.md "Create Payment") with the following parameters:

Description of Body Parameters

| Body Parameter | Description |
| --- | --- |
| amount | Enter **9.99** as the payment amount. |
| currency | Enter **USD** as the currency code. |
| customer | Enter the 'customer_id' that you received when you created the customer in your sandbox. For purposes of this use case lesson, we are using  **cus_8ded332b08966abf51bdc28c106acb7c**, which is the customer ID we created in our sandbox. |

### Create Payment Request

Request Rapyd to process your customer's payment for 9.99 USD (U.S. Dollars) (as shown in this example code below).

- - Request

    - ```
      // Request URL: POST https://sandboxapi.rapyd.net/v1/payments

      // Message body:
      {
      	"amount": 9.99,
      	"currency": "USD",
      	"customer": "cus_8ded332b08966abf51bdc28c106acb7c"
      }
      ```
- - Python

    - ```
      from pprint import pprint

      from utilities import make_request

      payment_body = {
          "amount": 9.99,
          "currency": "USD",
          "customer": "cus_8ded332b08966abf51bdc28c106acb7c"
      }

      create_payment_response = make_request(method='post',
                                             path='/v1/payments',
                                             body=payment_body)
      pprint(create_payment_response)
      ```

### Create Payment Response

[Payment Object](https://docs.rapyd.net/en/payment.md "Payment") describes the fields in the response.

- - Response

    - ```
      {
          "status": {
              "error_code": "",
              "status": "SUCCESS",
              "message": "",
              "response_code": "",
              "operation_id": "4e44e8c1-ee8c-411a-a2de-a2a2ae0122d3"
          },
          "data": {
              "id": "payment_7b4cb9456f1ff73132831fc2e35d88be",
              "amount": 9.99,
              "original_amount": 9.99,
              "is_partial": false,
              "currency_code": "USD",
              "country_code": "US",
              "status": "CLO",

              //      ...

              "customer_token": "cus_8ded332b08966abf51bdc28c106acb7c",
              "payment_method": "card_dbc9f6743ec2ab00486843edfdca42d9",
              "expiration": 0,
              "captured": true,

              //      ...

              "created_at": 1581248060,

              //      ...

              "paid": true,
              "paid_at": 1581248060,

              //      ...

              "payment_method_type": "us_debit_visa_card",
              "payment_method_type_category": "card",

              //      ...

          }
      }
         
      ```

The response (in the sample code above) shows that Rapyd successfully processed the payment based on the amount, currency, and Customer ID. A sum of 9.99 USD (U.S. Dollars) was paid from the customer's card.

You'll always get a similar response. The only difference will be the date and payment ID, and the amount if it's not identical.

You can see that the payment was successful since the  `status` (under `data`) is **CLO** (closed). [Payment Object](https://docs.rapyd.net/en/payment.md "Payment") lists possible values for `status`.

At this point, you can inform the customer that the purchase is complete.

### Account Name Inquiry

Add the `full_name` object to the request to perform an Account Name Inquiry (ANI).The fields for the object include: `first_name`, `middle_name`, and `last_name`. The card scheme matches the cardholder details with the cardholder’s bank information. The ANI is used for fraud management. See [Add Payment Method to Customer](https://docs.rapyd.net/en/add-payment-method-to-customer.md "Add Payment Method to Customer") or [Create Payment](https://docs.rapyd.net/en/create-payment.md "Create Payment") for additional details.

### Add Payment Method to Customer Request

- - Request

    - ```
      // Request URL: POST https://sandboxapi.rapyd.net/v1/customers/payment_methods

      // Message body:
      {
          "type": "gb_visa_card",
          "fields": {
              "number": "4761340000001082",
              "expiration_month": "02",
              "expiration_year": "26",
              "cvv": "111",
              "name": "Jon Doo"
          },
          "full_name": {
              "first_name": "John",
              "middle_name": "Johnson",
              "last_name": "Doe"
          },
          "complete_payment_url": "https://complete.rapyd.net",
          "error_payment_url": "https://error.rapyd.net"
      }
      ```

### Add Payment Method to Customer Response

- - Response

    - ```
      {
          "status": {
              "error_code": "",
              "status": "SUCCESS",
              "message": "",
              "response_code": "",
              "operation_id": "9ce88535-f718-4ea8-a265-554e6957a70e"
          },
          "data": {
              "id": "card_e2bdbf293c33cb2ab87c1014fda5f5f6",
              "type": "gb_visa_card",
              "category": "card",
              "metadata": {},
              "image": "",
              "webhook_url": "",
              "supporting_documentation": "",
              "next_action": "not_applicable",
              "full_name": {
                  "first_name": "John",
                  "middle_name": "Johnson",
                  "last_name": "Doe"
              },
              "account_name_inquiry": {
                  "account_name_inquiry_result": "Partial match",
                  "account_name_inquiry_details": {
                      "first_name": "Match",
                      "last_name": "Match",
                      "middle_name": "No match"
                  }
              },
              "name": "Jon Doo",
              "last4": "1082",
              "acs_check": "unchecked",
              "cvv_check": "unchecked",
              "bin_details": {
                  "type": "DEBIT",
                  "brand": "VISA",
                  "level": "GOLD",
                  "issuer": "INTL HDQTRS-CENTER OWNED",
                  "country": "SG",
                  "bin_number": "476134"
              },
              "expiration_year": "26",
              "expiration_month": "02",
              "fingerprint_token": "ocfp_b8eafaeeea548e97ef23914cffa7154a",
              "network_reference_id": "000000906217732",
              "complete_payment_url": "https://complete.rapyd.net",
              "error_payment_url": "https://error.rapyd.net"
          }
      }
      ```

> **Note:**
>
> Want to see the Rapyd API methods and objects that you'll use? Visit the [Merchant API Reference](https://docs.rapyd.net/en/merchant-api-reference.md "Merchant API Reference") for more technical details.