Idempotency
Retry requests safely — a charge or payout is never created twice.
Network failures happen: the request reaches WeetPay but the response is lost. The API is designed so you can repeat the same request without fear.
Payouts (pix-payment)
Send a unique key per payout — ideally the payment ID in your system:
POST /api/v1/gateway/pix-payment
Idempotency-Key: payout-2026-10-30-0001The x-idempotency-key header is also accepted or, without a header, the requestNumber body field.
| Situation | Result |
|---|---|
| first time | payout created, 200 { id, status: "processing" } |
| same key, same amount and PIX key | the same payout — 200 with the same id and the Idempotent-Replayed: true header. Nothing is debited again |
| same key, different amount or PIX key | 409 — "Esta chave de idempotência já foi usada em outro saque" |
| no key at all | the same amount to the same PIX key within 1 minute returns the previous payout |
The key is valid forever on your account (it does not expire) and has at most 100 characters.
Generate the key once per payment and store it before calling the API. Generating a new key on every retry defeats the protection.
Charges (request-qrcode)
requestNumber is unique per account: a second charge with the same requestNumber is rejected with 400 requestNumber já utilizado. If the creation response is lost, recover the charge with Get transaction using the requestNumber — the PIX code comes back in pixCopiaECola while it is pending.
Callbacks
On your side, notices may also arrive more than once (a retry after a timeout, for example). Process each idTransaction / id only once. See Callbacks and webhooks.