​
Overview

The Create Beneficiary endpoint allows you to save recipient information for future transfers. You can create beneficiaries for bank accounts, crypto wallets, and Interac e-Transfer recipients.

Saved beneficiaries can be reused for future transfers without having to re-enter the recipient details each time.

​
Endpoint

POST /beneficiaries

​
Supported Beneficiary Types

Bank Accounts

  • NGN bank accounts

  • USD bank accounts (ACH/Wire)

  • International bank accounts

Crypto Wallets

  • USDT addresses

  • USDC addresses

  • Multiple chains such as AVAX, ETH, TRX, DOGE, ADA, SOL are supported

Interac

  • Canadian recipients via Interac

​
Create NGN Bank Account Beneficiary

​
Request Parameters

​
type
string
required

Must be “bank_account”

​
currency
string
required

Must be “NGN”

​
account_name
string
required

Account holder’s name as registered with bank

​
account_number
string
required

10-digit Nigerian bank account number

​
bank_name
string
required

Full bank name

​
bank_code
string
required

Bank’s unique code - get from List Banks endpoint

​
rail
string
required

Must be nuban

​
Example Request

{
  "type": "bank_account",
  "currency": "NGN",
  "account_name": "John Doe",
  "account_number": "0123456789",
  "bank_name": "First Bank of Nigeria",
  "bank_code": "011",
  "rail": "nuban"
}

​
Create USD Bank Account Beneficiary

​
Request Parameters

​
type
string
required

Must be “bank_account”

​
currency
string
required

Must be “USD”

​
routing_number
string
required

9-digit ABA routing number

​
rail
string
required

Payment rail to use (“ach” or “wire”)

​
sort_code
string

Bank sort code (if required)

​
address
object
required

Beneficiary’s address information

​
bank_address
object
required

Bank’s physical address

​
Example Request

{
  "type": "bank_account",
  "currency": "USD",
  "routing_number": "123456789",
  "rail": "ach",
  "sort_code": "123456",
  "address": {
    "line1": "15 High Road",
    "line2": "Unit 12",
    "city": "New York",
    "state": "NY",
    "country": "US",
    "zip_code": "10003"
  },
  "bank_address": {
    "line1": "20 Finance Blvd",
    "line2": "Suite 200",
    "city": "Los Angeles",
    "state": "CA",
    "country": "US",
    "zip_code": "90001"
  }
}

​
Create Interac e-Transfer Beneficiary

​
Request Parameters

​
type
string
required

Must be “interac”

​
currency
string
required

Must be “CAD”

​
beneficiary_type
string
required

Type of recipient (“personal” or “business”)

​
first_name
string
required

Recipient’s first name

​
last_name
string
required

Recipient’s last name

​
email
string
required

Recipient’s email registered with Interac

​
phone_number
string

Recipient’s phone number (optional)

​
question
string
required

Security question for manual deposits

​
answer
string
required

Answer to security question

​
Example Request

{
  "type": "interac",
  "currency": "CAD",
  "beneficiary_type": "personal",
  "first_name": "Alice",
  "last_name": "Smith",
  "email": "alice@example.com",
  "question": "What is your pet's name?",
  "answer": "Fluffy",
  "phone_number": "1234567890"
}

​
Create Crypto Address Beneficiary

​
Request Parameters

​
type
string
required

Must be “crypto_address”

​
label
string
required
​
currency
string
required

Must be one of USDC, USDT

​
chain
string
required

Multiple chains such as AVAX, ETH, TRX, DOGE, ADA, SOL are supported

​
address
string
required

Must be a supported crypto address based on the currency and chain

​
Example Request

{
  "type": "crypto_address",
  "label": "Test wallet",
  "currency": "USDC|USDT",
  "chain": "ETH|TRX|DOGE|ADA|SOL|AVAX",
  "address": "0x..."
}

​
Response Format

​
data
object

Created beneficiary details

​
Success Response Example

{
  "data": {
    "account_name": "Michael Asaju",
    "account_number": "8036120312",
    "account_type": "savings",
    "address": null,
    "bank_address": null,
    "bank_code": "100004",
    "bank_id": null,
    "bank_name": "OPAY",
    "bic": null,
    "currency": "NGN",
    "id": "d71efb6e-b7f5-4acd-a729-3da08e36eaed",
    "lifetime": "permanent",
    "routing_number": null,
    "sort_code": null,
    "type": "bank_account",
    "user_id": "c545cbc5-9915-4bfb-98ee-3759894feac2",
    "virtual": false
  }
}

​
Error Handling

​
Validation Rules

  1. NGN Bank Accounts

    • Account numbers must be 10 digits

    • Bank code must be valid

    • Account name must match bank records

  2. USD Bank Accounts

    • Routing numbers must be 9 digits

    • Valid US state codes required

    • ZIP codes must match state

  3. Interac e-Transfer

    • Valid Canadian email required

    • Security question required if auto-deposit not enabled

    • Phone number must be Canadian format

Need Help?

For additional assistance: