Card on File

Store customer payment information for recurring and subscription purchases

Streamline the card on file process and lower your PCI-Compliance burden by generating a secure token for customers who opt to save their payment information with your business.

How it works

Note: For illustration purposes, we will use the US and USD as an example for country and currency.

Find Available Payment Methods

Decide the payment methods you will accept so that your customer can specify their payment methods on your payment page.

To decide which payment methods you will accept, use List Payment Methods by Country with the following 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 URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/country?country=US&currency=USD

// Message body absent
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);
            }
        }
    }
}
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
$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";
}
?>
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 Object describes the fields in the response.

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "cfa35a73-aa0b-4e7e-839c-4c3b6149edd7"
    },
    "data": [{
            "type": "us_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 with the following parameter.

Path Parameter

Description

type

Enter us_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 URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/required_fields/us_visa_card

// Message body absent
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/required_fields/{type}");

                Console.WriteLine(result);
            }
            catch (Exception e)
            {
                Console.WriteLine("Error completing request: " + e.Message);
            }
        }
    }
}
const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

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

    console.log(result);
  } catch (error) {
    console.error('Error completing request', error);
  }
}
<?php
$path = $_SERVER['DOCUMENT_ROOT'];
$path .= "/<path-to-your-utility-file>/utilities.php";
include($path);

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

from utilities import make_request

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

Get Payment Method Required Fields Response

Payment Method Object describes the fields in the 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 with the following parameters:

Body Parameter

Description

name

Enter Jane Doe as the customer name.

payment_method

Enter an object with the following fields:
type - us_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 URL: POST https://sandboxapi.rapyd.net/v1/customers

// Message body: 
{
    "name": "Jane Doe",
    "payment_method": {
        "type": "us_visa_card",
        "fields": {
            "number": "4111111111111111",
            "expiration_month": "10",
            "expiration_year": "20",
            "cvv": "123",
            "name": "Jane Doe"
        }
    }
}
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 describes the fields in the 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_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 with the following 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 (as shown in this example code below).

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

// Message body:
{
    "amount": 9.99,
    "currency": "USD",
    "customer": "cus_8ded332b08966abf51bdc28c106acb7c"
}
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 describes the fields in the 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_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 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 lists possible values for status.

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

📘

Looking for more in-depth technical information?

Want to see the Rapyd API methods and objects that you'll use?
Visit the Rapyd API Reference Documentation for more technical details.


Updated about 17 hours ago



Card on File


Store customer payment information for recurring and subscription purchases

Suggested Edits are limited on API Reference Pages

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