Payment Methods & Requirements

Cadana supports multiple payment methods depending on the destination country and currency. Each method has specific field requirements for creating beneficiaries. Use the discovery endpoints to determine what’s available for a given corridor at runtime.

Available corridors are configured per business. If you need access to a corridor that isn’t enabled on your account, contact the Cadana team.

Discovering Available Methods

Call GET /v1/payment-methods to list payment methods available for a country:

bash

curl -X GET 'https://api.cadanapay.com/v1/payment-methods' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Try it in the playground →

Response:

{
  "country": "BR",
  "paymentMethods": [
    { "type": "bank", "currency": "BRL", "status": "active" },
    { "type": "proxy", "currency": "BRL", "status": "active" },
    { "type": "swift", "currency": "USD", "status": "active" }
  ]
}

Call GET /v1/providers to list supported banks and mobile money providers:

bash

curl -X GET 'https://api.cadanapay.com/v1/providers' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Try it in the playground →

Response:

{
  "data": [
    {
      "code": "01",
      "name": "Example Bank",
      "countryCode": "KE",
      "currency": "KES",
      "type": "bank"
    }
  ]
}

Use the returned code as the bankCode (or providerCode for mobile money) when creating beneficiaries.

Using the Requirements API

The requirements endpoint returns a JSON Schema (Draft-07) describing all mandatory and optional fields for a given corridor:

bash

curl -X GET 'https://api.cadanapay.com/v1/payment-requirements' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Understanding the Response

Here’s an example response for Colombia (COP, bank transfer):

{
  "type": "object",
  "additionalProperties": false,
  "required": ["accountName", "accountNumber", "bankCode", "bankName", "accountType", "beneficiaryId", "address", "email"],
  "properties": {
    "accountName": { "type": "string", "maxLength": 60 },
    "accountNumber": {
      "type": "string",
      "pattern": "^[0-9]{9,16}$",
      "description": "9 - 16-digit Colombian account number"
    },
    "accountType": { "type": "string", "enum": ["Checking", "Saving"] },
    "bankCode": {
      "type": "string",
      "pattern": "^[A-Za-z0-9]{1,11}$",
      "description": "1-11 alphanumeric bank code"
    },
    "bankName": { "type": "string", "maxLength": 255 },
    "email": { "type": "string", "format": "email", "maxLength": 100 },
    "beneficiaryId": {
      "type": "object",
      "additionalProperties": false,
      "required": ["type", "value"],
      "properties": {
        "type": { "type": "string", "enum": ["NIT", "CC", "CE", "TI", "PASS"] },
        "value": { "type": "string" }
      },
      "allOf": [
        {
          "if": { "properties": { "type": { "const": "NIT" } } },
          "then": { "properties": { "value": { "pattern": "^\\d{9,11}$" } } }
        },
        {
          "if": { "properties": { "type": { "const": "CC" } } },
          "then": { "properties": { "value": { "pattern": "^\\d{6,10}$" } } }
        },
        {
          "if": { "properties": { "type": { "const": "CE" } } },
          "then": { "properties": { "value": { "pattern": "^[A-Za-z0-9]{5,12}$" } } }
        },
        {
          "if": { "properties": { "type": { "const": "TI" } } },
          "then": { "properties": { "value": { "pattern": "^\\d{8,11}$" } } }
        },
        {
          "if": { "properties": { "type": { "const": "PASS" } } },
          "then": { "properties": { "value": { "pattern": "^[A-Za-z0-9]{5,15}$" } } }
        }
      ]
    },
    "address": {
      "type": "object",
      "additionalProperties": false,
      "required": ["line1", "city", "countryCode"],
      "properties": {
        "line1": { "type": "string", "maxLength": 70 },
        "line2": { "type": "string", "maxLength": 70 },
        "city": { "type": "string", "maxLength": 50 },
        "postalCode": { "type": "string", "maxLength": 10 },
        "state": { "type": "string", "maxLength": 50 },
        "countryCode": { "const": "CO" }
      }
    }
  }
}

Key parts of the schema:

Keyword	What it tells you
`required`	Fields that must be present
`properties`	Available fields with their types and constraints
`pattern`	Regex the value must match (e.g., `^[0-9]{9,16}$` for a 9-16 digit number)
`enum`	Allowed values (e.g., `["Checking", "Saving"]`)
`const`	Fixed value (e.g., `"CO"` for country code)
`maxLength`	Maximum string length
`format`	Semantic format hint (e.g., `email`)
`additionalProperties`	When `false`, no extra fields beyond those in `properties` are accepted
`allOf` / `if-then`	Conditional rules — e.g., if `beneficiaryId.type` is `"NIT"`, then `value` must be 9-11 digits

Building Dynamic Forms

You can use these schemas to dynamically generate beneficiary creation forms that automatically adapt to each corridor’s requirements — no hardcoded field logic needed.

User selects country, currency, and payment method
Your app calls GET /v1/payment-requirements
Render form fields from the schema (required, types, enums, validation)
Validate input client-side against the schema before submitting
POST /v1/beneficiaries with the validated data

This approach means your UI automatically adapts when Cadana adds new corridors or updates field requirements, without code changes. Standard JSON Schema libraries (like Ajv for JavaScript or jsonschema for Python) can handle validation directly from the response.

Always use GET /v1/payment-requirements as the source of truth. The examples below illustrate common patterns to help you plan your integration — they are not exhaustive.

Bank Transfer

Sends funds directly to a recipient’s bank account through local clearing networks. Set preferredMethod to "bank" and provide bank details in the bank object:

{
  "paymentDetails": {
    "preferredMethod": "bank",
    "bank": {
      "accountName": "John Doe",
      "accountNumber": "0123456789",
      "bankCode": "058",
      "bankName": "Example Bank"
    }
  }
}

Required fields vary by corridor. Bank transfer corridors range from 4 required fields to 10+, depending on the country’s regulatory and clearing requirements.

Simple — Nigeria (NGN)

Many corridors (e.g., NG, KE, GH, MX) require only basic bank details:

Field	Required	Format	Notes
`accountName`	Yes	String (max 60)	Must match bank records
`accountNumber`	Yes	String (max 255)	Bank-specific format (e.g., 10-digit NUBAN for Nigeria)
`bankCode`	Yes	String (max 255)	Bank code — use `GET /v1/providers`
`bankName`	Yes	String (max 255)	Bank name

Medium — United Kingdom (GBP)

Some corridors add fields like sortCode, routingNumber, or iban depending on the local clearing system:

Field	Required	Format	Notes
`accountName`	Yes	String (max 60)	Account holder name
`accountNumber`	Yes	1-8 digits	UK account number
`bankCode`	Yes	String (max 255)	Bank code
`bankName`	Yes	String (max 255)	Bank name
`sortCode`	Yes	6 digits	Sort code

Other examples of this pattern: SEPA (adds iban, beneficiaryAddress), Canada (adds sortCode, address).

Complex — Colombia (COP)

Corridors like Colombia, India, South Africa, and Peru require a combination of beneficiary identification, address, contact details, and conditional validation:

Field	Required	Format	Notes
`accountName`	Yes	String (max 60)	Account holder name
`accountNumber`	Yes	9-16 digits	Colombian account number
`bankCode`	Yes	String (1-11 chars)	Alphanumeric bank code
`bankName`	Yes	String (max 255)	Bank name
`accountType`	Yes	`Checking` or `Saving`	Account type
`beneficiaryId.type`	Yes	`NIT`, `CC`, `CE`, `TI`, or `PASS`	ID type
`beneficiaryId.value`	Yes	String	ID number (format depends on type — see schema `allOf` rules)
`email`	Yes	Email (max 100)	Recipient email
`address.line1`	Yes	String (max 70)	Street address
`address.city`	Yes	String (max 50)	City
`address.countryCode`	Yes	`CO`	Country code

ACH

Send funds to US bank accounts via the Automated Clearing House network. Set preferredMethod to "ach" and provide details in the ach object:

{
  "paymentDetails": {
    "preferredMethod": "ach",
    "ach": {
      "accountName": "Jane Smith",
      "accountNumber": "123456789",
      "routingNumber": "000000000",
      "accountType": "Checking",
      "bankName": "Example Bank",
      "address": {
        "line1": "123 Main St",
        "city": "New York",
        "state": "NY",
        "postalCode": "10001",
        "countryCode": "US"
      }
    }
  }
}

Mobile Money

Send funds directly to mobile money wallets. Widely used across Sub-Saharan African markets. Set preferredMethod to "momo" and provide details in the momo object:

{
  "paymentDetails": {
    "preferredMethod": "momo",
    "momo": {
      "accountName": "John Doe",
      "phoneNumber": {
        "number": "700000000",
        "countryCode": "254"
      },
      "providerCode": "MPESA"
    }
  }
}

Use GET /v1/providers to get the available providers for a given country.

Field	Required	Format	Notes
`accountName`	Yes	String	Account holder name
`phoneNumber.number`	Yes	String	Phone number
`phoneNumber.countryCode`	Yes	String	Country dialing code
`provider`	Yes	String	Provider name (e.g., `mpesa`)
`providerCode`	Yes	String	Provider code — use `GET /v1/providers`

Proxy

Proxy-based payment methods use an identifier (email, phone, or national ID) instead of traditional bank details. Used for corridors like Brazil Pix. Set preferredMethod to "proxy" and provide details in the proxy object:

{
  "paymentDetails": {
    "preferredMethod": "proxy",
    "proxy": {
      "type": "email",
      "value": "recipient@example.com"
    }
  }
}

Field	Required	Format	Notes
`type`	Yes	`email`, `mobile`, or `other`	Proxy key type
`value`	Yes	String (max 255)	The proxy identifier

Some corridors require additional fields like beneficiaryId or address. Use GET /v1/payment-requirements to check the exact requirements for each corridor.

SWIFT

For corridors without local payment rails, Cadana routes payments via SWIFT. Covers 180+ countries (USD and EUR). Set preferredMethod to "swift" and provide details in the swift object. SWIFT payments typically require more information than local transfers, including the SWIFT/BIC code, recipient address, and either iban or accountNumber depending on the destination.

Field	Required	Format	Notes
`accountName`	Yes	String (max 60)	Account holder name
`accountNumber`	Yes	String (max 255)	Account number
`swiftCode`	Yes	8 or 11 chars	SWIFT/BIC code
`bankName`	Yes	String (max 255)	Bank name
`currency`	Yes	`USD` or `EUR`	Payment currency
`iban`	Yes	String	International Bank Account Number
`address`	Yes	Object	Recipient address (`line1`, `city`, `postalCode`, `countryCode`)

Get Started

Workforce

White-Label UI

Platform Integration

Payments

Wallets

Global Tax Engine

Embedded Tools

Payment Methods & Requirements

Discovering Available Methods

Using the Requirements API

Understanding the Response

Building Dynamic Forms

Bank Transfer

Simple — Nigeria (NGN)

Medium — United Kingdom (GBP)

Complex — Colombia (COP)

ACH

Mobile Money

Proxy

SWIFT

Next Steps

Making a Payment

Supported Countries

Get Started

Workforce

White-Label UI

Platform Integration

Payments

Wallets

Global Tax Engine

Embedded Tools

​Discovering Available Methods

​Using the Requirements API

​Understanding the Response

​Building Dynamic Forms

​Bank Transfer

​Simple — Nigeria (NGN)

​Medium — United Kingdom (GBP)

​Complex — Colombia (COP)

​ACH

​Mobile Money

​Proxy

​SWIFT

​Next Steps

Making a Payment

Supported Countries

Discovering Available Methods

Using the Requirements API

Understanding the Response

Building Dynamic Forms

Bank Transfer

Simple — Nigeria (NGN)

Medium — United Kingdom (GBP)

Complex — Colombia (COP)

ACH

Mobile Money

Proxy

SWIFT

Next Steps