Sub-contas

Uma sub-conta é uma conta com saldo próprio sob a sua: uma filial, uma unidade de negócio, um lojista do seu marketplace. Uma cobrança com ex.subconta credita nela; ?subconta= nas consultas recorta o que é dela.

Algumas contas não têm sub-contas. Leia capacidades.subcontas em GET /v2/ex/config: quando é false, criar uma sub-conta responde 503 capacidade_indisponivel, e as consultas continuam respondendo.

Criar #

PUT /v2/ex/subcontas/{id}

Escopo: 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"
}

Campo	Tipo	Obrigatório	Descrição
`nome`	string	sim	Nome da sub-conta.
`cnpj`	string	sim	CNPJ do titular da sub-conta: 14 posições, sem pontuação, com os dígitos verificadores. As 12 primeiras podem ser dígitos ou letras, e a letra minúscula é lida em maiúscula; as 2 últimas são dígitos. Fora disso, `400 cnpj_invalido`.

Campo do response	Tipo	Descrição
`status`	string	Nasce `EM_ANALISE`. Da análise vai a `ATIVA` ou a `RECUSADA`, às vezes passando por `EM_DILIGENCIA`. De `ATIVA` pode ir a `SUSPENSA`, `BLOQUEADA` ou `ENCERRADA`, e das duas primeiras voltar a `ATIVA`. `RECUSADA` e `ENCERRADA` são finais. Quem muda é a instituição.
`custodiante`	string	O nome da instituição por onde as operações novas dela passam (a cobrança, o saque), o mesmo de `custodia.custodiante` em `GET /v2/ex/config?subconta={id}`. Para ler, não para programar contra. Somente leitura: quem troca é a AmunPay, e o que já existe segue pela instituição em que nasceu.
`herda`	boolean	`true` quando ela opera pela mesma instituição da conta principal e acompanha cada troca dela; `false` quando tem uma própria. Somente leitura.
`aceitaSplit`	boolean	Se uma cobrança desta sub-conta pode levar `ex.splitConfig`. Não se deduz de `custodiante`. Com `false`, ela responde `422 split_de_outro_custodiante`. Ausente quando não foi apurado. Somente leitura.

Cada mudança de status emite subconta.atualizada. Cobrança e saque novos exigem a sub-conta ATIVA e respondem 403 subconta_indisponivel fora dela. O saque já em processamento liquida. A cobrança já emitida, se for paga com a sub-conta fora de ATIVA, não credita: o Pix é recusado ou devolvido ao pagador, com o evento cob.pagamento_rejeitado (motivo SUBCONTA_INDISPONIVEL).

Listar e consultar #

GET /v2/ex/subcontas

Escopo: 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= filtra a lista pela situação. GET /v2/ex/subcontas/{id} devolve uma sub-conta.

Consultas por sub-conta #

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 e GET /v2/ex/resumo aceitam ?subconta=. As capacidades de uma sub-conta podem ser diferentes das da conta principal: antes de cobrar, sacar ou devolver por ela, leia GET /v2/ex/config com ?subconta=.

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

Inquilinos #

Quando capacidades.baas é verdadeiro em GET /v2/ex/config, uma sub-conta pode ter credencial própria e operar sozinha, sobre a própria conta, com escopos que são um subconjunto dos seus. POST /v2/ex/inquilinos emite a credencial, GET /v2/ex/inquilinos lista e DELETE /v2/ex/inquilinos/{sub} revoga. Escopo: ex.inquilinos.write e ex.inquilinos.read. A credencial do inquilino nasce sem IP e só pede token depois que a AmunPay cadastra os IPs de saída dele. Antes disso, o token e cada chamada respondem 403 origem_nao_permitida.

Erros #

Status	`title`	Quando
400	`id_invalido`	`id` fora de 26 a 35 caracteres alfanuméricos.
400	`nome_obrigatorio`	`nome` vazio.
400	`cnpj_invalido`	`cnpj` fora das 14 posições, com pontuação ou com os dígitos verificadores errados.
400	`status_invalido`	Filtro `status` fora da lista.
409	`id_duplicado`	O mesmo `id` já existe com outro corpo.
403	`subconta_indisponivel`	Operação numa sub-conta que não está `ATIVA`.
403	`subconta_de_outro`	A credencial é de uma sub-conta e pediu outra.
404	`nao_encontrado`	A sub-conta não existe nesta conta.
503	`capacidade_indisponivel`	`capacidades.subcontas` é `false`: a conta não tem sub-contas.