Skip to main content
POST
Create Beneficiary
Create a new saved beneficiary for your business. The required fields depend on the withdrawal_method and currency.
New required fields (account_owner_type, account_category). Every bank-account beneficiary must now declare account_owner_type (individual or business), and every USD beneficiary must also declare account_category (checking or savings). During a 60-day grace period, requests that omit these fields still succeed but return a deprecation_warning in the response; after the enforcement date they are rejected with a 400. See Beneficiary Account Fields for the full migration guide.

​
Example Request (NGN Bank Transfer)

For Nigerian Naira transfers, omit withdrawal_method (or set it to null). bank_code is always required for NGN.

​
Example Request (Domestic Wire — USD)

​
Example Request (ACH — USD)

ACH is the low-cost domestic US rail. It reaches the same US bank accounts as a domestic wire but settles in business days rather than same-day, and is usually priced lower — so quote the fee per rail rather than assuming they match. Use account_category to say whether the destination is a checking or savings account.
routing_number is the beneficiary bank’s 9-digit ABA number and is required for both ach and domestic_wire — those rails are addressed by routing number, so a beneficiary saved without one can never be paid and is rejected with a 400. international_wire uses swift_code instead and is unaffected.
The domestic_wire requirement is newly enforced. It has always been listed as required below, but the server previously accepted domestic wire beneficiaries without a routing_number. If you have saved any, backfill them via PATCH /beneficiaries/{beneficiaryId} — otherwise the next update to that beneficiary will be rejected.

​
Example Request (International Wire — USD)

​
Example Request (Crypto USDC)

​
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.
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

​
Account Classification Fields

For compliant payout routing, bank-account beneficiaries carry two classification fields:
These fields are being rolled out with a 60-day grace period. Requests that omit a required field currently still succeed but include a deprecation_warning object in the response (see below). After the enforcement date, the same request is rejected with a 400. Send the fields now to avoid disruption. Full details in the Beneficiary Account Fields migration guide.

​
Deprecation warning (during grace period)

​
Required Fields by Withdrawal Method

Both beneficiary_address and bank_address are objects with the following fields:
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,
ach,
crypto_usdt,
crypto_usdc,
rolla_transfer
​
routing_number
string

9-digit ABA routing number. Required for USD ach and domestic_wire.

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"

​
account_owner_type
enum<string>

Whether the account is held by an individual or a business. Required for every bank-account beneficiary (any fiat method that is not crypto or rolla_transfer, including NGN bank transfer, domestic_wire, and international_wire). Not applicable to crypto_usdt, crypto_usdc, or rolla_transfer. During the deprecation grace period, requests that omit this field still succeed but return a deprecation_warning object; after the enforcement date the request is rejected with a 400. See the Beneficiary Account Fields migration guide.

Available options:
individual,
business
Example:

"business"

​
account_category
enum<string>

Whether a USD account is checking or savings. Required only when currency is USD. If you are not sure, use "checking". Subject to the same grace-period behaviour as account_owner_type.

Available options:
checking,
savings
Example:

"checking"

Response

Beneficiary created successfully

​
success
boolean
Example:

true

​
message
string
Example:

"Beneficiary created successfully"

​
data
object