Overview

The Beneficiaries API allows you to create, manage, and use payment recipients for your financial operations. Beneficiaries are entities that can receive funds from your accounts, and they can be individuals or businesses with various payment method types depending on their location and currency.

Key features of the Beneficiaries API:

Create and manage fiat currency beneficiaries
Support for multiple payment method types (SWIFT, ACH, FedWire, NUBAN, SEPA, Faster Payments)
Country-specific payment method validation
Search and filter beneficiaries
Update beneficiary details
Delete beneficiaries when no longer needed

The API simplifies the process of storing recipient information for repeated use, ensuring compliance with payment regulations, and enabling efficient fund transfers to your business partners, suppliers, employees, and customers around the world.

The Beneficiary Object

Property	Type	Required	Description
id	string (UUID)	✅	Unique identifier of the beneficiary.
state	enum	✅	Current state of the beneficiary (ACTIVE, INACTIVE).
created_date	string (datetime)	✅	Date and time when the beneficiary was created.
updated_date	string (datetime)	✅	Date and time when the beneficiary was last updated.
type	enum	✅	Type of the beneficiary (always "FIAT" for fiat currency beneficiaries).
country	string	✅	ISO 2-letter country code of the beneficiary.
address	object	❌	Physical address of the beneficiary (required for most non-NGN beneficiaries).
kind	enum	✅	Kind of beneficiary ("INDIVIDUAL" or "BUSINESS").
name	string	✅	Account holder name of the beneficiary.
friendly_name	string	❌	Optional custom name for easier identification.
currency	string	✅	Currency code the beneficiary can receive (ISO 4217).
email	string	❌	Email address of the beneficiary (required for most non-NGN beneficiaries).
is_own_account	boolean	✅	Whether this beneficiary is your own account (default: false).
client_reference	string	❌	Your custom reference for this beneficiary.
method	object	✅	Payment method details (varies by type).

Beneficiary Method Object Structure

The method object in a beneficiary is a structured field that specifies how funds will be sent to this recipient. It consists of two key parts:

A type field that identifies the payment method category
A details object containing the specific payment information for that type

{
  "method": {
    "type": "PAYMENT_METHOD_TYPE",
    "details": {
      // Varies by type - contains the specific fields required for that payment method
    }
  }
}

The type field is always one of the following values:

"NUBAN" - Nigerian bank accounts
"SWIFT" - International wire transfers
"ACH" - US domestic electronic transfers
"FED_WIRE" - US domestic wire transfers
"SEPA" - European zone payments
"FASTER_PAYMENTS" - UK domestic transfers

The details object's structure changes completely based on the type. For example:

A "NUBAN" type requires Nigerian bank details
A "SWIFT" type requires international banking details with SWIFT/BIC codes
A "SEPA" type requires IBAN and European bank information

This flexible structure allows the API to accommodate the diverse requirements of different payment systems worldwide while maintaining a consistent top-level structure.

Supported Methods

1. NUBAN (Nigerian Bank Account)

Nigerian Uniform Bank Account Number for payments to Nigerian bank accounts in NGN.

Parameter	Type	Required	Description
account_number	string	✅	10-digit Nigerian bank account number.
bank_code	string	✅	3-6 digit bank code for the Nigerian bank.
account_name	string	✅	Name of the account holder as registered with the bank.
bank_name	string	❌	Bank name

{
    "type": "NUBAN",
    "details": {
        "account_number": "0123456789",
        "bank_code": "033",
        "account_name": "Alan Turing"
    }
}

2. SWIFT (International Wire Transfer)

SWIFT/BIC-based transfers for international payments across various currencies.

Parameter	Type	Required	Description
swift_bic	string	✅	SWIFT/BIC code (8-11 characters) of the beneficiary bank.
account_number	string	✅	Account number or IBAN of the beneficiary.
bank_name	string	✅	Full name of the beneficiary bank.
bank_address	object	✅	Physical address of the beneficiary bank.
bank_address.line_1	string	✅	Street address of the bank.
bank_address.city	string	✅	City where the bank is located.
bank_address.state	string	❌	State/province where the bank is located (required for some countries).
bank_address.postal_code	string	❌	Postal/ZIP code (required for some countries).
bank_address.country	string	✅	ISO-2 country code of the bank.
intermediary_bank	object	❌	Details of an intermediary bank if required for routing.
intermediary_bank.name	string	❌	Name of the intermediary bank.
intermediary_bank.swift_bic	string	❌	SWIFT/BIC code of the intermediary bank.
intermediary_bank.account_number	string	❌	Account number at the intermediary bank.
intermediary_bank.address	object	❌	Address of the intermediary bank.
intermediary_bank.routing_number	string	❌	Routing number for the intermediary bank.
intermediary_bank.instructions	string	❌	Special instructions for the intermediary bank.

{
    "type": "SWIFT",
    "details": {
        "swift_bic": "CHASUS33",
        "account_number": "000123456789",
        "bank_name": "JPMorgan Chase Bank",
        "bank_address": {
            "line_1": "270 Park Avenue",
            "city": "New York",
            "state": "NY",
            "postal_code": "10017",
            "country": "US"
        },
        "intermediary_bank": {
            "name": "Citibank",
            "swift_bic": "CITIUS33",
            "account_number": "36838007",
            "address": {
                "line_1": "388 Greenwich Street",
                "city": "New York",
                "state": "NY",
                "postal_code": "10013",
                "country": "US"
            }
        }
    }
}

3. ACH (US Automated Clearing House)

For domestic US transfers in USD using the ACH network.

Parameter	Type	Required	Description
account_number	string	✅	US bank account number (8-17 digits).
routing_number	string	✅	9-digit ACH routing number.
bank_name	string	✅	Name of the US banking institution.
account_type	enum	✅	Type of bank account: "checking" or "savings".
bank_address	object	✅	Physical address of the US bank.
bank_address.line_1	string	✅	Street address of the bank.
bank_address.line_2	string	❌	Additional address information.
bank_address.city	string	✅	City where the bank is located.
bank_address.state	string	✅	US state where the bank is located.
bank_address.postal_code	string	✅	US ZIP code.
bank_address.country	string	✅	Must be "US".

{
    "type": "ACH",
    "details": {
        "account_number": "12345678901",
        "routing_number": "021000021",
        "bank_name": "Bank of America",
        "account_type": "checking",
        "bank_address": {
            "line_1": "100 Federal Street",
            "city": "Boston",
            "state": "MA",
            "postal_code": "02110",
            "country": "US"
        }
    }
}

4. FED_WIRE (US Fedwire)

For domestic US wire transfers in USD using the Fedwire system.

Parameter	Type	Required	Description
account_number	string	✅	US bank account number (8-17 digits).
routing_number	string	✅	9-digit Fedwire routing number.
bank_name	string	✅	Name of the US bank.
bank_address	object	✅	Physical address of the US bank.
bank_address.line_1	string	✅	Street address of the bank.
bank_address.line_2	string	❌	Additional address information.
bank_address.city	string	✅	City where the bank is located.
bank_address.state	string	✅	US state where the bank is located.
bank_address.postal_code	string	✅	US ZIP code.
bank_address.country	string	✅	Must be "US".

{
    "type": "FED_WIRE",
    "details": {
        "account_number": "12345678901",
        "routing_number": "021000021",
        "bank_name": "Wells Fargo",
        "bank_address": {
            "line_1": "420 Montgomery Street",
            "city": "San Francisco",
            "state": "CA",
            "postal_code": "94104",
            "country": "US"
        }
    }
}

5. SEPA (Single Euro Payments Area)

For EUR transfers within the SEPA zone (EU/EEA countries).

Parameter	Type	Required	Description
iban	string	✅	International Bank Account Number (15-34 characters).
bic_swift	string	✅	BIC/SWIFT code of the beneficiary bank (8-11 characters).
bank_name	string	✅	Name of the beneficiary bank.
bank_address	object	❌	Physical address of the beneficiary bank (optional).
bank_address.line_1	string	❌	Street address of the bank.
bank_address.city	string	❌	City where the bank is located.
bank_address.postal_code	string	❌	Postal code.
bank_address.country	string	❌	ISO-2 country code within the SEPA zone.

{
    "type": "SEPA",
    "details": {
        "iban": "DE89370400440532013000",
        "bic_swift": "DEUTDEFF",
        "bank_name": "Deutsche Bank"
    }
}

6. FASTER_PAYMENTS (UK Faster Payments)

For domestic UK GBP transfers using the Faster Payments Service.

Parameter	Type	Required	Description
account_number	string	✅	8-digit UK bank account number.
sort_code	string	✅	6-digit UK bank sort code (without hyphens).
bank_name	string	✅	Name of the UK bank.
bank_address	object	❌	Physical address of the UK bank (optional).
bank_address.line_1	string	❌	Street address of the bank.
bank_address.city	string	❌	City where the bank is located.
bank_address.postal_code	string	❌	UK postal code.
bank_address.country	string	❌	Must be "GB" if provided.

{
    "type": "FASTER_PAYMENTS",
    "details": {
        "account_number": "12345678",
        "sort_code": "123456",
        "bank_name": "Barclays Bank"
    }
}

Method Type Selection by Country and Currency

Country	Currency	Recommended Method(s)	Notes
NG	NGN	NUBAN	Required for all domestic Nigerian payments
US	USD	ACH	For lower-cost domestic US transfers (slower)
US	USD	FED_WIRE	For same-day domestic US transfers (higher fees)
EU Countries	EUR	SEPA	For payments within the SEPA zone
GB	GBP	FASTER_PAYMENTS	For domestic UK payments
Any	Any	SWIFT	Universal method for international payments
KE	KES	MOBILE_MONEY, BANK_ACCOUNT	Mobile money B2C, Paybill and Till are available as well as local bank payments

By understanding the requirements for each payment method type and following best practices, you can ensure smooth and efficient management of your payment recipients.