Skip to main content

Documentation

Creating a Card Payment

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

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.

As a Payment Facilitator (PayFac) your submerchant can collect funds from a card payment, and you can direct the funds to your client wallet. The collected funds are settled via the Payment Facilitator’s client wallet.

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

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.

Use Case

The submerchant collects a card payment on their business website. They notify the PayFac, who initiates a card payment via the Rapyd Collect API. The funds are collected via the checkout process, and the funds are directed to the PayFac's client wallet, where the funds are then settled.

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

creating-card-payment-payfac-flow-1.png
  1. The customer completes the card payment in checkout on your submerchant’s website.

  2. You ask Rapyd to process the card payment.

  3. Rapyd processes the payment and sends the response and webhook back to you.

  4. You display your purchase success page to the customer.

  5. The collected funds are directed to the PayFac client wallet.

As a Payment Facilitator, you can create a card payment and direct the funds that the submerchant collects to your client wallet. The captured funds are then settled via the client wallet.

When using Create Payment, you must provide the submerchant’s ewallet ID in the merchant_ewallet field. For the ewallet field, you can either provide the ewallet ID of your PayFac client wallet, or omit the field from the payment request.

Decide the card payment types you'll accept in a chosen country. Use List Payment Methods by Country with the following parameters:

  • GB and GBP are used for country and currency in the sample codes below. GB Visa Card as the payment type.

Description of Query Parameters

Query Parameter

Description

country

Enter GB as the country code.

currency

Enter GBP as the currency code.

List Payment Methods by Country Request
    • Request

      • // Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/country?country=GB&currency=GBP
        
        // Message body absent
    • .NET Core

      • using System;
        
        namespace RapydApiRequestSample
        {
            class Program
            {
                static void Main(string[] args)
                {
                    try
                    {
                        string result = RapydApiRequestSample.Utilities.MakeRequest("GET", "/v1/payment_methods/country?country=GB&currency=GBP");
        
                        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=GB&currency=GBP');
        
            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=GB&currency=GBP');
            var_dump($object);
        } catch (Exception $e) {
            echo "Error: $e";
        }
        ?>
    • Python

      • from pprint import pprint
        
        from utilities import make_request
        
        country = 'GB'
        currency = 'GBP'
        results = make_request(method='get',
                               path=f'/v1/payment_methods/country?country={country}&currency={currency}')
        pprint(results)
        
List Payment Methods by Country Response
    • Response

      • {
            "status": {
                "error_code": "",
                "status": "SUCCESS",
                "message": "",
                "response_code": "",
                "operation_id": "cfa35a73-aa0b-4e7e-839c-4c3b6149edd7"
            },
            "data": [{
                   "type": "gb_visa_card",
                    "name": "Visa",
                    "category": "card",
                    "image": "https://iconslib.rapyd.net/checkout/gb_visa_card.png",
                    "country": "GB",
                    "payment_flow_type": "",
                    "currencies": [
                        "AED",
                        "AUD",
                        "BGN",
                        "BOB",
                        "BRL",
                        "CAD",
                        "CHF",
                        "CNY",
                        "COP",
                        "CZK",
                        "DKK",
                        "EUR",
                        "GBP",
                        "GEL",
                        "HKD",
                        "HRK",
                        "HUF",
                        "IDR",
                        "ILS",
                        "INR",
                        "ISK",
                        "JPY",
                        "KZT",
                        "MDL",
                        "MXN",
                        "MYR",
                        "NOK",
                        "NZD",
                        "PEN",
                        "PHP",
                        "PLN",
                        "RON",
                        "RSD",
                        "RUB",
                        "SEK",
                        "SGD",
                        "THB",
                        "TRY",
                        "TWD",
                        "UAH",
                        "USD",
                        "UYU",
                        "ZAR"
                    ],
                    "status": 1,
                    "is_cancelable": true,
                    "payment_options": [
                        {
                            "name": "description",
                            "type": "string",
                            "regex": "",
                            "description": "the description field must be filled in.",
                            "is_required": false,
                            "is_updatable": false
                        },
                        {
                            "name": "capture",
                            "type": "boolean",
                            "regex": "",
                            "description": "Determines when the payment is processed for capture.",
                            "is_required": false,
                            "is_updatable": false
                        },
                        {
                            "name": "complete_payment_url",
                            "type": "string",
                            "regex": "",
                            "description": "the complete_payment_url field must be filled in.",
                            "is_required": true,
                            "is_updatable": false
                        },
                        {
                            "name": "error_payment_url",
                            "type": "string",
                            "regex": "",
                            "description": "the error_payment_url field must be filled in.",
                            "is_required": true,
                            "is_updatable": false
                        },
                        {
                            "name": "customer",
                            "type": "string",
                            "regex": "",
                            "description": "ID of a customer object, a string starting with ‘cus_‘. The customer object must contain the fields listed as required, and can contain additional fields listed here.If the customer object does not exist yet, use ‘Create Customer‘",
                            "is_required": false,
                            "is_updatable": false
                        }
                    ],
                    "is_expirable": true,
                    "is_online": false,
                    "is_refundable": true,
                    "minimum_expiration_seconds": 600,
                    "maximum_expiration_seconds": 604800,
                    "virtual_payment_method_type": "card",
                    "is_virtual": false,
                    "multiple_overage_allowed": false,
                    "amount_range_per_currency": [
                        {
                            "currency": "AED",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "AUD",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "BGN",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "BOB",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "BRL",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "CAD",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "CHF",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "CNY",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "COP",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "CZK",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "DKK",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "EUR",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "GBP",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "GEL",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "HKD",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "HRK",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "HUF",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "IDR",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "ILS",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "INR",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "ISK",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "JPY",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "KZT",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "MDL",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "MXN",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "MYR",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "NOK",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "NZD",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "PEN",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "PHP",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "PLN",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "RON",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "RSD",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "RUB",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "SEK",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "SGD",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "THB",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "TRY",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "TWD",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "UAH",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "USD",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "UYU",
                            "maximum_amount": null,
                            "minimum_amount": null
                        },
                        {
                            "currency": "ZAR",
                            "maximum_amount": null,
                            "minimum_amount": null
                        }
                    ],
                    "is_tokenizable": false,
                    "supported_digital_wallet_providers": [
                        "google_pay"
                    ],
                    "is_restricted": false,
                    "supports_subscription": true
                },
                }
            ]
        }
        

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.

Description of Path Parameters

Path Parameter

Description

type

Enter gb_visa_card as the payment method type.

Get Payment Method Required Fields Request

Request a set of required fields for a Visa card.

    • Request

      • // Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/gb_visa_card/required_fields
        
        // Message body absent
    • .NET Core

      • using System;
        
        namespace RapydApiRequestSample
        {
            class Program
            {
                static void Main(string[] args)
                {
                    try
                    {
                        string result = RapydApiRequestSample.Utilities.MakeRequest("GET", "/v1/payment_methods/us_visa_card/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)
        
Get Payment Method Required Fields Response

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

  • number

  • expiration_month

  • expiration_year

  • name

  • CVV

    • Response

      • {
            “status”: {
                “error_code”: “”,
                “status”: “SUCCESS”,
                “message”: “”,
                “response_code”: “”,
                “operation_id”: “598b1a00-e302-4037-b0ef-aac895974e9e”
            },
            “data”: {
                “type”: “gb_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
            }
        }

As a Payment Facilitator, you can create a card payment and direct the funds that the submerchant collects to your client wallet. The captured funds are then settled via the client wallet.

You must provide the submerchant’s ewallet ID in the merchant_ewallet field. For the ewallet field, you can either provide the ewallet ID of your PayFac client wallet, or omit the field from the payment request.

Description of Body Parameters

Body Parameter

Description

Required

payment_method

Enter an object with the following fields:type - gb_visa_card fields - Enter an object with the following fields: number - 4111111111111111 expiration_month - 10 expiration_year - 29 cvv - 123

No

amount

The amount of the payment, in units of the currency defined in currency. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 4217:2015.

Enter 19.22 as the payment amount.

Yes

currency

The currency of the transaction. Three-letter ISO 4217 code.

Enter GBP as the currency code.

Yes

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.

No

complete_payment_url

URL where the customer is redirected after successfully completing an operation on a hosted page. Does not support localhost URLs.

Yes

error_payment_url

URL where the customer is redirected if an error occurs during or after an operation on a hosted page. Does not support localhost URLs.

Yes

ewallet

ID of the wallet that the money is paid into. String starting with ewallet_.

Default value: ID of the default client wallet.

Note: Enter the PayFac’s client wallet ID.

No

merchant_ewallet

ID of the wallet for the submerchant. String starting with ewallet_.

Yes

Create Payment Request

See Create Payment for more details.

    • Request

      • // Request URL: POST https://sandboxapi.rapyd.net/v1/payments
        
        // Message body: 
        {
            "amount": "19.20",
            "currency": "USD",
            "capture": true,
            "complete_payment_url": "https://www.google.com",
            "error_payment_url": "https://www.error.com",
            "merchant_ewallet": "ewallet_42dbfb7fd7638a95d6ba084ac07dec1e",
            "statement_descriptor": "testing_payfac",
            "payment_method": {
            "type": "gb_visa_card",
            "fields": {
            "number": "4111111111111111",
            "expiration_month": "10",
            "expiration_year": "29",
            "cvv": "123",
            "name": "Jon Dud"
            }
            },
            "payment_method_options": {
            "3d_required": true
            
            }
        }
Create Payment Response
    • Response

      • {
            "status": {
            "error_code": "",
            "status": "SUCCESS",
            "message": "",
            "response_code": "",
            "operation_id": "23e5d6e0-bd2d-4fed-8e93-1796a13b95cb"
        
            },
            "data": {
                "id": "payment_abe17edaededa707ce9f93cdced4a5e6",
                "amount": 19.2,
                "original_amount": 19.2,
                "is_partial": false,
                "currency_code": "USD",
                "country_code": "GB",
                "status": "CLO",
                "description": "",
                "merchant_reference_id": "",
                "customer_token": "cus_c9436fb62eb6709500591bbb38b78485",
                "payment_method": null,
                "payment_method_data": {
                    "id": null,
                    "type": "gb_visa_card",
                    "category": "card",
                    "metadata": null,
                    "image": "",
                    "webhook_url": "",
                    "supporting_documentation": "",
                    "next_action": "not_applicable",
                    "name": "Jon Dud",
                    "last4": "1111",
                    "acs_check": "pass",
                    "cvv_check": "pass",
                    "bin_details": {
                        "type": "CREDIT",
                        "brand": "VISA",
                        "level": null,
                        "issuer": "JPMORGAN CHASE BANK, N.A.",
                        "country": "US",
                        "bin_number": "411111"
                    },
                    "expiration_year": "29",
                    "expiration_month": "10",
                    "fingerprint_token": "ocfp_7ec6034df2f77d10a6af604c93926d30",
                    "payment_account_reference": "V0010013018036782991622965076"
            },
            "auth_code": "916048",
            "expiration": 1747094400,
            "captured": true,
            "refunded": false,
            "refunded_amount": 0,
            "receipt_email": "",
            "redirect_url": "",
            "complete_payment_url": "https://www.google.com",
            "error_payment_url": "https://www.error.com",
            "receipt_number": "",
            "flow_type": "",
            "address": null,
            "statement_descriptor": "",
            "transaction_id": "",
            "created_at": 1746519705,
            "metadata": {},
            "failure_code": "",
            "failure_message": "",
            "paid": true,
            "paid_at": 1746519707,
            "dispute": null,
            "refunds": null,
            "order": null,
            "outcome": null,
            "visual_codes": {},
            "textual_codes": {},
            "instructions": [],
            "ewallet_id": "ewallet_5f9cb598369042adae6d1ce4be76e86e",
            "ewallets": [
                {
                    "ewallet_id": "ewallet_5f9cb598369042adae6d1ce4be76e86e",
                    "amount": 19.2,
                    "percent": 100,
                    "refunded_amount": 0
                }
            ],
            "payment_method_options": {},
            "payment_method_type": "gb_visa_card",
            "payment_method_type_category": "card",
            "fx_rate": 1,
            "merchant_requested_currency": null,
            "merchant_requested_amount": null,
            "fixed_side": "",
            "payment_fees": null,
            "invoice": "",
            "escrow": null,
            "group_payment": "",
            "cancel_reason": null,
            "initiation_type": "customer_present",
            "mid": "mid_af321954a7f11687adf2a2baa5cb383a",
            "next_action": "not_applicable",
            "error_code": "",
            "remitter_information": {},
            "save_payment_method": true,
            "merchant_advice_code": null,
            "merchant_advice_message": null,
            "merchant_ewallet": "ewallet_42dbfb7fd7638a95d6ba084ac07dec1e"
            }
        }

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