Create Beneficiary

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

Show Address Fields

line1

string

required

Street address

line2

string

Additional address info

city

string

required

City name

state

string

required

State code

country

string

required

2-letter country code

zip_code

string

required

ZIP/Postal code

bank_address

object

required

Bank’s physical address

Show Bank Address Fields

line1

string

required

Street address

line2

string

Additional address info

city

string

required

City name

state

string

required

State code

country

string

required

2-letter country code

zip_code

string

required

ZIP/Postal code

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

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

Show Response Fields

string

Unique beneficiary identifier

type

string

Beneficiary type

currency

string

Currency code

account_name

string

For bank accounts: Account holder name

account_number

string

For bank accounts: Account number

account_type

string

For bank accounts: Account type

bank_name

string

For bank accounts: Bank name

bank_code

string

For bank accounts: Bank code

routing_number

string

For USD accounts: ABA routing number

user_id

string

ID of creating user

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

400 - Invalid Request

422 - Validation Error

409 - Duplicate Error

Validation Rules

NGN Bank Accounts
- Account numbers must be 10 digits
- Bank code must be valid
- Account name must match bank records
USD Bank Accounts
- Routing numbers must be 9 digits
- Valid US state codes required
- ZIP codes must match state
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:

Check our API Reference
Contact Support
Review our Error Handling Guide

Home

Customers

Payments

Payment Transactions

Transfers

Exchange

Overview

Endpoint

Supported Beneficiary Types

Bank Accounts

Crypto Wallets

Interac

Create NGN Bank Account Beneficiary

Request Parameters

Example Request

Create USD Bank Account Beneficiary

Request Parameters

Example Request

Create Interac e-Transfer Beneficiary

Request Parameters

Example Request

Create Crypto Address Beneficiary

Request Parameters

Example Request

Response Format

Success Response Example

Error Handling

Validation Rules

Need Help?

Home

Customers

Payments

Payment Transactions

Transfers

Exchange

​Overview

​Endpoint

​Supported Beneficiary Types

Bank Accounts

Crypto Wallets

Interac

​Create NGN Bank Account Beneficiary

​Request Parameters

​Example Request

​Create USD Bank Account Beneficiary

​Request Parameters

​Example Request

​Create Interac e-Transfer Beneficiary

​Request Parameters

​Example Request

​Create Crypto Address Beneficiary

​Request Parameters

​Example Request

​Response Format

​Success Response Example

​Error Handling

​Validation Rules

Need Help?

Overview

Endpoint

Supported Beneficiary Types

Create NGN Bank Account Beneficiary

Request Parameters

Example Request

Create USD Bank Account Beneficiary

Request Parameters

Example Request

Create Interac e-Transfer Beneficiary

Request Parameters

Example Request

Create Crypto Address Beneficiary

Request Parameters

Example Request

Response Format

Success Response Example

Error Handling

Validation Rules