Skip to main content
In this guide you’ll create an account, decide whether it only receives money or also accepts payments, and read back the requirements that choice produced. By the end you’ll have an account ready to onboard. Most marketplaces only need an account that receives money: it gets paid out, moves transfers, converts currency. That account’s requirements are short. An account that also accepts payments in its own name needs a merchant capability, and its requirements grow accordingly. Decide which one you’re building before you call this endpoint, because it is the single biggest lever you have over whether the account finishes onboarding at all.

​
Before you start

  • A sandbox API key (sk_sandbox_...) with the connected_accounts:write scope. See Authentication.
  • The connect capability active on your account. See Become a platform.

​
Steps

1

Create the account

contact_email is the only required field. Send country when the account is not in yours, because country decides which requirements it is given.
This account can receive money (hold a transfer share and withdraw it), but it cannot accept a payment directly from a customer, since no merchant capability was requested and merchant was never named in configuration. configuration names only recipient here, and that is the only reason transfers and payouts, both recipient capabilities, were requestable at all. Nothing is applied that was not named, so always name at least one persona and request at least one capability under it; do not create an account without both. This is the shape most marketplaces want.
Name every persona the account needs as a key in configuration, and nest each capability under that persona’s own capabilities: {"merchant": {"capabilities": {"card_collection": {"requested": true}}}}, never a bare {"card_collection": {...}} at the top level. A capability is only ever named inside the persona object it belongs to, so there is no way to name one without also naming its persona in the same request. Nesting it under the wrong persona’s capabilities fails with 400 capability_configuration_mismatch: it is never silently corrected. Naming a persona with capabilities left out entirely requests every capability that persona allows, live or sandbox, which is rarely what you want. Send "capabilities": {} under it when you deliberately want to apply the persona and request nothing yet.
This request runs in sandbox, where a capability whose persona is applied is granted active immediately instead of landing restricted for review, which is why the response above already shows active. This still respects personas: naming merchant in configuration and nesting a merchant capability under its capabilities here would grant it active the same way. In live mode the same request lands every requested capability restricted until a reviewer enables it. See Testing.
responsibilities.fees.collector is fixed at creation and cannot change afterward: bachs (shown above, and the default) takes the processing fee out of the account’s own charges; platform has you absorb it instead. It only affects the account’s own charges, not one it receives as the destination of yours. See Accounts.
2

Check what it owes

The response’s requirements block lists the field keys the account has to provide. Read it again at any time:
A recipient-only account like this one asks for less: no business profile, no payment-method fields, only the identity needed to move money to it. An account that also holds a merchant capability has a longer list, because accepting payments carries its own set of requirements. See Requirements for the field states and how they change.
3

Request more capabilities later

Requesting a capability after creation uses the same configuration shape as creation: naming a persona as a key, with or without a capability nested under its capabilities, is what applies that persona if the account does not already have it. Another recipient capability works, since this account already has recipient:
"requested": false returns 400 with capability_unrequest_unsupported. There is no way to unrequest a capability through the API.
So does a first merchant capability: this is how a recipient-only account becomes a merchant later, not only at creation:
Naming merchant as a key here applies it to this account, since it did not have it, then requests the card_collection nested under its capabilities, alone. recipient is untouched. Unlike creation, an omitted capabilities on update never blanket-requests: naming merchant with capabilities left out here would only apply the persona and request nothing. A capability named under the wrong persona, such as card_collection under recipient’s capabilities, fails with 400 capability_configuration_mismatch instead: the shape only applies the persona you actually named, never a different one inferred from the capability.
In sandbox, a capability requested this way is granted active immediately, the same as at creation, scoped to only what you named: card_collection here, not the rest of what merchant allows. In live it lands restricted for review, same as everywhere else. See Testing.

​
With this shape

  • A recipient-only account, configuration: {"recipient": {}}, can be paid out, send and receive transfers, and convert currency, and nothing more. Its requirements are the short list this guide showed.
  • Naming merchant as a key in configuration, with a merchant capability nested under its capabilities, at creation or later, adds that capability’s requirements to the account. It does not remove recipient if the account has it; an account keeps every persona it has ever been given.
  • responsibilities.fees.collector is fixed the moment the account exists. Decide it here; there is no endpoint to change it afterward.

​
Errors

Account creation returns the standard error envelope. A field this endpoint does not read is not rejected: the request still returns 201, and the field silently takes its default. See Accounts.

​
Next steps