Skip to main content
POST
Create a sub-account
The reference is immutable. It is the identifier you send in the X-Sub-Account header to operate on the sub-account, and the value that arrives in the subAccount field of webhooks — choose it carefully, because it cannot be changed after creation.Format: ^[a-z0-9][a-z0-9_-]{1,31}$ — 2 to 32 characters, only lowercase letters, digits, - and _, starting with a lowercase letter or a digit. The reference must be unique within the account: reusing an existing one returns 409 SUB_ACCOUNT_REFERENCE_TAKEN.The sub-account starts with its own balance, at zero and fully independent from the main account balance. See Sub-accounts for the behavior of the X-Sub-Account header and the full error table.

Authorizations

Authorization
string
header
required

Access token obtained from POST /auth (client_id + client_secret). Valid for 300 seconds.

Body

application/json
reference
string
required

Sub-account identifier defined by you. Unique within the account and immutable after creation. principal is a reserved word for the main account and cannot be used: it returns 400 SUB_ACCOUNT_INVALID_REFERENCE.

Pattern: ^[a-z0-9][a-z0-9_-]{1,31}$
Example:

"loja-centro"

name
string
required

Sub-account display name

Maximum string length: 255
Example:

"Loja Centro"

Response

Sub-account created successfully

id
string<uuid>
required

Sub-account ID

reference
string
required

Sub-account reference

Example:

"loja-centro"

name
string
required

Sub-account name

Example:

"Loja Centro"

status
string
required

Sub-account status

Example:

"approved"

createdAt
string<date-time>
required

Creation date