Skip to main content

​
Visão Geral

O evento REFUND é disparado quando o status de um estorno é atualizado na plataforma. O webhook é enviado quando:
  • Um estorno muda de status (ex: PROCESSING → SETTLED, PROCESSING → FAILED)

​
Headers do Webhook

X-Webhook-Event: REFUND
X-Webhook-Timestamp: 2024-01-15T11:00:00Z
X-Webhook-Signature: abc123def456...
Content-Type: application/json

​
Estrutura do Payload

{
  "event": "REFUND",
  "timestamp": "2024-01-15T11:00:00Z",
  "data": {
    "uuid": "770e8400-e29b-41d4-a716-446655440000",
    "status": "PROCESSING",
    "value": 247.99,
    "fees": 0.5,
    "refund": {
      "status": "PROCESSING",
      "value": 247.99,
      "fees": 0.5,
      "pix_original": {
        "uuid": "880e8400-e29b-41d4-a716-446655440001",
        "initiation": {
          "sender": {
            "name": "João Silva",
            "document": "12345678901",
            "account_number": "00123456",
            "account_agency": "0001",
            "bank": {
              "code": "341",
              "name": "ITAÚ UNIBANCO S.A.",
              "ispb": "60701190"
            },
            "account_type": "CHECKING"
          },
          "receiver": {
            "name": "Empresa Demo LTDA",
            "document": "12345678000190",
            "account_number": "9876543",
            "account_agency": "0001",
            "bank": {
              "code": "",
              "name": "PLOWF IP LTDA.",
              "ispb": "00000000"
            },
            "account_type": "CHECKING"
          },
          "txid": "770e8400e29b41d4a716446655440000",
          "value": "247.99",
          "type": "QR_DYNAMIC",
          "pix_key": "550e8400-e29b-41d4-a716-446655440000",
          "additional_info": [
            {
              "name": "ID do pagamento",
              "value": "990e8400-e29b-41d4-a716-446655440002"
            }
          ],
          "status": "COMPLETED",
          "expires_at": "2024-01-02T10:00:00.000000Z",
          "created_at": "2024-01-01T10:00:00.000000Z",
          "updated_at": "2024-01-01T10:05:00.000000Z"
        },
        "value": "247.99",
        "movement_type": "IN",
        "type": "EXTERNAL_TRANSFER",
        "status": "SETTLED",
        "end_to_end": "E6070119020240101100500000000001",
        "settled_at": "2024-01-01T10:05:00.000000Z",
        "created_at": "2024-01-01T10:05:00.000000Z",
        "updated_at": "2024-01-01T10:05:00.000000Z"
      },
      "pix_refund": {
        "uuid": "990e8400-e29b-41d4-a716-446655440002",
        "initiation": {
          "sender": {
            "name": "Empresa Demo LTDA",
            "document": "12345678000190",
            "account_number": "9876543",
            "account_agency": "0001",
            "bank": {
              "code": "",
              "name": "PLOWF IP LTDA.",
              "ispb": "00000000"
            },
            "account_type": "CHECKING"
          },
          "receiver": {
            "name": "João Silva",
            "document": "12345678901",
            "account_number": "00123456",
            "account_agency": "0001",
            "bank": {
              "code": "341",
              "name": "ITAÚ UNIBANCO S.A.",
              "ispb": "60701190"
            },
            "account_type": "CHECKING"
          },
          "txid": null,
          "value": 247.99,
          "type": "REFUND",
          "status": "COMPLETED",
          "expires_at": null,
          "created_at": "2024-01-02T10:00:00.000000Z",
          "updated_at": "2024-01-02T10:00:00.000000Z"
        },
        "value": 247.99,
        "movement_type": "OUT",
        "type": "EXTERNAL_REFUND",
        "status": "PENDING",
        "end_to_end": "D0000000020240102100000000000001",
        "settled_at": null,
        "created_at": "2024-01-02T10:00:00.000000Z",
        "updated_at": "2024-01-02T10:00:00.000000Z"
      },
      "created_at": "2024-01-02T10:00:00.000000Z",
      "updated_at": "2024-01-02T10:00:00.000000Z"
    },
    "history": [
      {
        "status": "PENDING",
        "created_at": "2024-01-01T10:00:00Z"
      },
      {
        "status": "PAID",
        "created_at": "2024-01-01T10:05:00Z"
      }
    ],
    "created_at": "2024-01-15T10:45:00Z",
    "updated_at": "2024-01-15T11:00:00Z"
  }
}

​
Campos do Payload

​
event
string
Tipo do evento. Sempre "REFUND" para este webhook.
​
timestamp
datetime
Timestamp ISO 8601 do momento em que o webhook foi enviado.
​
data
object
Dados do estorno atualizado.

​
Status Possíveis

Os status possíveis para um estorno são:
  • PENDING - Aguardando processamento
  • PROCESSING - Estorno em processamento
  • SETTLED - Estorno liquidado
  • FAILED - Estorno falhou
  • CANCELLED - Estorno cancelado
Use o campo uuid para identificar unicamente o estorno e implementar idempotência no seu endpoint.