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": {
    "street": "270 Park Ave",
    "city": "New York",
    "state": "NY",
    "postalCode": "10017",
    "country": "US"
  },
  "swift_code": "<string>",
  "email": "jsmith@example.com",
  "contact_person": "<string>",
  "beneficiary_address": {
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "US"
  },
  "routing_number": "<string>",
  "wallet_address": "<string>",
  "wallet_chain": "<string>",
  "intermediary_bank_name": "<string>",
  "intermediary_bank_routing_number": "<string>",
  "recipient_business_id": "d4e5f6a7-b8c9-0123-defa-456789012345"
}
'
{
  "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>",
      "routing_number": "<string>",
      "wallet_address": "<string>",
      "wallet_chain": "<string>",
      "intermediary_bank_name": "<string>",
      "intermediary_bank_routing_number": "<string>",
      "recipient_business_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "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 Bank Transfer)

For Nigerian Naira transfers, omit withdrawal_method (or set it to null). bank_code is always required for NGN. 
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",
    "email": "john@example.com"
  }'

​
Example Request (Domestic Wire — USD)

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",
    "withdrawal_method": "domestic_wire",
    "label": "US Supplier",
    "account_name": "John Doe",
    "account_number": "123456789",
    "bank_name": "Chase Bank",
    "routing_number": "021000021",
    "beneficiary_address": {
      "street": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    },
    "bank_address": {
      "street": "270 Park Ave",
      "city": "New York",
      "state": "NY",
      "postalCode": "10017",
      "country": "US"
    }
  }'

​
Example Request (International Wire — USD)

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",
    "withdrawal_method": "international_wire",
    "label": "US Supplier",
    "account_name": "John Doe",
    "account_number": "123456789",
    "bank_name": "Barclays Bank",
    "swift_code": "BARCGB22",
    "beneficiary_address": {
      "street": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    },
    "bank_address": {
      "street": "1 Churchill Place",
      "city": "London",
      "state": "England",
      "postalCode": "E14 5HP",
      "country": "GB"
    }
  }'

​
Example Request (Crypto USDC)

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",
    "withdrawal_method": "crypto_usdc",
    "label": "Base USDC wallet",
    "account_name": "My USDC Wallet",
    "wallet_address": "0x1234567890abcdef1234567890abcdef12345678",
    "wallet_chain": "base"
  }'

​
Example Request (Rolla Transfer)

For sending funds to another Rolla business. Use recipient_business_id to identify the target business. You can send in any supported currency. 
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",
    "withdrawal_method": "rolla_transfer",
    "label": "Partner company",
    "account_name": "Acme Corp",
    "recipient_business_id": "d4e5f6a7-b8c9-0123-defa-456789012345"
  }'
recipient_business_id is the Rolla-assigned UUID of the destination business. Each currency requires a separate beneficiary record — you cannot reuse the same recipient_business_id + currency combination.

​
Example Response

{
  "status": 201,
  "success": true,
  "message": "Beneficiary created successfully",
  "data": {
    "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": null,
    "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
NGN bank transfer (no withdrawal_method)currency, account_name, account_number, bank_name, bank_code
domestic_wire (USD)currency, account_name, account_number, bank_name, routing_number, beneficiary_address, bank_address
international_wire (USD)currency, account_name, account_number, bank_name, swift_code, beneficiary_address, bank_address
crypto_usdc / crypto_usdtcurrency, account_name, wallet_address, wallet_chain
rolla_transfercurrency, account_name, recipient_business_id
Both beneficiary_address and bank_address are objects with the following fields:
FieldRequiredNotes
streetYesStreet address
cityYesCity
stateYesState or province
postalCodeYesZip/postal code
countryYes2-letter country code (e.g. US, GB)
For NGN beneficiaries, use the /beneficiaries/beneficiary-lookup endpoint first to validate the account number and retrieve the correct account name before saving.

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
object

Bank's physical address. Required for USD domestic and international wire transfers.

​
swift_code
string

SWIFT/BIC code (required for international wire)

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
object

Beneficiary's physical address. Required for USD domestic and international wire transfers.

​
withdrawal_method
enum<string>

Withdrawal method

Available options:
domestic_wire,
international_wire,
crypto_usdt,
crypto_usdc,
rolla_transfer
​
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
​
recipient_business_id
string<uuid>

Required for rolla_transfer. The UUID of the destination Rolla business.

Example:

"d4e5f6a7-b8c9-0123-defa-456789012345"

Response

Beneficiary created successfully

​
success
boolean
Example:

true

​
message
string
Example:

"Beneficiary created successfully"

​
data
object