Payout Validation Schema

The Payout Validation Schema request returns every required field, validation rule, and constraint for a payout. You filter the result by destination country, currency, and payout method.

Instead of relying on static documentation, you can programmatically discover the exact data a payout needs before you submit it. This reduces rejected transactions and shortens your integration time.

Benefits

• One request for all corridors: Get field-level requirements for any supported corridor.
• Filtered results: Query by destination country, currency, and payout method.
• Per-field rules: See whether a field is required, its accepted format, length limits, and allowed values.
• Purpose codes: Get the corridor-specific values accepted in the purposeCode field.
• Dynamic validation: Build your payout form and validate your payload once, instead of fixing errors through trial and error in UAT.

How it works

1. Before you create a payout, call the Payout Validation Schema request with the destination currency, destination country, and payout method.
2. Read the returned schema to find the fields your request must include, along with their validation rules.
3. Use the schema to build your payout form or validate your request payload.
4. Optionally, check the complete payload with the Payout Validator request.
5. Submit the payout using the Transfer Money request.

API request

GET /api/v1/client/{clientHashId}/customer/{customerHashId}/currency/{currencyCode}/payout/schema?payoutMethod=LOCAL&destinationCountry=PH
x-api-key: YOUR_API_KEY
x-request-id: YOUR_UNIQUE_UUID

Path parameters

Parameter	Required	Description
clientHashId	Yes	Unique client identifier generated and shared before API handshake.
customerHashId	Yes	Unique customer identifier generated on customer creation.
currencyCode	Yes	Destination currency as a 3-letter ISO 4217 code, for example, PHP.

Query parameters

Parameter	Required	Description
payoutMethod	Yes	The payout method. Accepted values: LOCAL, SWIFT, PROXY, WALLET, CARD, CASH, and CHECK.
destinationCountry	Yes	Destination country as a 2-letter ISO 3166 alpha-2 code, for example, PH.

Response

The response is a JSON Schema (draft 2020-12) document for the requested corridor. You can pass it to any standard JSON Schema validator library to validate your payout payload.

Each property name is the dot-notation path to a field in your payout request. For example, beneficiary.paymentAccount.accountNumber refers to the accountNumber field inside the beneficiary's paymentAccount object.

The following example shows the response for a local PHP payout to the Philippines:

Example response: PHP local payout schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "unified.php.local.json",
  "type": "object",
  "title": "PHP Local Unified Schema",
  "required": [
    "beneficiary.paymentAccount.payoutCurrency",
    "payout.destinationAmount",
    "remitter.name",
    "remitter.accountType",
    "remitter.address",
    "remitter.countryCode",
    "remitter.identificationType",
    "remitter.identificationNumber",
    "beneficiary.beneficiary.name",
    "beneficiary.beneficiary.addresses[0].line1",
    "beneficiary.beneficiary.addresses[0].countryCode",
    "beneficiary.beneficiary.accountType",
    "beneficiary.paymentAccount.accountNumber",
    "beneficiary.paymentAccount.routingCode[0].type",
    "beneficiary.paymentAccount.routingCode[0].value",
    "beneficiary.paymentAccount.payoutMethod",
    "payout.sourceCurrency"
  ],
  "properties": {
    "beneficiary.paymentAccount.payoutCurrency": {
      "$id": "/properties/beneficiary.paymentAccount.payoutCurrency",
      "type": "string",
      "title": "Destination Currency",
      "const": "PHP",
      "description": "Destination currency should be PHP"
    },
    "payout.destinationAmount": {
      "$id": "/properties/payout.destinationAmount",
      "type": "number",
      "title": "Destination Amount",
      "maximumDecimals": 2,
      "minimum": 0.01,
      "description": "Destination Amount should be minimum 0.01 PHP and upto two decimal places are allowed."
    },
    "customerComments": {
      "$id": "/properties/customerComments",
      "type": "string",
      "title": "Statement Narrative",
      "pattern": "^[a-zA-Z0-9_\\s]{0,255}$",
      "description": "Statement narrative can contain only these special characters - (_). Length should not be more than 255 characters."
    },
    "remitter.name": {
      "$id": "/properties/remitter.name",
      "type": "string",
      "title": "Remitter Name",
      "pattern": "^[A-Za-z0-9 .,()_'/&-]{1,100}$",
      "description": "Remitter Name can contain only these special characters - (. , ( ) _ ' / &-). Length should not be more than 100 characters."
    },
    "remitter.accountType": {
      "$id": "/properties/remitter.accountType",
      "title": "Remitter Account Type",
      "enum": [
        "INDIVIDUAL",
        "CORPORATE"
      ],
      "description": "Remitter Account Type should be INDIVIDUAL or CORPORATE."
    },
    "remitter.bankAccountNumber": {
      "$id": "/properties/remitter.bankAccountNumber",
      "type": "string",
      "title": "Remitter Bank Account Number",
      "maxLength": 50,
      "description": "Length of Remitter Bank Account Number should not be more than 50 characters."
    },
    "remitter.contactNumber": {
      "$id": "/properties/remitter.contactNumber",
      "type": "string",
      "title": "Remitter Contact Number",
      "pattern": "^\\d{0,17}$",
      "description": "Length of Remitter Contact Number should not be more than 17 digits."
    },
    "remitter.dob": {
      "type": "string",
      "$id": "/properties/remitter.dob",
      "title": "Remitter DOB",
      "pattern": "^(\\d\\d\\d\\d-[0-1]\\d-[0-3]\\d|\\d\\d\\d\\d/[0-1]\\d/[0-3]\\d).*?$",
      "description": "Remitter DOB can contain only these special characters-(- .). Length should not be more than 255 characters."
    },
    "remitter.address": {
      "$id": "/properties/remitter.address",
      "type": "string",
      "title": "Remitter Address",
      "maxLength": 200,
      "description": "Length of Remitter Address should not be more than 200 characters."
    },
    "remitter.city": {
      "$id": "/properties/remitter.city",
      "type": "string",
      "title": "Remitter City",
      "maxLength": 255,
      "description": "Length of Remitter City should not be more than 255 characters."
    },
    "remitter.postcode": {
      "$id": "/properties/remitter.postcode",
      "type": "string",
      "title": "Remitter Postcode",
      "pattern": "^[a-zA-Z0-9\\s\\-]{0,255}$",
      "description": "Remitter Postcode can contain only these special characters - (-). Length of postcode should not be more than 255 characters."
    },
    "remitter.state": {
      "$id": "/properties/remitter.state",
      "type": "string",
      "title": "Remitter State",
      "maxLength": 255,
      "description": "Length of Remitter State should not be more than 255 characters."
    },
    "remitter.countryCode": {
      "$id": "/properties/remitter.countryCode",
      "type": "string",
      "title": "Remitter Country Code",
      "pattern": "^[A-Z]{2}$",
      "description": "Remitter Country should be valid two letter country code."
    },
    "remitter.nationality": {
      "$id": "/properties/remitter.nationality",
      "type": "string",
      "title": "Remitter Nationality",
      "pattern": "^[A-Z]{2}$",
      "description": "Remitter Nationality should be valid two letter country code."
    },
    "beneficiary.beneficiary.remitterBeneficiaryRelationship": {
      "$id": "/properties/beneficiary.beneficiary.remitterBeneficiaryRelationship",
      "type": "string",
      "title": "Remitter Beneficiary Relationship",
      "pattern": "^[A-Za-z0-9 -.]{1,255}$",
      "description": "Remitter Beneficiary Relationship should not contain special characters."
    },
    "purposeCode": {
      "$id": "/properties/purposeCode",
      "type": "string",
      "title": "Remit Purpose Code",
      "description": "Remit purpose code should be a valid NIUM purpose code."
    },
    "sourceOfFunds": {
      "$id": "/properties/sourceOfFunds",
      "type": "string",
      "title": "Remitter Source of Income",
      "maxLength": 255,
      "description": "Length of Remitter Source of Income should not be more than 255 characters."
    },
    "beneficiary.beneficiary.name": {
      "$id": "/properties/beneficiary.beneficiary.name",
      "type": "string",
      "title": "Beneficiary Name",
      "pattern": "^[A-Za-z0-9 .,()_'/-]{1,64}$",
      "description": "Name can contain english alphabets, numbers and special characters - (. , ( ) _ ' / -). Length should not be more than 64 characters."
    },
    "beneficiary.beneficiary.addresses[0].line1": {
      "$id": "/properties/beneficiary.beneficiary.addresses[0].line1",
      "type": "string",
      "title": "Beneficiary Address",
      "maxLength": 200,
      "description": "Length of Beneficiary Address should not be more than 200 characters."
    },
    "beneficiary.beneficiary.addresses[0].city": {
      "$id": "/properties/beneficiary.beneficiary.addresses[0].city",
      "type": "string",
      "title": "Beneficiary City",
      "maxLength": 35,
      "description": "Length of Beneficiary City should not be more than 35 characters."
    },
    "beneficiary.beneficiary.addresses[0].countryCode": {
      "$id": "/properties/beneficiary.beneficiary.addresses[0].countryCode",
      "type": "string",
      "title": "Beneficiary Country Code",
      "pattern": "^[A-Z]{2}$",
      "description": "Beneficiary Country should be valid two letter country code."
    },
    "beneficiary.beneficiary.email.value": {
      "$id": "/properties/beneficiary.beneficiary.email.value",
      "type": "string",
      "title": "Beneficiary Email",
      "maxLength": 100,
      "pattern": "^([a-zA-Z0-9+_\\-\\.]+)@([a-zA-Z0-9_\\-\\.]+)\\.([a-zA-Z]{2,63})$",
      "description": "Beneficiary should provide a valid email address."
    },
    "beneficiary.paymentAccount.accountType": {
      "$id": "/properties/beneficiary.paymentAccount.accountType",
      "type": "string",
      "title": "Beneficiary Bank Account Type",
      "enum": [
        "CHECKING",
        "SAVING",
        "MAESTRA",
        "CURRENT"
      ],
      "description": "Beneficiary Bank Account should be of the type : CHECKING, MAESTRA,  SAVING or CURRENT."
    },
    "beneficiary.beneficiary.accountType": {
      "$id": "/properties/beneficiary.beneficiary.accountType",
      "type": "string",
      "title": "Beneficiary Account Type",
      "enum": [
        "INDIVIDUAL",
        "CORPORATE"
      ],
      "description": "Beneficiary Account Type should be INDIVIDUAL or CORPORATE."
    },
    "beneficiary.beneficiary.contactNumber.number": {
      "$id": "/properties/beneficiary.beneficiary.contactNumber.number",
      "type": "string",
      "title": "Beneficiary Contact Number",
      "pattern": "^\\d{1,17}$",
      "description": "Length of Beneficiary Contact Number should not be more than 17 digits."
    },
    "beneficiary.beneficiary.addresses[0].state": {
      "$id": "/properties/beneficiary.beneficiary.addresses[0].state",
      "type": "string",
      "title": "Beneficiary State",
      "maxLength": 50,
      "description": "Length of Beneficiary State should not be more than 50 characters."
    },
    "beneficiary.beneficiary.addresses[0].postalCode": {
      "$id": "/properties/beneficiary.beneficiary.addresses[0].postalCode",
      "type": "string",
      "title": "Beneficiary Postcode",
      "maxLength": 15,
      "description": "Length of Beneficiary Postcode should not be more than 15 characters."
    },
    "beneficiary.paymentAccount.accountNumber": {
      "$id": "/properties/beneficiary.paymentAccount.accountNumber",
      "type": "string",
      "title": "Beneficiary Account Number",
      "pattern": "^.{1,25}$",
      "description": "Length of Beneficiary Account Number should not be more than 25 characters."
    },
    "beneficiary.paymentAccount.bankName": {
      "$id": "/properties/beneficiary.paymentAccount.bankName",
      "type": "string",
      "title": "Beneficiary Bank Name",
      "maxLength": 255,
      "description": "Length of Beneficiary Bank Name should not be more than 255 characters."
    },
    "beneficiary.paymentAccount.bankCode": {
      "$id": "/properties/beneficiary.paymentAccount.bankCode",
      "type": "string",
      "title": "Beneficiary Bank Code",
      "maxLength": 15,
      "description": "Length of Beneficiary Bank Code should not be more than 15."
    },
    "beneficiary.beneficiary.identification.type": {
      "$id": "/properties/beneficiary.beneficiary.identification.type",
      "type": "string",
      "title": "Beneficiary Identification Type",
      "pattern": "^[A-Za-z0-9 \\.:()_/-]{1,255}$",
      "description": "Beneficiary Identification Type can contain only these special characters - (- . ( ) : _ /). Length should not be more than 255 characters."
    },
    "beneficiary.beneficiary.identification.value": {
      "$id": "/properties/beneficiary.beneficiary.identification.value",
      "type": "string",
      "title": "Beneficiary Identification Value",
      "pattern": "^[A-Za-z0-9 \\.:()_/-]{1,255}$",
      "description": "Beneficiary Identification Value can contain only these special characters - (- . ( ) : _ /). Length should not be more than 255 characters."
    },
    "beneficiary.paymentAccount.routingCode[0].type": {
      "$id": "/properties/beneficiary.paymentAccount.routingCode[0].type",
      "type": "string",
      "title": "Routing Code Type 1",
      "const": "SWIFT",
      "description": "Routing Code type one should be SWIFT for payouts to this country."
    },
    "beneficiary.paymentAccount.routingCode[0].value": {
      "$id": "/properties/beneficiary.paymentAccount.routingCode[0].value",
      "type": "string",
      "title": "Routing Code Value 1",
      "pattern": "^[A-Za-z0-9]{8}$|^[A-Za-z0-9]{11}$",
      "description": "SWIFT should not contain special characters. Length of SWIFT should be 8 or 11 characters."
    },
    "beneficiary.paymentAccount.payoutMethod": {
      "type": "string",
      "title": "Payout Method",
      "description": "Payout method for the transaction. Supported values: LOCAL, SWIFT, PROXY, CASH, WALLET, CARD.",
      "$id": "/properties/beneficiary.paymentAccount.payoutMethod"
    },
    "payout.sourceCurrency": {
      "type": "string",
      "title": "Source Currency",
      "description": "Source currency for the payout (ISO 4217 code). Required when payout.auditId is not provided.",
      "$id": "/properties/payout.sourceCurrency"
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "payout.destinationAmount": {
            "minimum": 500001,
            "type": "number"
          }
        },
        "required": [
          "payout.destinationAmount"
        ]
      },
      "then": {
        "required": [
          "sourceOfFunds",
          "purposeCode"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "remitter.accountType": {
            "const": "INDIVIDUAL"
          },
          "beneficiary.beneficiary.accountType": {
            "const": "INDIVIDUAL"
          }
        },
        "required": [
          "remitter.accountType",
          "beneficiary.beneficiary.accountType"
        ]
      },
      "then": {
        "properties": {
          "purposeCode": {
            "enum": [
              "IR002",
              "IR004",
              "IR006",
              "IR008",
              "IR010",
              "IR012",
              "IR014",
              "IR016",
              "IR01801",
              "IR01803",
              "IR01805",
              "IR01807",
              "IR01809",
              "IR01811",
              "IR021",
              "IR001",
              "IR003",
              "IR005",
              "IR007",
              "IR009",
              "IR011",
              "IR013",
              "IR015",
              "IR017",
              "IR01802",
              "IR01804",
              "IR01806",
              "IR01808",
              "IR01810",
              "IR020"
            ]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "remitter.accountType": {
            "const": "INDIVIDUAL"
          },
          "beneficiary.beneficiary.accountType": {
            "const": "CORPORATE"
          }
        },
        "required": [
          "remitter.accountType",
          "beneficiary.beneficiary.accountType"
        ]
      },
      "then": {
        "properties": {
          "purposeCode": {
            "enum": [
              "IR002",
              "IR004",
              "IR006",
              "IR008",
              "IR010",
              "IR012",
              "IR014",
              "IR016",
              "IR01801",
              "IR01803",
              "IR01805",
              "IR01807",
              "IR01809",
              "IR01811",
              "IR021",
              "IR001",
              "IR003",
              "IR005",
              "IR007",
              "IR009",
              "IR011",
              "IR013",
              "IR015",
              "IR017",
              "IR01802",
              "IR01804",
              "IR01806",
              "IR01808",
              "IR01810",
              "IR020"
            ]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "remitter.accountType": {
            "const": "CORPORATE"
          },
          "beneficiary.beneficiary.accountType": {
            "const": "INDIVIDUAL"
          }
        },
        "required": [
          "remitter.accountType",
          "beneficiary.beneficiary.accountType"
        ]
      },
      "then": {
        "properties": {
          "purposeCode": {
            "enum": [
              "IR002",
              "IR004",
              "IR006",
              "IR008",
              "IR010",
              "IR012",
              "IR014",
              "IR016",
              "IR01801",
              "IR01803",
              "IR01805",
              "IR01807",
              "IR01809",
              "IR01811",
              "IR021",
              "IR001",
              "IR003",
              "IR005",
              "IR007",
              "IR009",
              "IR011",
              "IR013",
              "IR015",
              "IR017",
              "IR01802",
              "IR01804",
              "IR01806",
              "IR01808",
              "IR01810",
              "IR020"
            ]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "remitter.accountType": {
            "const": "CORPORATE"
          },
          "beneficiary.beneficiary.accountType": {
            "const": "CORPORATE"
          }
        },
        "required": [
          "remitter.accountType",
          "beneficiary.beneficiary.accountType"
        ]
      },
      "then": {
        "properties": {
          "purposeCode": {
            "enum": [
              "IR002",
              "IR004",
              "IR006",
              "IR008",
              "IR010",
              "IR012",
              "IR014",
              "IR016",
              "IR01801",
              "IR01803",
              "IR01805",
              "IR01807",
              "IR01809",
              "IR01811",
              "IR021",
              "IR001",
              "IR003",
              "IR005",
              "IR007",
              "IR009",
              "IR011",
              "IR013",
              "IR015",
              "IR017",
              "IR01802",
              "IR01804",
              "IR01806",
              "IR01808",
              "IR01810",
              "IR020"
            ]
          }
        }
      }
    }
  ]
}

Read the schema

Keyword	Description
required	Fields that your payout request must include for this corridor.
properties	The rules for each field, keyed by the field's dot-notation path.
type	The data type of the field, such as string or number.
pattern	A regular expression that the field value must match.
maxLength	The maximum length of a string field.
minimum, maximumDecimals	The smallest accepted amount and the maximum number of decimal places.
enum	The list of accepted values for the field.
const	The only accepted value for the field.
description	A readable explanation of the field's rules.
allOf with if and then	Conditional rules. When the if condition matches your request, the rules under then also apply.

In the example, the allOf block contains two kinds of conditional rules:

• Additional required fields: When payout.destinationAmount is 500,001 PHP or more, sourceOfFunds and purposeCode also become required.
• Accepted purpose codes: The accepted purposeCode values depend on the combination of remitter.accountType and beneficiary.beneficiary.accountType. For example, when both are INDIVIDUAL, purposeCode must be one of the listed IR codes.

tip

Cache the schema for each corridor and refresh it periodically. Don't hardcode field lists in your application—corridor requirements can change.

Related pages

• Transfer Money
• Payout Validator
• Purpose Codes
• Routing Codes
• Country and Regional Guides