---
title: "Checkout cancelled"
method: POST
path: "checkout.cancelled"
---

# Checkout cancelled

`POST checkout.cancelled` (webhook)

Sent when the provider cancels the checkout upstream (refund/error). Sent to the checkout's callback_url (checkout-level, falling back to product/merchant defaults at creation time). Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `"${t}.${raw body}"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.

## Headers

- `X-DePix-Signature` string, required
- `X-DePix-Event-Id` string, required

## Payload

- object: Envelope of the checkout.cancelled event.
  - `event` 'checkout.cancelled', required: Event name — fixed for this webhook.
  - `data` CheckoutWebhookData, required: Checkout event payload.
    - `id` string, required: Checkout id (chk_*).
    - `status` union, required: Checkout lifecycle status — the enum below is the complete, closed set. `completed` is the terminal SUCCESS state. Terminal states (safe to stop polling): completed, expired, cancelled.
      - 'pending': Awaiting payment; the PIX QR is active until expires_at.
      - 'processing': PIX paid; settlement in progress.
      - 'approved': Payment approved by the provider; DePix on the way to the merchant.
      - 'completed': TERMINAL — success: DePix delivered to the merchant.
      - 'expired': TERMINAL — QR expired unpaid.
      - 'cancelled': TERMINAL — cancelled upstream by the provider (refund/error).
    - `is_live` boolean, required: False for a sandbox checkout (sk_test_, or one completed from the hosted sandbox payment page). Sandbox events are signed with the same secret and carry the same shape as live ones, so this is the field that separates them — never release goods on false.
    - `amount` integer, required: Charge amount in cents — always the FACE value, never what the payer actually paid (see amount_received).
    - `payment_method` 'pix' | 'depix': Which rail settles the checkout. `pix` (default): the payer pays a PIX QR and the provider delivers DePix to the merchant. `depix`: the payer sends DePix wallet-to-wallet on Liquid to an address dedicated to this merchant, and settlement is observed on-chain — no PIX QR exists on this rail.
    - `amount_received` integer: What the payer actually paid, in cents — present on the depix rail, where it is `amount` minus the merchant's discount and minus the cents adjustment that made the value unique. Release goods against THIS value.
    - `discount_pct` integer: DePix discount applied to this checkout, 0–90 — present on the depix rail.
    - `product_id` string, nullable, required: Originating product/charge id (prd_*); null for standalone checkouts. For charges, pair with metadata.charge_cycle to know WHICH competência settled.
    - `metadata` union: Merchant metadata when set on the checkout (omitted otherwise).
      - object
      - string
    - `processing_at` string: Transition timestamp — present on checkout.processing.
    - `approved_at` string: Transition timestamp — present on checkout.approved.
    - `completed_at` string: Transition timestamp — present on checkout.completed.
    - `cancelled_at` string: Transition timestamp — present on checkout.cancelled.
    - `rejection_reasons` string[]: Provider reasons for the refusal/refund — present on checkout.cancelled, so revoking on the webhook needs no follow-up GET to learn WHY. Same catalog as the REST reads (PAYER_MISMATCH, PAST_DAILY_LIMIT, BLOCKED_USER, HIGH_VELOCITY, ...); [] when the provider reported none. New codes may appear; display unknown codes as-is.
    - `blockchain_tx_id` string: Liquid txid of the settlement — present on checkout.completed when known.
    - `event_id` string, required: Stable delivery id (evt_*) — identical across retries of the same event; use it for deduplication. Also sent as the X-DePix-Event-Id header.

## Acknowledgement `200`

Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry.

---

[API](https://skmtc.dev/depixapp/apis/depix-api.md) · [All operations](https://skmtc.dev/depixapp/apis/depix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/depixapp/apis/depix-api/revisions/04094536dd0f?raw)