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: