Sub-accounts

A sub-account is an account with its own balance under yours: a branch, a business unit, a seller in your marketplace. A charge with ex.subconta credits it; ?subconta= in lookups narrows the result down to what belongs to it.

Some accounts do not have sub-accounts. Read capacidades.subcontas in GET /v2/ex/config: when it is false, creating a sub-account responds 503 capacidade_indisponivel, and the lookups keep responding.

Create #

PUT /v2/ex/subcontas/{id}

Scope: ex.subcontas.write.

PUT /v2/ex/subcontas/SUB01J1ZK7M9QW3ERT5TY6UI8O
{
  "nome": "Filial Centro",
  "cnpj": "11222333000181"
}
→ 201
{
  "id": "SUB01J1ZK7M9QW3ERT5TY6UI8O",
  "nome": "Filial Centro",
  "cnpj": "11222333000181",
  "status": "EM_ANALISE",
  "custodiante": "Conta PI",
  "herda": true,
  "aceitaSplit": true,
  "criadoEm": "2026-09-18T12:00:00Z",
  "atualizadoEm": "2026-09-18T12:00:00Z"
}

Field	Type	Required	Description
`nome`	string	yes	Name of the sub-account.
`cnpj`	string	yes	CNPJ of the holder of the sub-account: 14 positions, without punctuation, with the check digits. The first 12 may be digits or letters, and a lowercase letter is read as uppercase; the last 2 are digits. Otherwise, `400 cnpj_invalido`.

Response field	Type	Description
`status`	string	Starts as `EM_ANALISE`. From the analysis it goes to `ATIVA` or to `RECUSADA`, sometimes passing through `EM_DILIGENCIA`. From `ATIVA` it may go to `SUSPENSA`, `BLOQUEADA` or `ENCERRADA`, and from the first two it may return to `ATIVA`. `RECUSADA` and `ENCERRADA` are final. The institution makes the changes.
`custodiante`	string	The name of the institution through which its new operations go (the charge, the withdrawal), the same as `custodia.custodiante` in `GET /v2/ex/config?subconta={id}`. For reading, not for programming against. Read only: AmunPay makes the change, and what already exists goes on through the institution where it was created.
`herda`	boolean	`true` when it operates through the same institution as the main account and follows each change of it; `false` when it has its own. Read only.
`aceitaSplit`	boolean	Whether a charge of this sub-account can carry `ex.splitConfig`. It is not deduced from `custodiante`. With `false`, such a charge responds `422 split_de_outro_custodiante`. Absent when it was not determined. Read only.

Each status change emits subconta.atualizada. New charges and payouts require the sub-account to be ATIVA and respond 403 subconta_indisponivel otherwise. A payout already in processing settles. A charge already issued, if paid while the sub-account is not ATIVA, does not credit: the Pix is rejected or returned to the payer, with the event cob.pagamento_rejeitado (reason SUBCONTA_INDISPONIVEL).

List and get #

GET /v2/ex/subcontas

Scope: ex.subcontas.read.

GET /v2/ex/subcontas
→ 200
{
  "subcontas": [
    {
      "id": "SUB01J1ZK7M9QW3ERT5TY6UI8O",
      "nome": "Filial Centro",
      "cnpj": "11222333000181",
      "status": "EM_ANALISE",
      "custodiante": "Conta PI",
      "herda": true
    }
  ]
}

?status= filters the list by status. GET /v2/ex/subcontas/{id} returns a sub-account.

Lookups by sub-account #

GET /v2/ex/config, GET /v2/ex/saldo, GET /v2/ex/cobrancas, GET /v2/ex/pix, GET /v2/ex/extrato/{data}, GET /v2/ex/extrato/{data}/arquivo, GET /v2/ex/transacoes, GET /v2/ex/transacoes/mapear and GET /v2/ex/resumo accept ?subconta=. The capabilities of a sub-account may differ from those of the main account: before charging, paying out or refunding through it, read GET /v2/ex/config with ?subconta=.

GET /v2/ex/saldo?subconta=SUB01J1ZK7M9QW3ERT5TY6UI8O
→ 200
{
  "subconta": "SUB01J1ZK7M9QW3ERT5TY6UI8O",
  "disponivel": "0.00",
  "total": "0.00"
}

Tenants #

When capacidades.baas is true in GET /v2/ex/config, a sub-account may have its own credential and operate by itself, on its own account, with scopes that are a subset of yours. POST /v2/ex/inquilinos issues the credential, GET /v2/ex/inquilinos lists and DELETE /v2/ex/inquilinos/{sub} revokes. Scope: ex.inquilinos.write and ex.inquilinos.read. The credential of the tenant is created without an IP and only requests a token after AmunPay registers its outbound IPs. Before that, the token request and every call respond 403 origem_nao_permitida.

Errors #

Status	`title`	When
400	`id_invalido`	`id` outside 26 to 35 alphanumeric characters.
400	`nome_obrigatorio`	Empty `nome`.
400	`cnpj_invalido`	`cnpj` not 14 positions, with punctuation or with wrong check digits.
400	`status_invalido`	`status` filter outside the list.
409	`id_duplicado`	The same `id` already exists with a different body.
403	`subconta_indisponivel`	Operation on a sub-account that is not `ATIVA`.
403	`subconta_de_outro`	The credential belongs to a sub-account and asked for another one.
404	`nao_encontrado`	The sub-account does not exist in this account.
503	`capacidade_indisponivel`	`capacidades.subcontas` is `false`: the account does not have sub-accounts.