--- title: "Get Payout Required Fields" source_url: https://docs.rapyd.net/en/get-payout-required-fields.html lang: en --- # Get Payout Required Fields Retrieve the fields required to use a payout method type. The fields are returned as an array of objects. The name of each field appears in the `name` field of each object. Use this information for [Create Payout](https://docs.rapyd.net/en/create-payout.md "Create Payout") , [Create Sender](https://docs.rapyd.net/en/create-sender.md "Create Sender"), and [Create Beneficiary](https://docs.rapyd.net/en/create-beneficiary.md "Create Beneficiary"). > **Note:** > > - The fields returned by this method are required when you create a payout. If you create a payout with a sender or beneficiary that was created previously, you are responsible for choosing a sender and beneficiary that have all the fields required by the payout method. > - This endpoint replaces the deprecated endpoint - `GET /v1/payouts/:payout_method_type/details` > > 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") > - [Payout Errors](https://docs.rapyd.net/en/payout-errors.md "Payout 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 - - payout_method_type - The type of the payout method. Set to the name of a payout method listed in the response to [List Payout Method Types](https://docs.rapyd.net/en/list-payout-method-types.md "List Payout Method Types"). The two-letter prefix must match the beneficiary country code. ### Request Query Parameters - - beneficiary_country - Country of the beneficiary. Two-letter ISO 3166-1 ALPHA-2 code. - - beneficiary_entity_type - Type of entity for the beneficiary. One of the following values: - **company** - **individual** - - payout_amount - Amount of the payout, in units of the currency that the beneficiary is receiving. Decimal. - - payout_currency - Currency received by the beneficiary. Three-letter ISO 4217 code. - - sender_country - Country of the sender. Two-letter ISO 3166-1 ALPHA-2 code. - - sender_currency - Currency that the sender is paying with. Three-letter ISO 4217 code. - - sender_entity_type - Type of entity for the sender. One of the following values: - **company** - **individual** ### 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 - - batch_file_header - Contains a comma-separated list of the headers required for creating a batch file. Relevant for creating a mass payout through the Client Portal. See [Mass Payouts](https://docs.rapyd.net/en/mass-payouts.md "Mass Payouts"). - - beneficiary_country - Country of the beneficiary. Two-letter ISO 3166-1 ALPHA-2 code. - - beneficiary_entity_type - Filters the type of entity for the beneficiary. One of the following values: - **company** - **individual** - - beneficiary_required_fields - Describes the fields required for the beneficiary when you create a payout. Array of objects. - - description - Text description of the field. - - name - Name of the field. - - is_required - Whether the field is always required for this payout method. - - regex - A regular expression that defines the valid values for the field. - - type - Type of data for the field. - - image - URL of an image that the merchant can use to represent the payout method. - - is_cancelable - Indicates whether the payout can be canceled. Relevant when `category` is **cash**. - - is_expirable - Indicates whether the payout expires if not completed. Relevant when `category` is **cash**. - - is_location_specific - Indicates whether the payout must be made at a specific physical location. Relevant when `category` is **cash**. - - is_online - Indicates whether the payout is made automatically, without any action by the beneficiary. - - maximum_amount - Maximum amount supported by this payout method for the indicated currency. Decimal. - - maximum_expiration_seconds - The maximum time (in seconds) that the merchant can set for completing the payout. Relevant when `is_expirable` is **true**. - - minimum_amount - Minimum amount supported by this payout method for the indicated currency. Decimal number. - - minimum_expiration_seconds - The minimum time (in seconds) that the merchant can set for completing the payout. Relevant when `is_expirable` is **true**. - - payout_currency - Currency received by the beneficiary. Three-letter ISO 4217 code. - - payout_method_type - The type of payout method. The two-letter prefix must match the beneficiary country code. - - payout_options - Additional fields that are required to use a payout method type. Array of objects. - - description - Text description of the field. - - name - Name of the field. - - is_required - Whether the field is always required for this payout method. - - regex - A regular expression that defines the valid values for the field. - - type - Type of data for the field. - - sender_country - Country of the sender. Two-letter ISO 3166-1 ALPHA-2 code. ***** means 'all countries'. - - sender_currency - Currency that the sender is paying with. Three-letter ISO 4217 code. ***** means 'all currencies'. - - sender_entity_type - Filters the type of entity for the sender. One of the following: - **company** - **individual** - - sender_required_fields - Describes the fields required for the sender when you create a payout. Array of objects. - - allowed_values - List of values for the field. Array of strings. - - description - Text description of the field. - - name - Name of the field. - - is_required - Whether the field is always required for this payout method. - - regex - A regular expression that defines the valid values for the field. - - type - Type of data for the field. - - status - Indicates whether the payout method is currently available. One of the following values: - **0** - Not available. - **1** - Available. - /v1/payout_methods/:payout_method_type/required_fields - Get Payout Required Fields - ```curl curl -X get 'https://sandboxapi.rapyd.net/v1/payout_methods/mx_abc_capital_bank/required_fields?sender_country=mx&sender_currency=USD&beneficiary_country=mx&payout_currency=mxn&sender_entity_type=company&beneficiary_entity_type=individual&payout_amount=2000' \ -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": "7b0f3268-94e3-43b7-9c5c-704d6ca3c968" }, "data": { "payout_method_type": "mx_abc_capital_bank", "sender_currency": "USD", "sender_country": "*", "sender_entity_type": "company", "beneficiary_country": "mx", "payout_currency": "MXN", "beneficiary_entity_type": "individual", "is_cancelable": 0, "is_location_specific": 0, "is_expirable": 0, "minimum_expiration_seconds": null, "maximum_expiration_seconds": null, "is_online": null, "image": "/checkout/mx_abc_capital_bank.png", "status": 1, "beneficiary_required_fields": [ { "name": "account_number", "regex": "^([0-9]){1,34}$", "is_required": true, "type": "string" }, { "name": "first_name", "regex": "^([a-zA-Z0-9\\s]){1,50}$", "is_required": true, "type": "string" }, { "name": "last_name", "regex": "^([a-zA-Z0-9\\s]){1,50}$", "is_required": true, "type": "string" }, { "name": "bank_account_type", "regex": "clabe", "is_required": true, "type": "string" }, { "name": "date_of_birth", "regex": "^(0[1-9]|[12][0-9]|3[01])/(0[1-9]|1[012])/(19|20)[0-9][0-9]$", "is_required": false, "type": "string", "description": "dd/mm/yyyy" } ], "sender_required_fields": [ { "name": "company_name", "regex": "^([a-zA-Z0-9]){1,50}$", "is_required": true, "type": "string" } ], "payout_options": null, "minimum_amount": 1, "maximum_amount": 999999999, "batch_file_header": "payout_method_type,sender_currency,payout_currency,beneficiary.account_number,beneficiary.first_name,beneficiary.last_name,beneficiary.bank_account_type,beneficiary.date_of_birth,sender.company_name" } } ``` - Bad Request - Missing Sender Country - ```curl curl -X get 'https://sandboxapi.rapyd.net/v1/payout_methods/mx_abc_capital_bank/required_fields?sender_currency=USD&beneficiary_country=mx&payout_currency=mxn&sender_entity_type=company&beneficiary_entity_type=individual&payout_amount=2000' \ -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": "ERROR_MISSING_PAYOUT_SENDER_COUNTRY", "status": "ERROR", "message": "The request attempted an operation that requires the country of the sender, but the country was missing. The request was rejected. Corrective action: In the 'sender_country' field, use the correct 2-letter ISO 3166-1 ALPHA-2 code.", "response_code": "ERROR_MISSING_PAYOUT_SENDER_COUNTRY", "operation_id": "594e987e-07c0-40ee-afa8-100019e1fb2e" } } ``` - Bad Request - Invalid Payout Method Type - ```curl curl -X get 'https://sandboxapi.rapyd.net/v1/payout_methods/mx_xyz_capital_bank/required_fields?sender_country=mx&sender_currency=USD&beneficiary_country=mx&payout_currency=mxn&sender_entity_type=company&beneficiary_entity_type=individual&payout_amount=2000' \ -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_PAYOUT_METHOD_TYPE", "status": "ERROR", "message": "The request tried to perform an operation that requires a payout method type, but the type was not recognized. The request was rejected. Corrective action: To find payout method types, use 'List Payout Method Types'.", "response_code": "INVALID_PAYOUT_METHOD_TYPE", "operation_id": "7be035fd-23bf-4a56-a01b-71bf9ac7eede" } } ```