> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wizzgift.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Event catalog

> Every event and its payload.

## The envelope

Every delivery shares one envelope; `data` varies by event:

```json theme={null}
{
  "id": "whd_Xy12Ab34Cd56",
  "type": "order.completed",
  "createdAt": 1753142400000,
  "data": { "...": "..." }
}
```

`id` is the delivery id (stable across retries — deduplicate on it), `type` is the event name, `createdAt` is epoch milliseconds.

## Events

| Event               | Fires when                                          |
| ------------------- | --------------------------------------------------- |
| `payment.detected`  | Customer's transaction seen, awaiting confirmations |
| `payment.confirmed` | Payment fully confirmed — fulfillment starts        |
| `order.completed`   | Every item fulfilled — codes ready to fetch         |
| `order.partial`     | Some items fulfilled, some failed                   |
| `order.failed`      | No item could be fulfilled                          |
| `refund.initiated`  | A refund was created                                |
| `refund.completed`  | The refund finished                                 |
| `refund.failed`     | The refund attempt failed                           |
| `ping`              | Manual test via `POST /retailer/v1/webhook/test`    |

## Payloads

All order-related events carry the same base: checkout identity, status, totals, and an item summary. Payment and refund events add one extra object.

<Tabs>
  <Tab title="Order events">
    `order.completed`, `order.partial`, `order.failed`:

    ```json theme={null}
    {
      "id": "whd_Xy12Ab34Cd56",
      "type": "order.completed",
      "createdAt": 1753142400000,
      "data": {
        "checkoutId": "chkr_ab12cd34",
        "externalRef": "shop-order-889",
        "status": "completed",
        "totalAmount": 27.3,
        "currency": "USD",
        "items": [
          {
            "id": "itm_1",
            "productId": "prod_psn_de",
            "productName": "PlayStation Store 25 EUR (DE)",
            "quantity": 1,
            "status": "completed"
          }
        ]
      }
    }
    ```

    <Note>
      No card codes — fetch them with `GET /retailer/v1/checkouts/{checkoutId}` after verifying the signature.
    </Note>
  </Tab>

  <Tab title="Payment events">
    `payment.detected`, `payment.confirmed` add a `payment` object:

    ```json theme={null}
    {
      "id": "whd_Qr78St90Uv12",
      "type": "payment.confirmed",
      "createdAt": 1753142300000,
      "data": {
        "checkoutId": "chkr_ab12cd34",
        "externalRef": "shop-order-889",
        "status": "processing",
        "totalAmount": 27.3,
        "currency": "USD",
        "items": ["..."],
        "payment": {
          "paymentId": "pay_x1",
          "method": "Bitcoin",
          "amount": 27.3,
          "currency": "USD"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Refund events">
    `refund.initiated`, `refund.completed`, `refund.failed` add a `refund` object:

    ```json theme={null}
    {
      "id": "whd_Gh34Ij56Kl78",
      "type": "refund.completed",
      "createdAt": 1753150000000,
      "data": {
        "checkoutId": "chkr_ab12cd34",
        "externalRef": "shop-order-889",
        "status": "partial",
        "totalAmount": 27.3,
        "currency": "USD",
        "items": ["..."],
        "refund": {
          "amount": 27.3,
          "method": "balance",
          "reason": "fulfillment_failed"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Ping">
    ```json theme={null}
    {
      "id": "whd_Mn90Op12Qr34",
      "type": "ping",
      "createdAt": 1753142000000,
      "data": { "message": "Wizzgift webhook test" }
    }
    ```
  </Tab>
</Tabs>

## Choosing events to subscribe

Most integrations only need the order terminals:

* **Minimal:** `order.completed`, `order.partial`, `order.failed` — fetch codes on completed/partial, alert on failed.
* **With payment UX:** add `payment.detected` and `payment.confirmed` to update your customer's payment screen in real time.
* **With refund tracking:** add the three `refund.*` events.

The exact payload schemas are also documented under **Webhook payloads** in the [API reference](/api-reference/introduction), with full field documentation generated from the OpenAPI spec.