Rapyd Documentation and API

Card Payments

Securely accept international and local, credit and debit card payments across the globe.

Overview

A card payment is initiated when your customer selects card payment from your list of payment methods, or enters their card details into your card form fields.

A card payment initiation consists of the following:

  • authorization amount.
  • successful capture of the authorized transaction.

By default, all card payments are captured immediately after authorization, but sometimes, a post-capture process can be used to put funds on hold.

How it works

The card payment process below explains how to:

  • add local and international card payments to your checkout.
  • complete a single card payment authorization.
  • capture the transaction.

📘

PCI Certification

Clients with PCI-DSS certification can handle personal identifying information.

Step 1: Decide the Card Payment Types You'll Accept in a Chosen Country

Find Available Payment Methods

Use List Payment Methods by Country with the following parameters:

Note: For illustration purposes, we will use the US and USD for country and currency in the sample codes below.

Query Parameter

Description

country

Enter US as the country code.

currency

Enter USD as the currency code.

List Payment Methods by Country request

// 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 result = RapydApiRequestSample.Utilities.MakeRequest("GET", "/v1/payment_methods/country?country=US&currency=USD");

                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 Type 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
        }
    ]
}

Get the Required Fields for the Payment Method Types

Use the Get Payment Method Required Fields with the following parameter:

The data section of this response shows that a Visa card is an acceptable payment method type.

Note: A real response usually lists many payment types.

Path Parameter

Description

type

Enter us_visa_card as the payment method type.

Get Payment Method Required Fields request

Request a 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 result = RapydApiRequestSample.Utilities.MakeRequest("GET", "/v1/payment_methods/required_fields/us_visa_card");

                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.

The response below shows that for a US Visa card, the customer must fill in:

  • number
  • expiration_month
  • expiration_year
  • name
  • CVV
{
    “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
    }
}

Step 2: Accept a Card Payment From a Customer

📘

For 3DS flow see Card Payment with 3DS Verification

Initiate your Customer's Payment

Rapyd uses the Create Payment object to serve as the intent to collect a payment from your customer:

Body Parameter

Description

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 - 21
  ● cvv - 123

amount

Enter 9.99 as the payment amount.

currency

Enter USD as the currency code.

capture

Enter true as the value. This tells Rapyd to collect the payment for you right away. If 'false', a hold will be put on the card and the funds will not be captured until the status is updated.

Submit Payment to Rapyd

Rapyd processes your customer's card payment and immediately captures the funds for you (in the sample code below, the amount used is $9.99).

Create Payment request

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

// Message body: 
{
   "amount": 9.99,
   "currency": "USD",
   "payment_method": {
       "type": "us_visa_card",
       "fields": {
           "number": "4111111111111111",
           "expiration_month": "10",
           "expiration_year": "21",
           "cvv": "123"
       }
   },
  "error_payment_url": "https://error_example.net",
  "capture": true
}

using System;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                string payment = @"{""amount"":9.99,""currency"":""USD"",""payment_method"":{""type"":""us_visa_card"",""fields"":{""number"":""4111111111111111"",""expiration_month"":""10"",""expiration_year"":""21"",""cvv"":""123""}},""error_payment_url"":""https:error_example.net"",""capture"":true}";

                string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/payments", payment);

                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 body = {
      amount: 9.99,
      currency: 'USD',
      payment_method: {
        type: 'us_visa_card',
        fields: {
          number: '4111111111111111',
          expiration_month: '10',
          expiration_year: '21',
          cvv: '123'
        }
      },
      capture: true
    };
    const result = await makeRequest('POST', '/v1/payments', body);

    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);

$body = [
    'amount' => 9.99,
    'currency' => 'USD',
    'payment_method' => [
        'type' => 'us_visa_card',
        'fields' => [
            'number' => '4111111111111111',
            'expiration_month' => '10',
            'expiration_year' => '21',
            'cvv' => '123']
    ],
    'error_payment_url' => urldecode('https://error_example.net'),
    'capture' => true
];

try {
    $object = make_request('post', '/v1/payments', $body);
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>

from pprint import pprint

from utilities import make_request

payment_body = {
    'amount': 9.99,
    'currency': 'USD',
    'payment_method': {
        'type': 'us_visa_card',
        'fields': {
            'number': '4111111111111111',
            'expiration_month': '10',
            'expiration_year': '21',
            'cvv': '123'
        }
    },
    'error_payment_url': 'https://error_example.net',
    'capture': True
}

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

Create Payment Response

The Payment Object describes the fields in the response.

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "d036678e-79f3-45fd-ac9b-54277a0f1887"
    },
    "data": {
        "id": "payment_476c494ba433285e3468ddd3d12e6287",
        "amount": 9.99,
        "original_amount": 9.99,
        "is_partial": false,
        "currency_code": "USD",
        "country_code": "US",
        "status": "CLO",

        //     ...

        "customer_token": "cus_f7f818996c5cff475839fc2b5edf985a",
        "payment_method": "card_1bdfe1b70af665004da098f8bd859282",
        "expiration": 0,
        "captured": true,

        //     ...

        "error_payment_url": "https://error_example.net",

        //     ...

        "created_at": 1581235148,

        //     ...

        "paid": true,
        "paid_at": 1581235148,

        //     ...

        "payment_method_type": "us_visa_card",
        "payment_method_type_category": "card",

        //     ...

    }
}

The response shows that Rapyd successfully processed the payment based on the amount, currency, and payment method.

The payment is successful since the status (under data) is CLO (closed).

Note: Payment Object lists possible values for status.

You can now notify your customer that the purchase is complete.

Updated about 17 hours ago

What's Next

Card Payment with 3DS Verification
Card on File

Card Payments

Securely accept international and local, credit and debit card payments across the globe.

Suggested Edits are limited on API Reference Pages

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