Idempotência
Repita requisições com segurança — uma cobrança ou um saque nunca são criados duas vezes.
Falhas de rede acontecem: o pedido chega à WeetPay, mas a resposta se perde. A API foi feita para que você possa repetir a mesma requisição sem medo.
Saques (pix-payment)
Envie uma chave única por saque — de preferência o ID do pagamento no seu sistema:
POST /api/v1/gateway/pix-payment
Idempotency-Key: saque-2026-10-30-0001Também é aceito o cabeçalho x-idempotency-key ou, sem cabeçalho, o campo requestNumber do corpo.
| Situação | Resultado |
|---|---|
| primeira vez | saque criado, 200 { id, status: "processing" } |
| mesma chave, mesmo valor e mesma chave PIX | o mesmo saque — 200 com o mesmo id e o cabeçalho Idempotent-Replayed: true. Nada é debitado de novo |
| mesma chave, outro valor ou outra chave PIX | 409 — "Esta chave de idempotência já foi usada em outro saque" |
| sem chave nenhuma | o mesmo valor para a mesma chave PIX em menos de 1 minuto devolve o saque anterior |
A chave vale para sempre na sua conta (não expira) e tem no máximo 100 caracteres.
Gere a chave uma vez por pagamento e guarde-a antes de chamar a API. Gerar uma chave nova a cada tentativa anula a proteção.
Cobranças (request-qrcode)
O requestNumber é único por conta: uma segunda cobrança com o mesmo requestNumber é recusada com 400 requestNumber já utilizado. Se a resposta da criação se perder, recupere a cobrança com Consultar transação informando o requestNumber — o PIX copia e cola volta em pixCopiaECola enquanto ela estiver pendente.
Callbacks
Do lado do seu sistema, os avisos também podem chegar repetidos (reenvio após timeout, por exemplo). Processe cada idTransaction / id uma única vez. Veja Callbacks e webhooks.