Webhooks

Ao criar uma cobrança ou saque, informe uma callbackUrl. Quando o status mudar (ex.: pagamento confirmado), a PayerPix faz um POST para essa URL.

Payload

{
  "eventType": "payment.completed",
  "payload": {
    "id": "0e9c...uuid",
    "externalId": "TX-9931",
    "status": "COMPLETED",
    "amount": 1990,
    "paidAt": "2026-06-03T12:03:11Z",
    "payerName": "Maria Souza",
    "payerDocument": "***.456.789-**",
    "endToEndId": "E1234567890..."
  },
  "deliveryAttempt": 1,
  "timestamp": "2026-06-03T12:03:12Z"
}

Boas práticas

1. Responda 2xx rapidamente e processe de forma assíncrona.
2. Trate idempotência pelo payload.id (pode haver reentrega).
3. Confirme o estado consultando GET /v1/pix?id=... antes de liberar o produto/serviço.
4. Proteja a callbackUrl com um segredo/rota não‑adivinhável.

Status possíveis