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 , Create Sender, and 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 will continue to support the deprecated endpoint until December 31, 2024.

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

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.
- 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. Two or more of the following:
  - 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. Two or more of the following:
  - 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 -X get
https://sandboxapi.rapyd.net/v1/payout_methods/xx_swift_bank/required_fields?sender_country=PH&sender_currency=USD&beneficiary_country=MX&payout_currency=MXN&sender_entity_type=company&beneficiary_entity_type=individual&payout_amount=251
-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": "d60c2f93-065a-47a5-aef0-7bdb824fb5ab"
    },
    "data": {
        "payout_method_type": "xx_swift_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/xx_swift_bank.png",
        "status": 1,
        "beneficiary_required_fields": [
            {
                "name": "first_name",
                "regex": "^.{1,20}",
                "is_required": true,
                "type": "string",
                "description": "First name + Last name must not exceed 35 characters."
            },
            {
                "name": "last_name",
                "regex": "^.{1,15}",
                "is_required": false,
                "type": "string",
                "description": "First name + Last name must not exceed 35 characters"
            },
            {
                "name": "address",
                "regex": "^.{1,35}",
                "is_required": true,
                "type": "string",
                "description": "Beneficiary street name ; building number"
            },
            {
                "name": "city",
                "regex": "^.{1,25}",
                "is_required": true,
                "type": "string",
                "description": "The combined length of city+state+country+postcode must not exceed 32 characters"
            },
            {
                "name": "state",
                "regex": "^.{1,15}",
                "is_required": false,
                "type": "string",
                "description": "The combined length of city+state+country+postcode must not exceed 32 characters"
            },
            {
                "name": "country",
                "regex": "^[A-Z]{2}$",
                "is_required": true,
                "type": "string",
                "description": "The combined length of city+state+country+postcode must not exceed 32 characters"
            },
            {
                "name": "postcode",
                "regex": "^.{1,10}",
                "is_required": false,
                "type": "string",
                "description": "The combined length of city+state+country+postcode must not exceed 32 characters"
            },
            {
                "name": "account_number",
                "regex": "^.{1,34}$",
                "is_required": true,
                "type": "string"
            },
            {
                "name": "bic_swift",
                "regex": "^.{8,11}$",
                "is_required": true,
                "type": "string"
            }
        ],
        "sender_required_fields": [
            {
                "name": "company_name",
                "regex": "^.{1,35}",
                "is_required": true,
                "type": "string"
            },
            {
                "name": "address",
                "regex": "^.{1,35}",
                "is_required": true,
                "type": "string",
                "description": "Beneficiary street name ; building number"
            },
            {
                "name": "city",
                "regex": "^.{1,25}",
                "is_required": true,
                "type": "string",
                "description": "The combined length of city+state+country+postcode must not exceed 32 characters"
            },
            {
                "name": "state",
                "regex": "^.{1,15}",
                "is_required": false,
                "type": "string",
                "description": "The combined length of city+state+country+postcode must not exceed 32 characters"
            },
            {
                "name": "country",
                "regex": "^[A-Z]{2}$",
                "is_required": true,
                "type": "string",
                "description": "The combined length of city+state+country+postcode must not exceed 32 characters"
            },
            {
                "name": "postcode",
                "regex": "^.{1,10}",
                "is_required": false,
                "type": "string",
                "description": "The combined length of city+state+country+postcode must not exceed 32 characters"
            },
            {
                "name": "purpose_code",
                "regex": "investment_income|salary|insurance_payments|computer_services|educational_services|payment_of_goods|payment_of_services|Inward_remittance",
                "is_required": false,
                "type": "string",
                "allowed_values": [
                    "investment_income",
                    "salary",
                    "insurance_payments",
                    "computer_services",
                    "educational_services",
                    "payment_of_goods",
                    "payment_of_services",
                    "Inward_remittance"
                ],
                "description": "Required only for sending to - China, India, South Korea, Philippines, Malaysia"
            }
        ],
        "payout_options": [
            {
                "name": "beneficiary_country",
                "regex": "^[A-Z]{2}$",
                "is_required": true,
                "type": "string",
                "description": "Country where the beneficiary account is held"
            },
            {
                "name": "description",
                "regex": "^.{1,140}",
                "is_required": true,
                "type": "string",
                "description": "Payout purpose description"
            },
            {
                "name": "statement_descriptor",
                "regex": "^.{1,140}",
                "is_required": false,
                "type": "string",
                "description": "Information to be displayed in the beneficiary statement"
            }
        ],
        "minimum_amount": null,
        "maximum_amount": null,
        "batch_file_header": "payout_method_type,sender_currency,payout_currency,beneficiary.first_name,beneficiary.last_name,beneficiary.address,beneficiary.city,beneficiary.state,beneficiary.country,beneficiary.postcode,beneficiary.account_number,beneficiary.bic_swift,sender.company_name,sender.address,sender.city,sender.state,sender.country,sender.postcode,sender.purpose_code"
    }
}

In this section:

Documentation