Event catalog

The envelope

Every delivery shares one envelope; data varies by event:

{
  "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.

Order events
Payment events
Refund events
Ping

order.completed, order.partial, order.failed:

{
  "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"
      }
    ]
  }
}

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

payment.detected, payment.confirmed add a payment object:

{
  "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"
    }
  }
}

refund.initiated, refund.completed, refund.failed add a refund object:

{
  "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"
    }
  }
}

{
  "id": "whd_Mn90Op12Qr34",
  "type": "ping",
  "createdAt": 1753142000000,
  "data": { "message": "Wizzgift webhook test" }
}

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, with full field documentation generated from the OpenAPI spec.

Getting started

Quickstarts

Core concepts

Webhooks

The envelope

Events

Payloads

​The envelope

​Events

​Payloads

​Choosing events to subscribe

The envelope

Events

Payloads

Choosing events to subscribe