Skip to main content

​
Criar saque

POST /v1/payouts
  • O saldo na moeda do saque é debitado atomicamente na criação (valor + taxa). Sem saldo → 422 INSUFFICIENT_FUNDS.
  • kind: PLAYER_PAYOUT (saque de player) ou SETTLEMENT (saque do seu próprio saldo).
  • Idempotência por external_id.
  • currency / payment_method — a moeda e o trilho. Sem eles, o saque é BRL / PIX, exatamente como sempre foi.

​
Saque em pesos mexicanos (SPEI)

  • destination.clabe — a conta CLABE de destino, 18 dígitos. Validada antes de qualquer coisa: o último dígito é verificador, e o banco se deriva dos três primeiros — você não informa banco, ele vem da conta. CLABE inválida → 422 INVALID_DESTINATION, sem saque criado e sem saldo tocado.
  • recipient.document — o RFC (12 ou 13 caracteres) ou o CURP (18) do beneficiário. Documento fora desses formatos → 422 INVALID_DESTINATION.
  • pix_key e pix_key_type não se aplicam ao SPEI — o destino é a CLABE.
  • O payout devolvido traz currency, payment_method e destination { type: "spei", clabe, bank_code, bank_name } com o banco resolvido pelo catálogo do Banxico.
Saque é irreversível. A CLABE certa numa conta que não é a do seu cliente paga a pessoa errada, e não há estorno pelo trilho. A validação barra erro de digitação; a titularidade da conta é responsabilidade de quem informa.

​
Dados do recebedor

Envie email e phone sempre que tiver. Os adquirentes exigem identificação real de quem recebe: transação sem esses dados entra no radar de risco deles, e conta com dado genérico repetido é motivo de bloqueio. Você já envia essas informações no depósito — mande as mesmas aqui.
São opcionais: quem não enviar continua funcionando exatamente como hoje. E email malformado é simplesmente ignorado — nunca vamos recusar o saque do seu cliente por causa de um campo cadastral. Se a sua conta estiver com auto-aprovação ligada (padrão), o saque vai direto ao provedor e fica PROCESSING até liquidar. Senão, fica PENDING aguardando aprovação do operador.

​
Estados

PENDING → PROCESSING → PAID · ou → FAILED/REJECTED (o valor é estornado ao saldo).
Um 504 PROVIDER_TIMEOUT na criação não estorna automaticamente — o pagamento pode ter saído. O saque fica PROCESSING e é resolvido pelo webhook do provedor. Nunca refaça um saque por timeout sem antes consultar o status.

​
Consultar