Skip to main content
POST
Update an account

Authorizations

Authorization
string
header
required

Bearer token authentication. Pass your API key as Authorization: Bearer sk_.... See Authentication for keys, scopes, and sandbox vs production.

Path Parameters

account_id
string
required

The account to act on. It must be one of your own accounts; any other ID returns 404 so the response never confirms that an unrelated account exists.

Body

application/json

The one account write. Set contact details, request capabilities and satisfy requirement fields in a single call. Anything you leave out is unchanged.

configuration
object

Personas to apply, and capabilities to request under them, the same nested shape as creation. Naming a persona here, with or without a capability nested under its capabilities, is what applies it if the account does not already have it: an account can start recipient-only and be given merchant later this way. Unlike creation, an omitted capabilities here never blanket-requests; it only applies the persona. A capability nested under the wrong persona for it is rejected with 400 capability_configuration_mismatch. Only names set to true are acted on; any name set to false fails the whole request with 400 capability_unrequest_unsupported. Capabilities the account already holds are unaffected, and an omitted map changes nothing.

display_name
string

The account's public name. Omit to leave it unchanged.

contact_email
string<email>

Where onboarding correspondence for the account is sent. Omit to leave it unchanged.

fields
object

Requirement values, keyed by the field keys the account's requirements name: persons, company.*, business_profile.*, payout_destination, tos_acceptance.*. Omit to change nothing.

balance_currencies
object | null

Which currencies the account holds, keyed by currency code. Holding a currency decides what the account settles in; a one-time checkout can be priced in any supported currency regardless. A recurring checkout is the exception and must be priced in a held currency, so set this before the account sells subscriptions in its own market. A new account holds only USD. Send true to add a currency and false to remove one. Omitthe field and nothing changes. USD is always held and cannot be removed. A currency Bachs cannot settle in is rejected with 400.

Example:

Response

The account, including any requirements the newly requested capability just surfaced and the effect of any fields supplied.

id
string

Unique identifier for the account.

Example:

"acct_7KpQ2mNv4XbR9dLc"

name
string | null

The account's display name.

Example:

"Ada Stores"

owner_user_id
string

The user that owns the account. For an account you own this is a service user Bachs created; you never authenticate as it.

Example:

"usr_7b3e19d24c0a"

parent_organization_id
string | null

The platform this account is connected to, or null when it is a platform in its own right.

Example:

"acct_7KpQ2mNv4XbR9dLc"

country
string | null

Two-letter ISO 3166-1 country code. Decides which requirements the account is given.

Example:

"NG"

entity_type
enum<string> | null

What kind of legal person the account is, which together with country decides the requirements it is given. company: a registered entity, asked for registration and ownership details. individual: a natural person, asked only for their own identity.

Available options:
company,
individual
Example:

"company"

fee_handling
enum<string>

Who absorbs processing fees at checkout. account_pays_fee: deducted from the amount you receive. customer_pays_fee: added to what the customer pays.

Available options:
account_pays_fee,
customer_pays_fee
Example:

"account_pays_fee"

enabled_payment_methods
object | null

One entry per exact corridor (USD_CARD, NGN_CARD, NGN_BANK_TRANSFER, MOMO_GHS to MOMO_ZMW, CRYPTO). See payment method support. Each value has an enabled boolean; CRYPTO additionally carries a currencies map since it covers several asset/network pairs.

adaptive_pricing
boolean

When true, customers are shown prices in their local currency where one is available.

Example:

true

balance_currencies
string[]

Currencies this account is configured to hold a balance in.

Example:
phone_number
string | null

Contact phone number, including country code.

Example:

"+2348012345678"

company_name
string | null

Registered company name, when the account is a company.

Example:

"Ada Stores Limited"

enabled_capabilities
string[] | null

Names of the capabilities currently active on this account. A convenience view of capabilities.

Example:
capabilities
object | null

Each capability's status, keyed by capability name. Populated on single-account reads only; null on list items.

requirements
object | null

Outstanding requirements for this account. Populated on single-account reads only; null on list items.

is_active
boolean

When false, the account is deactivated and cannot authenticate or move funds.

Example:

true

created_at
string

When the account was created, ISO 8601 in UTC.

Example:

"2026-08-01T09:12:44.000Z"

updated_at
string

When the account was last updated, ISO 8601 in UTC.

Example:

"2026-08-07T11:04:22.518Z"

responsibilities
object | null

Fee arrangement for an account you own. null when this object is not an account you own.

configuration
object | null

Personas applied to this account, keyed by name (merchant, recipient), each with an empty object as its value. Populated on single-account reads, where it is {} when none apply; null on list items.

Example: