Saldo e Saques

Consultando o saldo

GET /account-balance retorna o saldo disponível pra saque, o saldo retido em reserva financeira (se sua instância usar essa configuração) e a lista de holds pendentes:

{
  "status": 200,
  "message": "Saldo consultado com sucesso",
  "data": {
    "balance": 250000,
    "currency": "BRL",
    "reservedBalance": 12000,
    "reserveHolds": [
      {
        "chargeId": "chg_abc123",
        "amountCents": 12000,
        "releaseAt": "2026-08-14T00:00:00.000Z",
        "status": "HELD"
      }
    ]
  }
}

balance e reservedBalance estão em centavos. Um valor em reserveHolds some da lista automaticamente quando liberado — o saldo correspondente passa a contar em balance.

Sobre reserva financeira

Retenção de reserva é uma configuração por instância/empresa (não é um valor fixo da plataforma) — algumas contas não têm retenção nenhuma, e todo o valor pago fica disponível pra saque imediatamente após a confirmação do pagamento. Não existe webhook de "valor liberado" hoje — consulte este endpoint periodicamente se seu fluxo depende de saber quando um hold libera.

Fazendo um saque

O fluxo tem 3 passos: iniciar, confirmar com OTP, e (opcional) reenviar ou cancelar.

1. Iniciar

curl -X POST "https://api.xpaybrasil.com/v1/account-balance/withdraw" \-H "X-API-KEY: cpk_live_sua_chave_aqui" \-H "Content-Type: application/json" \-d '{ "value": 10000 }'

value em centavos. O mínimo (padrão R$ 1,01) e a taxa de saque são configuráveis por instância — some os dois pra saber o piso real da sua conta; consulte GET /account-balance/withdraw-fee pra simular o valor líquido antes de sacar. Retorna um withdrawId e envia um código OTP de 6 dígitos por email pro responsável da conta.

Um saque por vez

Só existe um saque em aberto por empresa. Iniciar um novo enquanto outro está pendente retorna 409 com o withdrawId do saque já em andamento — confirme, cancele ou reenvie o OTP dele antes de tentar de novo.

2. Confirmar

curl -X POST "https://api.xpaybrasil.com/v1/account-balance/withdraw/confirm" \-H "X-API-KEY: cpk_live_sua_chave_aqui" \-H "Content-Type: application/json" \-d '{ "withdrawId": "withdraw_abc123", "otpCode": "123456" }'

O código expira em poucos minutos e aceita no máximo 5 tentativas erradas — depois disso o saque fica bloqueado pra /confirm até você chamar /resend-otp. Se a instância exigir aprovação manual de saques, a resposta vem com status: "PENDING_REVIEW" em vez de "APPROVED" — o saque fica parado até um super admin aprovar; senão, segue direto pro processamento.

A confirmação é assíncrona: a resposta desse endpoint reflete o saque entrando em processamento, não a liquidação final. O evento withdraw.completed (veja Webhooks) dispara quando o pagamento é confirmado.

Reenviar ou cancelar

# reenviar OTP: só funciona depois que o código atual expirar, mesmo se você já
# estourou as 5 tentativas — é a mesma proteção contra força bruta, não um bug
# (reseta o contador de tentativas quando finalmente é chamado)
curl -X POST ".../account-balance/withdraw/resend-otp" -d '{ "withdrawId": "withdraw_abc123" }'

# cancelar (só funciona se ainda não foi confirmado)
curl -X POST ".../account-balance/withdraw/cancel" -d '{ "withdrawId": "withdraw_abc123" }'

Histórico

GET /account-balance/withdrawals lista os saques da conta, com status (CREATED, PENDING_REVIEW, APPROVED, CONFIRMED, FAILED, CANCELLED), valor, chave PIX usada e o endToEndId da transação quando disponível.

Saque automático

Saque automático (transferir o saldo disponível todo dia, sem chamar a API) não é autoatendimento — é configurado por um super admin da instância, por empresa, pelo painel administrativo. Se sua conta tiver saque automático ativo, os saques daí também aparecem em GET /account-balance/withdrawals e disparam o mesmo withdraw.completed.

Veja a Referência da API pra o schema completo de request/response de cada endpoint.