> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://doc.cheddar.biz/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://doc.cheddar.biz/_mcp/server.

# Checkout webhook events

Checkout webhooks use the same Svix application as
[custodial events](/webhooks/custodial). See [Checkout links & sessions](/guides/checkout) for the payment flow.
For confirmation tiers and per-chain timing, see [Transaction statuses](/guides/transaction-statuses).

## Two payload shapes

Most checkout events use an **envelope** built at send time:

```json
{
  "id": "evt_a1b2c3d4e5f6…",
  "type": "checkout.payment.completed",
  "created_at": "2026-01-01T12:00:00.000Z",
  "data": { }
}
```

The `data` object always includes the fields below (plus event-specific
extras). Amounts are **human token units** (same as the checkout session), not
wei or lamports.

| Field                | Description                                                                                   |
| -------------------- | --------------------------------------------------------------------------------------------- |
| `checkout_id`        | Checkout UUID                                                                                 |
| `session_id`         | Session UUID                                                                                  |
| `idempotency_key`    | Merchant idempotency key from checkout create                                                 |
| `line_items`         | Cart snapshot (`product_id`, `sku`, `quantity`, USD prices)                                   |
| `chain`              | Network (for example `ETHEREUM`, `SOLANA`)                                                    |
| `token`              | Token symbol (for example `USDC`, `ETH`)                                                      |
| `amount_required`    | Required crypto amount for this session                                                       |
| `amount_received`    | Confirmed deposit total                                                                       |
| `overpayment_amount` | `amount_received − amount_required`, or `"0"`                                                 |
| `tx_hashes`          | Deposit transaction hashes (a payment that failed before its confirmation target is left out) |
| `metadata`           | Checkout metadata object from create                                                          |
| `risk_flag`          | Session risk metadata, or `null`                                                              |

**Risk / quarantine** events use a **flat** payload (no envelope):

```json
{
  "eventType": "checkout.flagged",
  "eventId": "evt_checkout_checkout.flagged_session-uuid",
  "checkoutId": "checkout-uuid",
  "sessionId": "session-uuid",
  "status": "FLAGGED_PENDING_REVIEW",
  "idempotency_key": "your-idempotency-key",
  "riskFlag": { }
}
```

---

## Event catalog

| Event type                       | Shape    | When                                                                                                                                                                                |
| -------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `checkout.payment.detected`      | Envelope | A payment is in a block and counting toward its confirmation target. Fires before the risk scan, so the session may not be `CONFIRMING` yet. Informational: nothing is counted yet. |
| `checkout.payment.failed`        | Envelope | A detected payment reorged out (or its result flipped) before its confirmation target. It is never counted; the session goes back to waiting for payment.                           |
| `checkout.payment.completed`     | Envelope | Session reaches `PAID` (first time).                                                                                                                                                |
| `checkout.payment.overpaid`      | Envelope | Session reaches `OVERPAID` (first time).                                                                                                                                            |
| `checkout.wrong_token_received`  | Envelope | Wrong token sent to the deposit address.                                                                                                                                            |
| `checkout.refund.initiated`      | Envelope | Refund worker starts (`REFUNDING`).                                                                                                                                                 |
| `checkout.refund.completed`      | Envelope | Refund transaction confirmed.                                                                                                                                                       |
| `checkout.refund.failed`         | Envelope | Refund could not complete.                                                                                                                                                          |
| `checkout.flagged.accepted`      | Envelope | Merchant accepted a flagged session.                                                                                                                                                |
| `checkout.flagged.rejected`      | Envelope | Merchant rejected a flagged session (refund queued).                                                                                                                                |
| `checkout.flagged`               | Flat     | Company-tier risk hold (`FLAGGED_PENDING_REVIEW`).                                                                                                                                  |
| `checkout.flagged.platform_held` | Flat     | Platform-tier sanctions hold.                                                                                                                                                       |
| `checkout.flagged.auto_returned` | Flat     | Quarantine window expired; auto-return queued.                                                                                                                                      |

> **Warning**
>
> **Breaking REST change:** the `minConfirmations` field is removed from the
> `CheckoutSession` response. Confirmation depth is now set per chain and
> payment value (see [Confirmation targets](#confirmation-targets)). Strict
> clients that require the field must drop it.

> **Note**
>
> Several `checkout.*` types exist in the API enum for future lifecycle hooks
> (for example `checkout.session.created`, `checkout.payment.confirming`) but are
> **not emitted today**. Subscribe only to the types above unless release notes
> say otherwise.

## Confirmation targets

Confirmation tracking rolls out per chain (Ethereum, BSC, Polygon, Robinhood
Chain, Tron, Solana; release notes announce each one). On a chain where it is
on, a payment is not counted at first block inclusion:

1. The payment is seen in a block: `checkout.payment.detected` fires. The
   session moves to `CONFIRMING` after the payment's risk scan, so it may
   still show its previous status (or a risk hold) when `detected` arrives.
2. Cheddar counts confirmations until the payment meets a target chosen by
   chain and by the payment's USD value (see [Transaction statuses](/guides/transaction-statuses) for targets and expected times).
3. At the target, the payment counts toward `amount_received`, and
   `checkout.payment.completed` / `checkout.payment.overpaid` fire as before.
   Settlement starts only after that. These events can therefore arrive minutes
   after `detected` (longer for high-value payments on slower chains).
4. If the payment leaves the chain first, `checkout.payment.failed` fires
   instead. The session goes back to `AWAITING_PAYMENT` (or `PARTIAL` if
   another payment already counted) and expires normally if its window has
   closed.

A `CONFIRMING` session does not expire while a payment is still counting
confirmations. A payment seen before the session's `expiresAt` that meets its
target afterwards still completes the session. An invoice past its due date
stays open while one of its payments is still counting confirmations.

On chains without tracking, payments count at first block inclusion, as before.
Some payments are counted at first inclusion even on a chain where tracking is
on, when Cheddar learns of them without a block reference (for example EVM
payments seen in the mempool, and some Tron and Solana payments).

## Test events

Send a sample of any event in the catalog above from **Dashboard → Webhooks →
Send test event**. Test payloads have the real shape and placeholder data, and
they don't create sessions or move funds. They carry a test flag:

* Envelope events get `"is_test": true` at the top level, next to `id` and `type`.
* Flat risk events (`checkout.flagged`, `checkout.flagged.platform_held`,
  `checkout.flagged.auto_returned`) get `"isTest": true`.

Real events never include the flag, so a missing flag means the event is real.

---

### Shared `data` example

The following `data` block is representative for envelope events (payment
completed shown; other events reuse the same core fields):

```json
{
  "id": "evt_a1b2c3d4e5f6789012345678901234567890",
  "type": "checkout.payment.completed",
  "created_at": "2026-01-01T12:00:00.000Z",
  "data": {
    "checkout_id": "3f1a7c2e-9b4d-4a61-8f0c-2d5e7a9b1c34",
    "session_id": "8b2c9d1e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
    "idempotency_key": "order-2026-001",
    "line_items": [
      {
        "product_id": "prod-1",
        "sku": "SKU-A",
        "quantity": 2,
        "unit_price_usd": "10.00",
        "line_total_usd": "20.00"
      }
    ],
    "chain": "ETHEREUM",
    "token": "USDC",
    "amount_required": "20.50",
    "amount_received": "20.50",
    "overpayment_amount": "0",
    "tx_hashes": ["0xabc…"],
    "metadata": { "orderId": "order-2026-001" },
    "risk_flag": null,
    "platform_fee": "0.21",
    "net_credited": "20.29"
  }
}
```

`platform_fee` and `net_credited` appear only on `checkout.payment.completed`
and `checkout.payment.overpaid`. They are estimated from org checkout config at
payment time (fee is accrued to the monthly platform bill, not deducted on-chain
from the sweep).

---

### `checkout.payment.detected` / `checkout.payment.failed`

Same core `data` fields (`amount_received` counts confirmed payments only, so
it does not include this one), plus the payment:

```json
"transaction": {
  "id": "5e1f2a3b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
  "tx_hash": "0xabc…",
  "amount": "20.50",
  "from_address": "0xpayer…",
  "status": "PROCESSING",
  "confirmation_tier": "MEDIUM",
  "confirmation_target": { "kind": "blocks", "blocks": 12 }
}
```

`checkout.payment.failed` has `"status": "FAILED"` in `transaction`, and a
top-level `reason`: `REORGED_OUT` (the transaction left the chain) or
`RESULT_FLIPPED` (it is now reported as failed on-chain).

```json
"reason": "REORGED_OUT"
```

Each event is sent once per payment. A session can see several payments, so
key your handling on `transaction.id`.

---

### `checkout.payment.overpaid`

Same envelope as completed. `type` is `checkout.payment.overpaid` and
`overpayment_amount` is greater than `"0"`.

---

### `checkout.wrong_token_received`

Same core `data` fields, plus:

```json
"token_expected": "USDC",
"token_received": "USDT"
```

---

### `checkout.refund.initiated`

Extra fields merged into `data`:

```json
"checkoutId": "3f1a7c2e-9b4d-4a61-8f0c-2d5e7a9b1c34",
"status": "REFUNDING"
```

(`checkoutId` duplicates `checkout_id` — both are present in the payload
today.)

---

### `checkout.refund.completed`

```json
"checkoutId": "3f1a7c2e-9b4d-4a61-8f0c-2d5e7a9b1c34",
"txHash": "0xrefund…"
```

---

### `checkout.refund.failed`

```json
"checkoutId": "3f1a7c2e-9b4d-4a61-8f0c-2d5e7a9b1c34",
"reason": "Insufficient gas on deposit address"
```

---

### `checkout.flagged.accepted` / `checkout.flagged.rejected`

Standard envelope and shared `data` fields. `type` is
`checkout.flagged.accepted` or `checkout.flagged.rejected`. Settlement or
refund is queued after the webhook.

---

### Flat risk events

**`checkout.flagged`** (merchant review):

```json
{
  "eventType": "checkout.flagged",
  "eventId": "evt_checkout_checkout.flagged_8b2c9d1e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
  "checkoutId": "3f1a7c2e-9b4d-4a61-8f0c-2d5e7a9b1c34",
  "sessionId": "8b2c9d1e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
  "status": "FLAGGED_PENDING_REVIEW",
  "idempotency_key": "order-2026-001",
  "riskFlag": {
    "tier": "company",
    "score": 25,
    "severity": "HIGH_RISK",
    "entityType": "MIXER",
    "entityName": "Example Mixer",
    "flaggedAt": "2026-01-01T12:00:00.000Z"
  }
}
```

**`checkout.flagged.platform_held`** — same shape; `status` is
`FLAGGED_PLATFORM_HELD`.

**`checkout.flagged.auto_returned`** — same shape; `status` is `REFUNDING`
(session moves to refund after the quarantine deadline). The checkout row is
marked `FLAGGED_AUTO_RETURNED` in the dashboard, but that value is not sent in
this webhook.

`riskFlag` is the session's stored risk metadata; fields vary by scan outcome.