Skip to main content
POST
/
beneficiaries
Create Beneficiary
curl --request POST \
  --url https://api.rolla.xyz/api/v1/external/beneficiaries \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "currency": "NGN",
  "label": "<string>",
  "account_name": "JOHN DOE",
  "account_number": "0123456789",
  "bank_name": "Access Bank",
  "bank_code": "000014",
  "bank_address": "<string>",
  "swift_code": "<string>",
  "email": "jsmith@example.com",
  "contact_person": "<string>",
  "beneficiary_address": "<string>",
  "withdrawal_method": "domestic_wire",
  "routing_number": "<string>",
  "wallet_address": "<string>",
  "wallet_chain": "<string>",
  "intermediary_bank_name": "<string>",
  "intermediary_bank_routing_number": "<string>"
}
'
{
  "success": true,
  "message": "Beneficiary created successfully",
  "data": {
    "beneficiary": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "currency": "NGN",
      "label": "Office rent",
      "account_name": "JOHN DOE",
      "account_number": "0123456789",
      "bank_name": "Access Bank",
      "bank_code": "000014",
      "bank_address": "<string>",
      "swift_code": "<string>",
      "email": "jsmith@example.com",
      "contact_person": "<string>",
      "beneficiary_address": "<string>",
      "withdrawal_method": "domestic_wire",
      "routing_number": "<string>",
      "wallet_address": "<string>",
      "wallet_chain": "<string>",
      "intermediary_bank_name": "<string>",
      "intermediary_bank_routing_number": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  }
}
Create a new saved beneficiary for your business. The required fields depend on the withdrawal method and currency.

​
Example Request (NGN Domestic Wire)

curl -X POST "https://api.rolla.xyz/api/v1/external/beneficiaries" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "NGN",
    "label": "Office rent",
    "account_name": "JOHN DOE",
    "account_number": "0123456789",
    "bank_name": "Access Bank",
    "bank_code": "000014",
    "withdrawal_method": "domestic_wire",
    "email": "john@example.com"
  }'

​
Example Request (Crypto USDT)

curl -X POST "https://api.rolla.xyz/api/v1/external/beneficiaries" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "label": "Crypto payout",
    "account_name": "Jane Doe",
    "withdrawal_method": "crypto_usdt",
    "wallet_address": "0x1234567890abcdef1234567890abcdef12345678",
    "wallet_chain": "ethereum"
  }'

​
Example Response

{
  "success": true,
  "message": "Beneficiary created successfully",
  "data": {
    "beneficiary": {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "currency": "NGN",
      "label": "Office rent",
      "account_name": "JOHN DOE",
      "account_number": "0123456789",
      "bank_name": "Access Bank",
      "bank_code": "000014",
      "withdrawal_method": "domestic_wire",
      "email": "john@example.com",
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z"
    }
  }
}

​
Required Fields by Withdrawal Method

MethodRequired Fields
domestic_wire (NGN)account_name, account_number, bank_name, bank_code
international_wireaccount_name, account_number, bank_name
crypto_usdt / crypto_usdcaccount_name, wallet_address
For NGN beneficiaries, use the /beneficiaries/beneficiary-lookup endpoint first to validate the account and retrieve the correct account name.

Authorizations

​
X-API-Key
string
header
required

Your Rolla API key

Body

application/json
​
currency
string
required

Currency code (e.g., NGN, USD)

Example:

"NGN"

​
label
string

Friendly label for the beneficiary

​
account_name
string

Account holder name

Maximum string length: 100
Example:

"JOHN DOE"

​
account_number
string

Bank account number

Maximum string length: 50
Example:

"0123456789"

​
bank_name
string

Bank name

Maximum string length: 100
Example:

"Access Bank"

​
bank_code
string

Bank code (required for NGN beneficiaries)

Maximum string length: 20
Example:

"000014"

​
bank_address
string

Bank address (for international wires)

Maximum string length: 500
​
swift_code
string

SWIFT/BIC code (for international wires)

Maximum string length: 20
​
email
string<email>

Beneficiary email

Maximum string length: 100
​
contact_person
string

Contact person name

Maximum string length: 100
​
beneficiary_address
string

Beneficiary address

Maximum string length: 500
​
withdrawal_method
enum<string>

Withdrawal method

Available options:
domestic_wire,
international_wire,
crypto_usdt,
crypto_usdc
​
routing_number
string

Routing number (for US wires)

Maximum string length: 20
​
wallet_address
string

Crypto wallet address (for crypto withdrawals)

​
wallet_chain
string

Blockchain network (for crypto withdrawals)

Maximum string length: 50
​
intermediary_bank_name
string

Intermediary bank name

Maximum string length: 255
​
intermediary_bank_routing_number
string

Intermediary bank routing number

Maximum string length: 50

Response

Beneficiary created successfully

​
success
boolean
Example:

true

​
message
string
Example:

"Beneficiary created successfully"

​
data
object