> ## Documentation Index
> Fetch the complete documentation index at: https://docs.juicyway.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Beneficiary
> Create and save beneficiaries for transfers across multiple payment methods
## 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
```bash theme={null}
POST /beneficiaries
```
## Supported Beneficiary Types
* NGN bank accounts
* USD bank accounts (ACH/Wire)
* International bank accounts
* USDT addresses
* USDC addresses
* Multiple chains such as AVAX, ETH, TRX, DOGE, ADA, SOL are supported
* Canadian recipients via Interac
## Create NGN Bank Account Beneficiary
### Request Parameters
Must be "bank\_account"
Must be "NGN"
Account holder's name as registered with bank
10-digit Nigerian bank account number
Full bank name
Bank's unique code - get from [List
Banks](/transfers/transfers/list-ngn-banks) endpoint
Must be nuban
### Example Request
```json theme={null}
{
"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
Must be "bank\_account"
Must be "USD"
9-digit ABA routing number
Payment rail to use ("ach" or "wire")
Bank sort code (if required)
Beneficiary's address information
Street address
Additional address info
City name
State code
2-letter country code
ZIP/Postal code
Bank's physical address
Street address
Additional address info
City name
State code
2-letter country code
ZIP/Postal code
### Example Request
```json theme={null}
{
"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
Must be "interac"
Must be "CAD"
Type of recipient ("personal" or "business")
Recipient's first name
Recipient's last name
Recipient's email registered with Interac
Recipient's phone number (optional)
Security question for manual deposits
Answer to security question
### Example Request
```json theme={null}
{
"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
Must be "crypto\_address"
Must be one of `USDC`, `USDT`
Multiple chains such as AVAX, ETH, TRX, DOGE, ADA, SOL are supported
Must be a supported crypto address based on the currency and chain
### Example Request
```json theme={null}
{
"type": "crypto_address",
"label": "Test wallet",
"currency": "USDC|USDT",
"chain": "ETH|TRX|DOGE|ADA|SOL|AVAX",
"address": "0x..."
}
```
## Response Format
Created beneficiary details
Unique beneficiary identifier
Beneficiary type
Currency code
For bank accounts: Account holder name
For bank accounts: Account number
For bank accounts: Account type
For bank accounts: Bank name
For bank accounts: Bank code
For USD accounts: ABA routing number
ID of creating user
### Success Response Example
```json theme={null}
{
"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
```json theme={null}
{
"error": {
"code": "invalid_request",
"message": "Invalid parameters provided",
"details": {
"account_number": ["Invalid account number format"]
}
}
}
```
```json theme={null}
{
"error": {
"code": "validation_error",
"message": "Invalid beneficiary details",
"details": {
"routing_number": ["Must be 9 digits for US banks"]
}
}
}
```
```json theme={null}
{
"error": {
"code": "duplicate_beneficiary",
"message": "A beneficiary with these details already exists"
}
}
```
## 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
For additional assistance:
* Check our [API Reference](/api-reference/overview)
* Contact [Support](mailto:support@juicyway.com)
* Review our [Error Handling Guide](/errors)