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.

A typical use case may follow these steps:

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

Multiple Payment Methods

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

Select the card to use for the payment.
Click the pencil icon to edit the card details.
Optional: You can update the card details. Click Update to save the changes.
Click Place Your Order.
Redirect to the Payment Success page.
Click Finish.

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

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.
Your website asks Rapyd to create a Customer ID.
Then your website asks Rapyd to create a $0 Auth payment to validate the card using the Customer ID.
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.

Step 2: Process First-Time Payment

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

Step 3: Start a Subsequent Purchase

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

Step 4: Process a Subsequent Payment

The website back end asks Rapyd to process the customer's payment, specifying the amount, currency, and Customer ID.
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.
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 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 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 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 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 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

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.

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 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 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 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 API Reference for more technical details.

In this section:

Documentation

Card on File

Multiple Payment Methods

Card on File Checkout

Card on File Workflow

Step 1: Store a Customer Card

Note

Step 2: Process First-Time Payment

Step 3: Start a Subsequent Purchase

Step 4: Process a Subsequent Payment

How Card on File Works

Find Available Payment Methods

List Payment Methods by Country Request

List Payment Methods by Country Response

Note

Find Required Fields for the Payment Method

Get Payment Method Required Fields Request

Get Payment Method Required Fields Response

Create the Customer ID and Store the Card

Create Customer Request

Create Customer Response

Process the Payment

Create Payment Request

Create Payment Response

Looking for More In-Depth Technical Information?

Search results