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 except NGN 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. A Rolla transfer beneficiary is not scoped by currency: one record per recipient serves every currency you pay them in. Saving the same recipient_business_id again returns the existing record with 200 and the message Beneficiary already saved (a new label, if sent, is applied).

Example Response

A new beneficiary returns 201. The beneficiary is returned directly under data; only populated fields are included, except withdrawal_method, which is always present and is null when no rail was set.

Validation error

Requests that fail schema validation return 400 with one entry per offending field:
Other rejections (unsupported currency, duplicate account number or wallet address, unsupported crypto network) also return 400 with a descriptive message and no errors array.

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)

enforcement_date is null until the date has been set.

Required Fields by Withdrawal Method

Both beneficiary_address and bank_address are objects with the following fields: Missing or blank address parts on ach, domestic_wire and international_wire are rejected with a 400 validation error naming each part (for example bank_address.city).
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

Which other fields are required depends on withdrawal_method and currency; see the "Required Fields by Withdrawal Method" table on Create Beneficiary. The same schema is validated as a whole on PATCH and PUT.

currency
string
required

Currency code (e.g., NGN, USD). Must be a supported wallet or FX corridor currency.

Maximum string length: 10
Example:

"NGN"

label
string

Friendly label for the beneficiary

Example:

"Office rent"

account_name
string

Account holder name. Required on every rail except mobile_money (for crypto and rolla_transfer it is the nickname).

Maximum string length: 100
Example:

"JOHN DOE"

account_number
string

Bank account number. Required for ach, domestic_wire and international_wire; surrounding whitespace is trimmed.

Maximum string length: 50
Example:

"0123456789"

bank_name
string

Bank name. Required for ach, domestic_wire and international_wire.

Maximum string length: 100
Example:

"Access Bank"

bank_code
string

Nigerian bank code from List Nigerian Banks. Required whenever currency is NGN and account_number is sent.

Maximum string length: 20
Example:

"000014"

bank_address
object

Postal address. On ach, domestic_wire and international_wire every part is required and country must be a two-letter ISO 3166-1 code; a missing part is rejected with a 400 naming the field (e.g. bank_address.city). Optional on every other rail.

swift_code
string

SWIFT/BIC code (required for international wire)

Maximum string length: 20
email
string<email>

Beneficiary email

Maximum string length: 100
Example:

"john@example.com"

contact_person
string

Contact person name

Maximum string length: 100
beneficiary_address
object

Postal address. On ach, domestic_wire and international_wire every part is required and country must be a two-letter ISO 3166-1 code; a missing part is rejected with a 400 naming the field (e.g. bank_address.city). Optional on every other rail.

withdrawal_method
enum<string> | null

Payout rail. Omit (or send null) for an NGN bank transfer. On update, omit to keep the current rail; null or "" clears it.

Available options:
domestic_wire,
international_wire,
ach,
local_transfer,
crypto_usdt,
crypto_usdc,
rolla_transfer,
mobile_money
routing_number
string

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

Maximum string length: 20
wallet_address
string

Crypto wallet address (required for crypto_usdt / crypto_usdc). 26 to 64 alphanumeric characters; validated against the network.

Required string length: 26 - 64
wallet_chain
string

Blockchain network slug (required for crypto_usdt / crypto_usdc), e.g. base, tron, ethereum. Stored as the canonical slug.

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
iban
string

IBAN, for banks that use one instead of an account number

Maximum string length: 50
bic
string

BIC, where it differs from swift_code

Maximum string length: 20
sort_code
string

UK sort code

Maximum string length: 10
recipient_business_id
string<uuid>

Required for rolla_transfer. The UUID of the destination Rolla business (not your own).

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 except NGN (ach, domestic_wire, international_wire). Accepted but not required for NGN. Not applicable to crypto_usdt, crypto_usdc, mobile_money 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"

mobile_money_provider
string

Mobile money operator slug (required for mobile_money)

Maximum string length: 100
phone_number
string

Mobile money wallet number (required for mobile_money)

Maximum string length: 30

Response

Beneficiary already saved - a rolla_transfer recipient_business_id you had already saved; the existing record is returned

status
integer
required
Example:

200

message
string
required
Example:

"Beneficiary already saved"

success
boolean
required
Example:

true

data
object
required

A saved beneficiary as returned to API-key callers. Only populated fields are included: a fiat beneficiary never carries wallet fields and a crypto beneficiary never carries bank fields, and empty values are dropped. withdrawal_method is always present and is null when no rail was set. Timestamps and internal ids (business_id, recipient_business_id) are not returned.