Skip to main content
PATCH
Update Beneficiary
Update the details of an existing saved beneficiary.
PATCH is the current update verb. PUT /beneficiaries/{beneficiaryId} remains supported as a backward-compatible alias with identical behaviour, but new integrations should use PATCH. Both verbs run the same handler and the same validation schema, so requests and responses are identical.

Example Request

PATCH/PUT is also how you backfill the new classification fields on an existing beneficiary that predates them — send account_owner_type (and account_category for USD) to bring a legacy record into compliance.

Example Response

The updated beneficiary is returned directly under data, in the same shape as Get Beneficiary. During the grace period a deprecation_warning object is appended when a required classification field is missing, exactly as on create.

Error Response

Every failure, including an unknown beneficiaryId, returns 400:
Schema failures return 400 with "message": "Validation failed" and an errors array, as on create.
The same validation rules apply as when creating a beneficiary, including the new account_owner_type and account_category fields and their grace-period behaviour. See the Create Beneficiary endpoint for required fields by withdrawal method, and the Beneficiary Account Fields migration guide.
The body is validated as a whole, not as a partial patch — send the method’s full required field set, not just the fields you are changing. In particular, a beneficiary on "withdrawal_method": "ach" or "domestic_wire" must include routing_number in the same request, now that it is enforced for both rails. Omit withdrawal_method to keep the current rail; send null or "" to clear it.

Authorizations

X-API-Key
string
header
required

Your Rolla API key

Path Parameters

beneficiaryId
string<uuid>
required

Beneficiary UUID

Body

application/json

Validated as a whole, not as a partial patch: send the full required field set for the beneficiary's withdrawal_method, not only the fields you are changing.

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 updated successfully

status
integer
required
Example:

200

message
string
required
Example:

"Beneficiary updated successfully"

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.

deprecation_warning
object

Present only during the grace period, when a required classification field (account_owner_type, account_category) was omitted.