Skip to main content

Documentation

Get Payment Method Required Fields

Retrieve the required fields for a payment method.

The fields are returned as a list of objects. The name of each field appears in the name field of the response.

Note

  • Rapyd employs a unique variant of regex. Note the following differences:

    • A single backslash matches a backslash as an ordinary character.

    • A backslash followed by an alphabetic character matches a string of two characters.

    • A special character such as \n is indicated as \\n.

  • Some payment methods require a predefined customer with required fields. See also the example on this page.

  • Some payment methods require fields when certain conditions are met.

  • This endpoint replaces the deprecated endpoint - GET /v1/payment_methods/required_fields/:type

    Rapyd no longer supports the deprecated endpoint.

    • type

    • The type of the payment method.

Code Samples
    • .NET

      • 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_type = "us_visa_card" 
        response = make_request(method='get', path=f'/v1/payment_methods/{payment_method_type}/required_fields/') 
        
        pprint(response)
  • /v1/payment_methods/required_fields/:type

  • Card

  • curl - X get https: //sandboxapi.rapyd.net/v1/payment_methods/required_fields/is_mastercard_pos
    -H 'access_key: your-access-key-here'
    -H 'Content-Type: application/json'
    -H 'salt: your-random-string-here'
    -H 'signature: your-calculated-signature-here'
    -H 'timestamp: your-unix-timestamp-here'
    
  • {
        "status": {
            "error_code": "",
            "status": "SUCCESS",
            "message": "",
            "response_code": "",
            "operation_id": "ebde57fa-5df6-495e-af33-1d22f8b6e01a"
        },
        "data": {
            "type": "is_mastercard_pos",
            "fields": [
                {
                    "name": "number",
                    "type": "string",
                    "regex": "",
                    "is_required": true,
                    "instructions": "card number"
                },
                {
                    "name": "number_type",
                    "type": "string",
                    "regex": "(fpan|tpan)",
                    "description": "Determining if number is funding PAN or token PAN",
                    "is_required": false
                },
                {
                    "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"
                }
            ],
            "payment_method_options": [
                {
                    "name": "sca_exemption",
                    "type": "string",
                    "regex": "(low_value|transaction_risk_analysis|authentication_outage|secure_corporate_payments)",
                    "description": "Request a strong customer authentication (SCA) exemption from 3D Secure (3DS) authentication for a merchant of a payment facilitator (PayFac). Specify one exemption type. To enable this feature, contact Rapyd Client Support.",
                    "is_required": false,
                    "is_updatable": false
                }
            ],
            "payment_options": [
                {
                    "name": "capture",
                    "type": "boolean",
                    "regex": "",
                    "description": "Determines when the payment is processed for capture.",
                    "is_required": false,
                    "is_updatable": false
                },
                {
                    "name": "statement_descriptor",
                    "type": "string",
                    "regex": "",
                    "description": "A text description suitable for a customer's payment statement. 5-22 characters.",
                    "is_required": true,
                    "is_updatable": false
                },
                {
                    "name": "ewallet",
                    "type": "string",
                    "regex": "^ewallet_[a-f0-9]{32}$",
                    "description": "ID of the wallet that the money is paid into. String starting with ewallet_.",
                    "is_required": true,
                    "is_updatable": false
                },
                {
                    "name": "initiation_type",
                    "type": "string",
                    "regex": "(card_present|customer_present|installment|moto|recurring|unscheduled)",
                    "description": "This indicates how the transaction was initiated.",
                    "is_required": false,
                    "is_updatable": false
                },
                {
                    "name": "device_id",
                    "type": "string",
                    "regex": "",
                    "description": "A unique id that is assigned by the POS provider and applies to his device. Note that even though a particular device belongs to a certain merchant today and for a certain payment, it might be sending transactions for a different merchant tomorrow.",
                    "is_required": true,
                    "is_updatable": false
                },
                {
                    "name": "payment_advice",
                    "type": "object",
                    "regex": "",
                    "description": "A json field containing information from the incoming pos device that has not already been mapped to other fields in the payment/pmt.",
                    "is_required": true,
                    "is_updatable": false
                }
            ],
            "minimum_expiration_seconds": 0,
            "maximum_expiration_seconds": 2592000
        }
    }
  • Cash

  • curl - X get https: //sandboxapi.rapyd.net/v1/payment_methods/required_fields/us_multiplestoresother_cash
    -H 'access_key: your-access-key-here'
    -H 'Content-Type: application/json'
    -H 'salt: your-random-string-here'
    -H 'signature: your-calculated-signature-here'
    -H 'timestamp: your-unix-timestamp-here'
    
  • {
        "status": {
            "error_code": "",
            "status": "SUCCESS",
            "message": "",
            "response_code": "",
            "operation_id": "b6d91993-c470-4a6c-8786-000731d5f5a7"
        },
        "data": {
            "type": "us_multiplestoresother_cash",
            "fields": [{
                    "name": "number_type",
                    "type": "string",
                    "regex": "(fpan|tpan)",
                    "description": "Determining if number is funding PAN or token PAN",
                    "is_required": false
                }
            ],
            "payment_method_options": [{
                    "name": "tavv",
                    "type": "String",
                    "regex": "",
                    "description": "Token Authentication Verification Value represented as a 20-byte value that is base64 encoded.",
                    "is_required": false,
                    "is_updatable": false
                }
            ],
            "payment_options": [{
                    "name": "customer",
                    "type": "customer",
                    "regex": "",
                    "description": "A 'customer' object or the ID of an existing customer object. All fields listed here as required must appear either directly in the API request or in the saved customer object.",
                    "is_required": true,
                    "is_updatable": false,
                    "required_fields": [{
                            "name": "name",
                            "type": "string",
                            "regex": "^[0-9a-zA-Z.:|?*,!&_ -]{1,128}$",
                            "description": "Customer’s full name",
                            "is_required": true,
                            "is_updatable": false
                        }
                    ]
                }
            ],
            "minimum_expiration_seconds": 0,
            "maximum_expiration_seconds": 1209600
        }
    }
  • Bank Transfer

  • curl - X get https: //sandboxapi.rapyd.net/v1/payment_methods/required_fields/ca_ach_bank
    -H 'access_key: your-access-key-here'
    -H 'Content-Type: application/json'
    -H 'salt: your-random-string-here'
    -H 'signature: your-calculated-signature-here'
    -H 'timestamp: your-unix-timestamp-here'
    
  • {
        "status": {
            "error_code": "",
            "status": "SUCCESS",
            "message": "",
            "response_code": "",
            "operation_id": "405536a3-f634-42a6-9b30-cb3235cc15d2"
        },
        "data": {
            "type": "ca_ach_bank",
            "fields": [
                {
                    "name": "proof_of_authorization",
                    "type": "boolean",
                    "regex": "",
                    "description": "Indicates that the requester has received authorization from the payer.",
                    "is_required": true,
                    "is_updatable": false
                },
                {
                    "name": "account_number",
                    "type": "string",
                    "regex": "^([0-9]){1,12}$",
                    "description": "The payer’s bank account number, up to 12 digits long",
                    "is_required": true,
                    "is_updatable": false
                },
                {
                    "name": "routing_number",
                    "type": "string",
                    "regex": "^([0-9]){9,9}$",
                    "description": "The payer’s bank routing number, 9 digits",
                    "is_required": true,
                    "is_updatable": false
                },
                {
                    "name": "account_currency",
                    "type": "string",
                    "regex": "^([A-Z]){3,3}$",
                    "description": "The currency of the payer’s bank account",
                    "is_required": true,
                    "is_updatable": false
                },
                {
                    "name": "number_type",
                    "type": "string",
                    "regex": "(fpan|tpan)",
                    "description": "Determining if number is funding PAN or token PAN",
                    "is_required": false
                }
            ],
            "payment_method_options": [
                {
                    "name": "statment_descriptor",
                    "type": "string",
                    "regex": "",
                    "description": "A text description that appears in the customer's bank statement.",
                    "is_required": false,
                    "is_updatable": false
                },
                {
                    "name": "tavv",
                    "type": "String",
                    "regex": "",
                    "description": "Token Authentication Verification Value represented as a 20-byte value that is base64 encoded.",
                    "is_required": false,
                    "is_updatable": false
                }
            ],
            "payment_options": [
                {
                    "name": "customer",
                    "type": "customer",
                    "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": true,
                    "is_updatable": false,
                    "required_fields": [
                        {
                            "name": "name",
                            "type": "string",
                            "regex": "^[0-9a-zA-Z ]{1,30}$",
                            "description": "Customer’s full name",
                            "is_required": true,
                            "is_updatable": false
                        }
                    ]
                }
            ],
            "minimum_expiration_seconds": 0,
            "maximum_expiration_seconds": 1209600
        }
    }
  • Customer with Required Fields

  • curl - X get https: //sandboxapi.rapyd.net/v1/payment_methods/required_fields/co_efecty_cash
    -H 'access_key: your-access-key-here'
    -H 'Content-Type: application/json'
    -H 'salt: your-random-string-here'
    -H 'signature: your-calculated-signature-here'
    -H 'timestamp: your-unix-timestamp-here'
    
  • {
        "status": {
            "error_code": "",
            "status": "SUCCESS",
            "message": "",
            "response_code": "",
            "operation_id": "6301279b-a4bc-472a-ada2-5171d8b20423"
        },
        "data": {
            "type": "co_efecty_cash",
            "fields": [
                {
                    "name": "number_type",
                    "type": "string",
                    "regex": "(fpan|tpan)",
                    "description": "Determining if number is funding PAN or token PAN",
                    "is_required": false
                },
                {
                    "name": "email",
                    "type": "string",
                    "regex": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+.[a-zA-Z]{2,}$",
                    "description": "The end-users email address",
                    "is_required": true,
                    "is_updatable": false
                }
            ],
            "payment_method_options": [
                {
                    "name": "tavv",
                    "type": "String",
                    "regex": "",
                    "description": "Token Authentication Verification Value represented as a 20-byte value that is base64 encoded.",
                    "is_required": false,
                    "is_updatable": false
                }
            ],
            "payment_options": [
                {
                    "name": "customer",
                    "type": "customer",
                    "regex": "",
                    "description": "ID of a customer object, a string starting with ‘cus_'.                             If the customer object does not exist yet, use 'Create Customer’.",
                    "is_required": "false",
                    "is_updatable": false,
                    "required_fields": [
                        {
                            "name": "name",
                            "type": "string",
                            "regex": "^[0-9a-zA-Z.:|?*,!&_ -]{1,128}$",
                            "description": "Customer’s full name",
                            "is_required": true,
                            "is_updatable": false
                        }
                    ]
                }
            ],
            "minimum_expiration_seconds": 0,
            "maximum_expiration_seconds": 1209600
        }
    }