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

string

required

Must be “bank_account”

string

required

Must be “NGN”

string

required

Account holder’s name as registered with bank

string

required

10-digit Nigerian bank account number

string

required

Full bank name

string

required

Bank’s unique code - get from List Banks endpoint

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

string

required

Must be “bank_account”

string

required

Must be “USD”

string

required

9-digit ABA routing number

string

required

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

string

Bank sort code (if required)

object

required

Beneficiary’s address information

Show Address Fields

string

required

Street address

string

Additional address info

string

required

City name

string

required

State code

string

required

2-letter country code

string

required

ZIP/Postal code

object

required

Bank’s physical address

Show Bank Address Fields

string

required

Street address

string

Additional address info

string

required

City name

string

required

State code

string

required

2-letter country 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

string

required

Must be “interac”

string

required

Must be “CAD”

string

required

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

string

required

Recipient’s first name

string

required

Recipient’s last name

string

required

Recipient’s email registered with Interac

string

Recipient’s phone number (optional)

string

required

Security question for manual deposits

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

string

required

Must be “crypto_address”

string

required

string

required

Must be one of USDC, USDT

string

required

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

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

object

Created beneficiary details

Show Response Fields

string

Unique beneficiary identifier

string

Beneficiary type

string

Currency code

string

For bank accounts: Account holder name

string

For bank accounts: Account number

string

For bank accounts: Account type

string

For bank accounts: Bank name

string

For bank accounts: Bank code

string

For USD accounts: ABA routing number

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

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid parameters provided",
    "details": {
      "account_number": ["Invalid account number format"]
    }
  }
}

422 - Validation Error

{
  "error": {
    "code": "validation_error",
    "message": "Invalid beneficiary details",
    "details": {
      "routing_number": ["Must be 9 digits for US banks"]
    }
  }
}

409 - Duplicate Error

{
  "error": {
    "code": "duplicate_beneficiary",
    "message": "A beneficiary with these details already exists"
  }
}

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

Wallet As A Service

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

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