Overview

The Beneficiary API Suite allows businesses to process payments across different countries using multiple payment methods. Each payment method requires specific information to ensure seamless transactions.

This guide provides:

• A quick reference table of payment methods, supported countries, and required fields.
• Detailed field requirements for each payment method, including validation rules.
• Bank and Beneficiary Address details, outlining mandatory and optional fields.

1. Payment Methods by Country

The table below outlines the available payment methods, their supported countries, currencies, and required fields:

• Optional fields

Note: bank_address.line_2 is optional for all methods.

2. Detailed Field Requirements

Each payment method has unique field validation rules. Below is a breakdown:

2.1 SWIFT Payments

• swift_bic: 8-11 characters, must be valid BIC format
• account_number: Up to 34 characters
• bank_name: Up to 64 characters, trimmed
• bank_address (Required object):
  • line_1: 1-128 characters, required, trimmed
  • line_2: Up to 128 characters, optional, trimmed
  • city: 1-64 characters, required, trimmed
  • state: 1-64 characters, optional, trimmed
  • postal_code: 2-16 characters, optional, trimmed
  • country: Required, must be a valid CountryCode enum value
• routing_number: Optional, up to 16 characters, trimmed
• intermediary_bank (Optional object):
  • name: Up to 64 characters, trimmed
  • swift_bic: 8-11 characters, must be valid BIC
  • account_number: Optional, up to 34 characters, trimmed
  • address: Optional bank_address object (same structure as above)
  • routing_number: Optional, up to 16 characters, trimmed
  • instructions: Optional, up to 128 characters, trimmed

.

2.2 ACH Payments (US Only)

• account_number: 8-17 digits, numeric only
• routing_number: Exactly 9 digits, numeric only
• bank_name: Required string
• account_type: Must be "checking" or "savings" (enum validation)
• bank_address: Required, same structure as in SWIFT

2.3 FED_WIRE Payments (US Domestic Wire)

• account_number: 8-17 digits, numeric only, trimmed
• routing_number: Exactly 9 digits, numeric only, trimmed
• bank_name: Required string
• bank_address: Required, same structure as in SWIFT

2.4 NUBAN Payments (Nigeria Only)

• account_number: Exactly 10 digits, numeric only, trimmed
• bank_code: 3-6 digits, numeric only, trimmed
• account_name: Up to 128 characters, trimmed

2.5 Faster Payments (UK Only)

• account_number: Exactly 8 digits, numeric only, trimmed
• sort_code: Exactly 6 digits (without hyphens), numeric only, trimmed
• bank_name: Up to 64 characters, trimmed
• bank_address: Optional, same structure as in SWIFT

2.6 SEPA Payments (EU + UK)

• iban: Up to 34 characters, validated with, trimmed
• bic_swift: 8-11 characters, valid BIC format, trimmed
• bank_name: Up to 64 characters, trimmed
• bank_address: Optional, same structure as in SWIFT

**2.7 Mobile Money Payment (Kenya)

3. Address Object Details

3.1 Bank Address

The bank_address object is structured as follows:

{
  "line_1": "string",         // Required, 1-128 characters
  "line_2": "string",         // Optional, up to 128 characters
  "city": "string",           // Required, 1-64 characters
  "state": "string",          // Optional for most, Required for some, 1-64 characters
  "postal_code": "string",    // Optional (except for US), 2-16 characters
  "country": "CountryCode"    // Required, enum value
}

3.2 Beneficiary Address

Similar but with slight differences:

{
  "line_1": "string",         // Required, 1-128 characters
  "line_2": "string",         // Optional, up to 128 characters
  "city": "string",           // Required, 1-64 characters
  "state": "string",          // Required, 1-64 characters
  "postal_code": "19808",    // Optional (but required for US), 2-16 characters
  "country": "US"    // Optional, enum value
}

❗️

Additional Considerations

• An email is required for all payment methods except NUBAN and MOBILE_MONEY
• A beneficiary address is mandatory for all currencies
• US addresses must include postal codes
• Metadata must be less than 1KB
• If the beneficiary address country is unspecified, it defaults to the main country field
• All string fields are automatically trimmed
• Bank and address validations vary slightly across payment methods