Schemas

Schemas define the required data structure and validation rules for different types of recipient accounts across various payment rails or geographic regions. Each schema specifies the exact fields, data types, and validation requirements needed to successfully create recipients and process transfers.

Retrieving Available Schemas

Get all available payment schemas and their field definitions:

GET /schemas

Response:

[
  {
    "id": "bank_sepa",
    "category": "bank",
    "fields": [
      {
        "key": "accountType",
        "type": "string",
        "oneOf": ["individual", "business"],
        "required": true
      },
      {
        "key": "IBAN",
        "type": "iban",
        "required": true
      },
      {
        "key": "companyName",
        "type": "string",
        "requiredIf": "accountType=business"
      }
    ]
  },
  {
    "id": "evm",
    "category": "crypto",
    "fields": [
      {
        "key": "address",
        "type": "eth_addr",
        "required": true
      }
    ]
  }
]

Understanding Schema Descriptors

Each schema descriptor contains:

id - Unique schema identifier used when creating recipients
category - Schema category (bank, mobile, crypto)
fields - Array of field definitions with validation rules

Field Properties

Property	Type	Description
`key`	string	Field name in JSON payload
`type`	string	Data type and validation rule
`required`	boolean	Whether field is mandatory
`requiredIf`	string	Conditional requirement (e.g., "accountType=individual")
`excludedUnless`	string	Field only allowed under condition
`oneOf`	array	Allowed enum values
`fields`	array	Nested object fields (for type="object")

Field Types

Common field types and their validation rules:

Type	Description	Example
`string`	Text field	Account holder name
`numeric`	Numbers only	Account number, routing number
`email`	Valid email format	[email protected]
`iban`	Valid IBAN format	GB82WEST12345698765432
`bic`	Valid BIC/SWIFT code	DEUTDEFF
`sort_code`	UK sort code format	12-34-56
`ifsc`	Indian IFSC code	HDFC0000123
`bsb`	Australian BSB code	123-456
`clabe`	Mexican CLABE format	123456789012345678
`cnaps`	Chinese CNAPS code	123456789012
`eth_addr`	Ethereum address	0x742d35Cc6635C0532925a3b8D98d0dfBb67B1BF8
`tron_addr`	Tron address	TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE
`starknet_addr`	Starknet address	0x1234...abcd
`object`	Nested object with sub-fields	Address object

Schema Validation

When creating recipients with invalid schema data, you'll receive a structured validation error:

Error Response (422):

{
  "statusCode": 422,
  "message": "Validation error",
  "code": "err_validation",
  "details": {
    "routingNumber": "required",
    "accountNumber": "numeric",
    "beneficiaryAddress.street_line_1": "required"
  }
}

The details object maps field paths to the specific validation rule that failed. For nested objects, field paths use dot notation (e.g., beneficiaryAddress.street_line_1).

Conditional Validation

Some schemas have conditional field requirements:

requiredIf - Field required only when another field has specific value
excludedUnless - Field only allowed when another field has specific value

Example: Colombian bank accounts require different fields for individual vs business accounts:

{
  "key": "firstName",
  "type": "string", 
  "requiredIf": "accountType=individual",
  "excludedUnless": "accountType=individual"
}

Schema Categories

Schemas are organized into three main categories:

Bank (`bank`)

Traditional banking payment methods including:

Domestic bank transfers (US ACH, UK Faster Payments, etc.)
International wire transfers (SWIFT)
Regional payment systems (SEPA, UPI, etc.)

Mobile (`mobile`)

Mobile money and digital wallet services:

African mobile money providers
Digital payment platforms

Crypto (`crypto`)

Cryptocurrency and blockchain-based payments:

EVM-compatible networks (Ethereum, Polygon, etc.)
Tron network
Starknet