Contas e saldo

Listar contas, consultar saldo e extrato, definir limites e gerenciar o ciclo de vida da conta. Toda conta acessada precisa pertencer ao parceiro do token.

Tipos de conta

Ao abrir uma conta (em Cadastrar cliente ou em Abrir conta adicional), o campo account_type aceita:

account_type	Descrição
payment (padrão)	Conta de pagamento
checking	Conta corrente
savings	Conta poupança
salary	Conta salário
client	Conta de cliente
client_external	Conta de cliente externo
escrow	Conta escrow (garantia)

O valor é tratado sem diferenciar maiúsculas de minúsculas. Um valor fora desta lista responde 422 com invalid account_type.

Unidades

Saldo, extrato e limites são devolvidos em centavos (número inteiro). R$ 15,00 é 1500.

Listar contas

GET /api/partner/v1/accounts?page=1&page_size=50
Authorization: Bearer {{access_token}}

• Escopo: account:read · Filtro opcional document (CPF/CNPJ do titular, com ou sem máscara).

{
  "data": [
    { "id": 10024270, "user_id": 25154, "kind": 3, "account_type": "payment", "agency": "0001", "account_number": "119306-6", "status": "active" }
  ],
  "meta": { "page": 1, "page_size": 50, "total": 1 }
}

Detalhar conta

GET /api/partner/v1/accounts/{id}
Authorization: Bearer {{access_token}}

• Escopo: account:read

{ "data": { "id": 10024270, "user_id": 25154, "kind": 3, "account_type": "payment", "agency": "0001", "account_number": "119306-6", "status": "active", "currency": "BRL", "created_at": "...", "updated_at": "..." } }

Consultar saldo

GET /api/partner/v1/accounts/{id}/balance
Authorization: Bearer {{access_token}}

• Escopo: account:read

{ "data": { "account_id": 10024270, "balance": 99997, "available": 99997, "blocked": 0, "currency": "BRL", "updated_at": "2026-07-11T02:21:28Z" } }

Consultar extrato

GET /api/partner/v1/accounts/{id}/statement?date_from=2026-07-01&date_to=2026-07-10&page=1&page_size=50
Authorization: Bearer {{access_token}}

• Escopo: statement:read · Filtros opcionais date_from, date_to.

{
  "data": [
    {
      "id": "PIXOUT20260710abc123",
      "direction": "debit",
      "type": "pix",
      "amount": 5000,
      "description": "PIX enviado",
      "status": "settled",
      "end_to_end_id": "E9999900820260710...",
      "created_at": "2026-07-10T10:12:00Z",
      "completed_at": "2026-07-10T10:12:01Z"
    }
  ],
  "meta": { "account_id": 10024270, "page": 1, "page_size": 50, "total": 1 }
}

Lançamentos de tarifa

A tarifa é sempre um lançamento separado da transação principal. Os lançamentos com type: "fee" carregam dois campos de correlação: feeTransactionId, o identificador da cobrança de tarifa, e originTransactionId, a transação que originou a cobrança.

{
  "direction": "debit",
  "type": "fee",
  "amount": 350,
  "status": "settled",
  "feeTransactionId": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c",
  "originTransactionId": "E9999900820260714210000aabbccdd0"
}

Os demais campos são os mesmos dos outros lançamentos. O detalhe das tarifas está em Tarifas.

Comprovante de um lançamento

GET /api/partner/v1/accounts/{id}/statement/{entry_id}/receipt
Authorization: Bearer {{access_token}}

• Escopo: statement:read · Um entry_id inexistente responde 404.

Limites

Cada conta tem limites para PIX de saída e TED nas janelas transacional, diária, mensal e noturna. O limite noturno atende à Resolução BCB 142.

Consultar limites

GET /api/partner/v1/accounts/{id}/limits
Authorization: Bearer {{access_token}}

• Escopo: account:read

{
  "data": {
    "account_id": 10024270,
    "currency": "BRL",
    "pix_out": { "transaction_limit": 1500000, "daily_limit": 10000000000, "monthly_limit": 10000000000, "nighttime_limit": 100000 },
    "ted": { "transaction_limit": 1500000, "daily_limit": 10000000000, "monthly_limit": 10000000000, "nighttime_limit": 100000 },
    "overrides": { "pix_out_transaction_limit": null, "pix_out_daily_limit": null, "pix_out_monthly_limit": null, "nighttime_limit": null }
  }
}

pix_out e ted são os limites efetivos da conta. overrides mostra os valores definidos especificamente nesta conta; null significa herdado do padrão.

Alterar limites

PUT /api/partner/v1/accounts/{id}/limits
Authorization: Bearer {{access_token}}
Content-Type: application/json

{ "pix_out_transaction_limit": 500000, "nighttime_limit": 100000 }

• Escopo: account:write
• Campos aceitos (em centavos): pix_out_transaction_limit, pix_out_daily_limit, pix_out_monthly_limit, nighttime_limit. Só os campos presentes são alterados; enviar null remove o override e a conta volta a herdar o padrão. A resposta traz os limites efetivos e os overrides atualizados.

Bloqueio e encerramento

O bloqueio impede a conta de originar saída de dinheiro (PIX, TED e transferência interna). Uma conta bloqueada continua podendo receber.

POST /api/partner/v1/accounts/{id}/block      # bloquear
POST /api/partner/v1/accounts/{id}/unblock    # desbloquear
POST /api/partner/v1/accounts/{id}/close       # encerrar
Authorization: Bearer {{access_token}}

• Escopo: account:write

Enquanto bloqueada, todo envio a partir da conta responde 422 com code: "account_blocked". O encerramento exige saldo zero; uma conta com saldo responde 422:

{ "error": { "status": 422, "message": "conta com saldo diferente de zero não pode ser encerrada", "balance": 99994, "currency": "BRL" } }

Com saldo zero, o encerramento responde 200 com status: "closed" e closing_date.

Trilha de eventos da conta

GET /api/partner/v1/accounts/{id}/events?limit=50
Authorization: Bearer {{access_token}}

• Escopo: account:read · Filtros opcionais from e to (ISO8601) e limit (padrão 50, máximo 100).

Devolve a trilha de auditoria da conta (criação, bloqueio, alteração de limites e demais mudanças administrativas), mais recente primeiro:

{
  "data": {
    "events": [
      { "id": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c", "action": "update", "resourceType": "account", "actorType": "admin", "changes": { "status": "blocked" }, "metadata": {}, "occurredAt": "2026-07-14T21:00:00Z" }
    ],
    "source": "audit_trail"
  }
}

Não é o catálogo de notificações: os eventos de webhook ficam em GET /webhooks/events e em Webhooks.

Eventos de conta

Os eventos de webhook account.created, account.blocked, account.unblocked e account.closed notificam a criação da conta e as mudanças de estado. Os payloads estão em Webhooks.