--- title: "Get Payment Method Required Fields" source_url: https://docs.rapyd.net/en/get-payment-method-required-fields.html lang: en --- # 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. > - The code samples include successful requests (200) and bad requests (400). > > - For error messages that appear due to bad requests (400), see: > > - [General Errors](https://docs.rapyd.net/en/general-errors.md "General Errors") > - [Payment Method Errors](https://docs.rapyd.net/en/payment-method-errors.md "Payment Method Errors") > - For information about unauthorized request (401) and other authentication errors, see [Troubleshooting Authentication and Authorization Errors](https://docs.rapyd.net/en/troubleshooting-authentication-and-authorization-errors.md "Troubleshooting Authentication and Authorization Errors"). ### Parameters ### Request Path Parameters - - payment_method_type - The type of the payment method. String with 2-letter prefix for the country and suffix representing the payment method category. ### Request Header Parameters - - access_key - Unique access key provided by Rapyd for each authorized user. See [Developers](https://docs.rapyd.net/en/developers.md "Developers"). - - Content-Type - Indicates that the data appears in JSON format. Set to **application/json**. - - salt - Random string. Recommended length: 8-16 characters. - - signature - Signature calculated for each request individually. See [Request Signatures](https://docs.rapyd.net/en/request-signatures.md "Request Signatures"). - - timestamp - Timestamp for the request, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds). ### Response Parameters - - fields - Contains several fields that are used in creating the specific payment method. These fields always contain the same value for a payment method, so they are included in the payment method object. To determine what fields you need for the payment method, see [Get Payment Method Required Fields](https://docs.rapyd.net/en/get-payment-method-required-fields.md "Get Payment Method Required Fields"). For more fields, see the `payment_options` field in the response to [List Payment Methods by Country](https://docs.rapyd.net/en/list-payment-methods-by-country.md "List Payment Methods by Country"). The `fields` object can contain only fields that are explicitly described as either required or optional. A field with an unknown name will throw an error. - - conditions - Conditions that define whether the field is required. - - description - Text explanation of the condition. - - element_name - Name of the field that is conditionally required. - - operator - Operator for evaluating the condition. When the condition evaluates to **true**, the field is required. One of the following: - **$eq** - Equal to - The value in the field is equal to the `threshold_value`. - **$ne** - Not equal to - The value in the field is not equal to the `threshold_value`. - **$gt** - Greater than - The value in the field is greater than the `threshold_value`. - **$lt** - Less than - The value in the field is less than the `threshold_value`. - **$gte** - Greater than or equal to - The value in the field is greater than the `threshold_value`. - **$lte** - Less than or equal to - The value in the field is less than the `threshold_value`. - **$in** - In - The value in the field is equal to any of the values in the `threshold_value` array. - **$nin** - Not in - The value in the field is not equal to any of the values in the `threshold_value` array. - - threshold_value - Value to compare with. Can be a string or an array of strings. - - instructions - Instructions for the field. - - is_required - Indicates whether the field is required for using the payment method. - **true** - Required. - **false** - Optional. - - name - Name of the field. - - regex - A regular expression that defines the format when `type` is **string**. > **Note:** > > Rapyd uses a unique variant of the regex standard. See - - type - Type of the field. One of the following values: - **boolean** - **number** - **string** - - maximum_expiration_seconds - The maximum time (in seconds) that the merchant can set for completing the payment. Relevant when `is_expirable` is **true**. - - minimum_expiration_seconds - The minimum time (in seconds) that the merchant can set for completing the payment. Relevant when `is_expirable` is **true**. - - payment_method_options - Additional fields required for the payment method. These values might vary from one use to the next, so they are not saved as part of the payment method object. In the request to create payment, these fields appear in the `payment_method_options` object. - - payment_options - Additional fields of the `payment` object which are required for the payment. In the request to create payment, these fields appear in the root of the body of the request. To determine the fields, run [Get Payment Method Required Fields](https://docs.rapyd.net/en/get-payment-method-required-fields.md "Get Payment Method Required Fields"). - - type - Type of the payment method. For example, **it_visa_card**. To get a list of payment methods for a country, use [List Payment Methods by Country](https://docs.rapyd.net/en/list-payment-methods-by-country.md "List Payment Methods by Country"). ### Code Samples - - .NET - ```csharp 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 - ```javascript const makeRequest = require('/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 /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 - ```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 curl -X get 'https://sandboxapi.rapyd.net/v1/payment_methods/is_mastercard_card/required_fields' \ -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' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "c30bfdf2-bd56-4c1f-a19d-2272e06e5c04" }, "data": { "type": "is_mastercard_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": true, "instructions": "card cvv" }, { "name": "name", "type": "string", "regex": "", "is_required": true, "instructions": "card holder name" }, { "name": "network_reference_id", "type": "string", "regex": "", "description": "Network Reference Id", "is_required": false }, { "name": "recurrence_type", "type": "string", "regex": "(recurring|installment|unscheduled)", "description": "Indicates how the token will be used. Required when this payment method is added to the customer profile. Values: 'unscheduled'=Individual unrelated payments. 'installment'=Regular payments for a defined number of payment cycles. 'recurring'=Regular payments for an indefinite period.", "is_required": false, "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": "3d_required", "type": "boolean", "regex": "", "description": "Allows the client to determine whether the customer is required to complete 3DS authentication for the transaction", "is_required": false, "is_updatable": false }, { "name": "3d_version", "type": "String", "regex": "(1.0.2|2.1.0|2.2.0)", "description": "3D Secure version of the transaction.", "is_required": false, "is_updatable": false }, { "name": "cavv", "type": "String", "regex": "", "description": "Cardholder Authentication Verification Value represented as a 20-byte value that is base64 encoded.", "is_required": false, "is_updatable": false }, { "name": "eci", "type": "String", "regex": "(01|02|05|06|07|08)", "description": "Electronic Commerce Indicator (ECI) from MPI Plugin(3-D Secure 1.0) or 3DS Server(3-D Secure 2.0).", "is_required": false, "is_updatable": false }, { "name": "xid", "type": "String", "regex": "", "description": "3D Secure XID, Base64 encoded.Required for VISA 1.0", "is_required": false, "is_updatable": false }, { "name": "ds_trans_id", "type": "String", "regex": "", "description": "The Directory Server (DS) Transaction ID. Required Mastercard 2.0.", "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 }, { "name": "cvv", "type": "string", "regex": "", "description": "Card CVV for Subsequent Payments", "is_required": false, "is_updatable": false }, { "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": "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 }, { "name": "initiation_type", "type": "string", "regex": "(customer_present|installment|moto|recurring|unscheduled)", "description": "This indicates how the transaction was initiated", "is_required": false, "is_updatable": false } ], "minimum_expiration_seconds": 0, "maximum_expiration_seconds": 604800 } } ``` - Card (POS) - ```curl curl -X get 'https://sandboxapi.rapyd.net/v1/payment_methods/is_mastercard_pos/required_fields' \ -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' ``` - ```json { "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 curl -X get 'https://sandboxapi.rapyd.net/v1/payment_methods/co_efecty_cash/required_fields' \ -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' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "b07e2d2b-aa5c-4ad0-a00a-d0aa61998467" }, "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 } } ``` - Bank Transfer - ```curl curl -X get 'https://sandboxapi.rapyd.net/v1/payment_methods/mx_spei_bank/required_fields' \ -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' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "ced5ea46-745b-4ef3-b0dc-d76450983e6a" }, "data": { "type": "mx_spei_bank", "fields": [ { "name": "amount", "type": "string", "regex": "[0-9]*.\\.[0-9]{2}", "description": "Must have two decimal places.", "is_required": false, "is_updatable": false }, { "name": "description", "type": "string", "regex": "[a-zA-z]{0,49}", "description": "Description of the payment transaction", "is_required": false, "is_updatable": false }, { "name": "expiration", "type": "string", "regex": "", "description": "End of the time allowed for customer to make this payment, in Unix time.", "is_required": false, "is_updatable": false }, { "name": "metadata", "type": "object", "regex": "", "description": "A JSON object defined by the Rapyd partner.", "is_required": false, "is_updatable": false } ], "payment_method_options": [], "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 }, { "name": "email", "type": "string", "regex": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$", "description": "The end-user's email address", "is_required": true, "is_updatable": false } ] }, { "name": "ewallet", "type": "string", "regex": "", "description": "Make sure to pass an ewallet", "is_required": false, "is_updatable": false } ], "minimum_expiration_seconds": 0, "maximum_expiration_seconds": 1209600 } } ``` - Bank Redirect - ```curl curl -X get 'https://sandboxapi.rapyd.net/v1/payment_methods/co_bbva_colombia_bank/required_fields' \ -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' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "628006be-c414-458f-8e2d-436e882cf734" }, "data": { "type": "co_bbva_colombia_bank", "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": [], "minimum_expiration_seconds": 0, "maximum_expiration_seconds": 1209600 } } ``` - Customer with Required Fields - ```curl curl -X get 'https://sandboxapi.rapyd.net/v1/payment_methods/mx_paycash_cash/required_fields' \ -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' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "1df0d3ec-6dbf-4148-ad10-421b4ee2c7dc" }, "data": { "type": "mx_paycash_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": "expiration", "type": "string", "regex": "^[0-9]{10}$", "is_required": false }, { "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": 2678400 } } ``` - Bad Request - Invalid Payment Method Type - ```curl curl -X get 'https://sandboxapi.rapyd.net/v1/payment_methods/us_cash_and_checks/required_fields' \ -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' ``` - ```json { "status": { "error_code": "INVALID_PAYMENT_METHOD_TYPE", "status": "ERROR", "message": "The request tried to perform an operation that requires a payment method type, but the type was not recognized. The request was rejected. Corrective action: To find payment method types for a country, use 'List Payment Methods by Country'.", "response_code": "INVALID_PAYMENT_METHOD_TYPE", "operation_id": "310a7a38-1583-49fc-841e-f9e572932c21" } } ```