Devoluções

Como as devoluções chegam no webhook.

Cada devolução concluída no banco gera um webhook no mesmo evento de estorno (pix_in.refunded na cobrança, pix_out.refunded no saque), com o acumulado até ela:

Situação	status	partial	Status da transação depois
Devolução parcial (a soma ainda não chega ao valor)	PARTIALLY_REFUNDED	true	continua PAID
Devolução que completa o valor	REFUNDED	false	REFUNDED

Por exemplo, um saque de R$ 100,00 devolvido em R$ 30,00, R$ 20,00 e R$ 50,00 gera três webhooks pix_out.refunded: PARTIALLY_REFUNDED com refundedAmount 30,00, PARTIALLY_REFUNDED com 50,00 e REFUNDED com 100,00.

• A devolução que gerou o webhook é a última de devolutions; as anteriores vêm junto para você conferir o histórico.
• Use o id de cada devolução para não processar a mesma duas vezes em caso de reenvio.
• Considere a cobrança ou o saque devolvido por completo só quando status for REFUNDED (partial: false).
• Saque devolvido antes da confirmação do pagamento: a devolução é avisada logo depois do pix_out.paid.

Exemplo — Saque de R$ 100,00: primeira devolução parcial (R$ 30,00):

{
  "event": "PIX_OUT_UPDATE",
  "method": "PIX_OUT",
  "status": "PARTIALLY_REFUNDED",
  "partial": true,
  "transactionId": "01961234-abcd-7000-8000-000000000002",
  "idempotency": "saque-67890",
  "value": 100.00,
  "valueFee": 2.50,
  "valueLiquid": 102.50,
  "destination": {
    "pixKey": "12345678900",
    "pixType": "DOCUMENT"
  },
  "customer": {
    "fullName": "Maria Oliveira",
    "document": "12345678900"
  },
  "endToEndId": "E12345678202301011200abcdefghijkl",
  "refundedAmount": 30.00,
  "devolutionSummary": {
    "originalAmount": 100.00,
    "refundedAmount": 30.00,
    "pendingAmount": 0,
    "remainingAmount": 70.00
  },
  "devolutions": [
    {
      "id": "01961234-abcd-7000-8000-0000000000d1",
      "endToEndId": "D98765432202501171200abcdefghij1",
      "amount": 30.00,
      "refundedAt": "2025-01-17T12:00:00.000Z"
    }
  ]
}

---