Saldos e Saques

Saldo

Saldos são sempre em centavos e divididos em duas partes:

Campo	Significado
`balanceAvailable`	Pronto para sacar
`balanceBlocked`	Retido (análise, garantia, disputa/infração)
`total`	Soma dos dois

curl https://api.betpaympix.com/v1/user/balance \
  -H "Authorization: Bearer $API_TOKEN"
# { "balanceAvailable": 50000, "balanceBlocked": 0, "total": 50000 }

O saldo de merchants é consultado à parte, em GET /v1/merchants/{id}/wallet (ver Merchants).

Saque do usuário (Pix)

curl -X POST https://api.betpaympix.com/v1/withdraw \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": 10000,
    "pixKey": "12345678909",
    "pixType": "CPF",
    "description": "Saque",
    "callbackUrl": "https://sualoja.com/webhooks/payerpix"
  }'

Sempre envie Idempotency-Key em saques. É a proteção contra duplicidade em retries de rede e cliques duplos.

Tipos de chave Pix (`pixType`)

Valor	Chave
`CPF`	CPF do recebedor
`CNPJ`	CNPJ do recebedor
`EMAIL`	E-mail cadastrado no Pix
`PHONE`	Telefone cadastrado no Pix
`EVP`	Chave aleatória

Ciclo de vida do saque

PENDING ──> ANALYSIS ──> COMPLETED
   │            │
   │            └──> CANCELED   (reprovado/expirado na auditoria)
   └────────────────> FAILED    (falha na liquidação)

Status	Significado
`PENDING`	Recebido, aguardando processamento
`ANALYSIS`	Em auditoria antifraude/limites
`COMPLETED`	Pago ao recebedor
`FAILED`	Falha na liquidação do Pix
`CANCELED`	Cancelado (incl. expiração em auditoria)

Saques em ANALYSIS que expiram são cancelados automaticamente por uma rotina periódica, devolvendo o valor ao saldo disponível.

Limites

Limites de mínimo/máximo por saque são aplicados por conta. Estouro retorna:

WITHDRAW_BELOW_MINIMUM — abaixo do mínimo
WITHDRAW_ABOVE_MAXIMUM — acima do máximo
WITHDRAW_INSUFFICIENT_FUNDS — saldo insuficiente

Ver catálogo completo em Erros.

Acompanhamento

Webhook: enviado para a callbackUrl quando o status muda (fonte de verdade).
Consulta: o estado também pode ser reconciliado via API.

Detalhes do payload em Webhooks.

Cobranças Pix

Splits