Subcuentas

Una subcuenta es una cuenta con saldo propio bajo la suya: una sucursal, una unidad de negocio, un comercio de su marketplace. Un cobro con ex.subconta acredita en ella; ?subconta= en las consultas filtra lo que es de ella.

Algunas cuentas no tienen subcuentas. Lea capacidades.subcontas en GET /v2/ex/config: cuando es false, crear una subcuenta responde 503 capacidade_indisponivel, y las consultas siguen respondiendo.

Crear #

PUT /v2/ex/subcontas/{id}

Alcance: 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	Obligatorio	Descripción
`nome`	string	sí	Nombre de la subcuenta.
`cnpj`	string	sí	CNPJ del titular de la subcuenta: 14 posiciones, sin puntuación, con los dígitos verificadores. Las 12 primeras pueden ser dígitos o letras, y la letra minúscula se lee en mayúscula; las 2 últimas son dígitos. Fuera de eso, `400 cnpj_invalido`.

Campo del response	Tipo	Descripción
`status`	string	Se crea como `EM_ANALISE`. Del análisis pasa a `ATIVA` o a `RECUSADA`, a veces pasando por `EM_DILIGENCIA`. De `ATIVA` puede pasar a `SUSPENSA`, `BLOQUEADA` o `ENCERRADA`, y de las dos primeras volver a `ATIVA`. `RECUSADA` y `ENCERRADA` son finales. Quien lo cambia es la institución.
`custodiante`	string	El nombre de la institución por donde pasan sus operaciones nuevas (el cobro, el retiro), el mismo de `custodia.custodiante` en `GET /v2/ex/config?subconta={id}`. Para leer, no para programar con él. Solo lectura: quien lo cambia es AmunPay, y lo que ya existe sigue por la institución en que nació.
`herda`	boolean	`true` cuando opera por la misma institución de la cuenta principal y acompaña cada cambio de ella; `false` cuando tiene una propia. Solo lectura.
`aceitaSplit`	boolean	Si un cobro de esta subcuenta puede llevar `ex.splitConfig`. No se deduce de `custodiante`. Con `false`, responde `422 split_de_outro_custodiante`. Ausente cuando no se determinó. Solo lectura.

Cada cambio de estado emite subconta.atualizada. Los cobros y retiros nuevos exigen la subcuenta ATIVA y responden 403 subconta_indisponivel fuera de ese estado. El retiro ya en procesamiento se liquida. El cobro ya emitido, si se paga con la subcuenta fuera de ATIVA, no acredita: el Pix se rechaza o se devuelve al pagador, con el evento cob.pagamento_rejeitado (motivo SUBCONTA_INDISPONIVEL).

Listar y consultar #

GET /v2/ex/subcontas

Alcance: 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 la lista por la situación. GET /v2/ex/subcontas/{id} devuelve una subcuenta.

Consultas por subcuenta #

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 y GET /v2/ex/resumo aceptan ?subconta=. Las capacidades de una subcuenta pueden ser diferentes de las de la cuenta principal: antes de cobrar, retirar o devolver por ella, lea GET /v2/ex/config con ?subconta=.

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

Inquilinos #

Cuando capacidades.baas es verdadero en GET /v2/ex/config, una subcuenta puede tener credencial propia y operar sola, sobre su propia cuenta, con alcances que son un subconjunto de los suyos. POST /v2/ex/inquilinos emite la credencial, GET /v2/ex/inquilinos lista y DELETE /v2/ex/inquilinos/{sub} revoca. Alcance: ex.inquilinos.write y ex.inquilinos.read. La credencial del inquilino se crea sin IP y solo solicita token después de que AmunPay registra sus IP de salida. Antes de eso, el token y cada llamada responden 403 origem_nao_permitida.

Errores #

Estado	`title`	Cuándo
400	`id_invalido`	`id` fuera de 26 a 35 caracteres alfanuméricos.
400	`nome_obrigatorio`	`nome` vacío.
400	`cnpj_invalido`	`cnpj` fuera de las 14 posiciones, con puntuación o con los dígitos verificadores incorrectos.
400	`status_invalido`	Filtro `status` fuera de la lista.
409	`id_duplicado`	El mismo `id` ya existe con otro cuerpo.
403	`subconta_indisponivel`	Operación en una subcuenta que no está `ATIVA`.
403	`subconta_de_outro`	La credencial es de una subcuenta y solicitó otra.
404	`nao_encontrado`	La subcuenta no existe en esta cuenta.
503	`capacidade_indisponivel`	`capacidades.subcontas` es `false`: la cuenta no tiene subcuentas.