Contas e saques

Saques e favorecidos

O dinheiro sai da conta só para favorecidos da mesma titularidade, validados por uma pessoa e depois de uma quarentena. Cada saque reserva o saldo conciliado e espera a aprovação de outra pessoa no painel.

Quanto pode sair

GET /v1/balance separa o que o provedor informa do que já foi conciliado pelo extrato. Só withdrawableNowCents pode ser pedido agora; pendingCents (confirmado a liberar) e suspenseCents nunca autorizam saque.

GET /v1/balance

{
  "accountId": "acc_01JDY7Q2M3N4P5R6S7T8V9W0XB",
  "environment": "sandbox",
  "providerAvailableCents": "9801",
  "eligibleCents": "9801",
  "withdrawableNowCents": "9801",
  "reservedCents": "0",
  "reconciledCents": "9801",
  "suspenseCents": "0",
  "pendingCents": "0",
  "blockedCents": "0",
  "asOf": "2026-11-13T13:00:00.000Z",
  "stale": false,
  "restrictions": [],
  "openCases": 0,
  "reconciliationStatus": "MATCHED"
}

restrictions explica por que o saque pode estar travado: PROVIDER_SNAPSHOT_STALE, PROVIDER_SNAPSHOT_MISSING, LEDGER_LAGGING (recebimento ainda não refletido no extrato) ou BALANCE_MISMATCH (divergência aberta na conciliação).

1. Cadastrar o favorecido

POST /v1/beneficiaries

{
  "kind": "PIX_KEY",
  "pixKey": "11222333000181",
  "pixKeyType": "CNPJ",
  "holderTaxId": "11222333000181",
  "holderName": "Loja Órbita Sintética LTDA"
}

Chave Pix (PIX_KEY) ou conta bancária (BANK_ACCOUNT), sempre com o CPF/CNPJ do próprio titular da conta (BENEFICIARY_HOLDER_MISMATCH para outro documento).
O destino é cifrado e só volta mascarado. Mudar o destino cria uma versão nova, que precisa de nova validação.
O favorecido nasce PENDING_VALIDATION e usable: false. Uma pessoa da equipe valida no painel, com confirmação reforçada (MFA); a partir daí corre a quarentena de 24 horas (availableFrom).

2. Pedir a transferência

POST /v1/transfers

{
  "beneficiaryVersionId": "bnv_01JDYA61B2C3D4E5F6G7H8J9KF",
  "amountCents": "250000",
  "description": "Repasse semanal"
}

Responde 202 com a transferência em AWAITING_APPROVAL e o valor reservado. Acima do disponível: 422 TRANSFER_EXCEEDS_ELIGIBLE; favorecido em quarentena ou não validado: BENEFICIARY_IN_QUARANTINE / BENEFICIARY_NOT_VALIDATED.
A API pública não aprova transferências. Outra pessoa, diferente de quem pediu, aprova ou recusa no painel do lojista, com MFA. O pedido não aprovado expira (padrão de 72 horas, proposta configurável) e a reserva é liberada sem nada enviar.
Depois da aprovação, a transferência vira uma operação: o saldo é conferido no provedor antes do envio, e a validação de saque do provedor só aprova a intenção exata (mesmo valor e mesmo favorecido).

Situações da transferência
status	Significado
`AWAITING_APPROVAL`	Reservada, aguardando a aprovação de outra pessoa.
`REJECTED`	Recusada no painel; reserva liberada.
`EXPIRED`	Não aprovada no prazo; reserva liberada.
`CANCELLED`	Cancelada por quem pediu ou pelo provedor.
`APPROVED`	Aprovada; aguardando envio.
`SUBMITTED`	Enviada ao provedor.
`UNKNOWN`	Resposta perdida: a reserva continua até haver evidência; nunca é reenviada.
`PENDING`	Aceita pelo provedor.
`BANK_PROCESSING`	Em processamento bancário.
`BLOCKED`	Bloqueada pelo provedor.
`DONE`	Concluída.
`FAILED`	Falhou; o valor volta à conta pelo extrato.

Acompanhe por transfer.updated e GET /v1/transfers/{id} (reservation.reflectedInStatement indica se o débito já apareceu no extrato).

Rotas

Rotas de favorecidos e transferências
Rota	O que faz	Situação
POST /v1/beneficiaries	Cadastrar favorecido (mesma titularidade; validação por pessoa com step-up e quarentena)	Implementada
GET /v1/beneficiaries	Listar favorecidos (destino mascarado)	Implementada
POST /v1/transfers	Solicitar transferência (reserva saldo e aguarda aprovação no painel)	Implementada
GET /v1/transfers	Listar transferências	Implementada
GET /v1/transfers/{id}	Consultar transferência	Implementada
GET /v1/beneficiaries/{id}	Consultar favorecido	Implementada

Rotas de saldo e conciliação
Rota	O que faz	Situação
GET /v1/balance	Saldos observados, conciliados e elegíveis	Implementada
GET /v1/statement	Extrato conciliado	Implementada
GET /v1/reconciliation/cases	Casos de conciliação da conta	Implementada

Próximo: Integrações de referência