Skip to navigation

Checkout webhook events

Session lifecycle, payments, refunds, and risk holds.

Checkout webhooks use the same Svix application as custodial events. See Checkout links & sessions for the payment flow. For confirmation tiers and per-chain timing, see Transaction statuses.

Two payload shapes

Most checkout events use an envelope built at send time:

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

FieldDescription
checkout_idCheckout UUID
session_idSession UUID
idempotency_keyMerchant idempotency key from checkout create
line_itemsCart snapshot (product_id, sku, quantity, USD prices)
chainNetwork (for example ETHEREUM, SOLANA)
tokenToken symbol (for example USDC, ETH)
amount_requiredRequired crypto amount for this session
amount_receivedConfirmed deposit total
overpayment_amountamount_received − amount_required, or "0"
tx_hashesDeposit transaction hashes (a payment that failed before its confirmation target is left out)
metadataCheckout metadata object from create
risk_flagSession risk metadata, or null

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

{
"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 typeShapeWhen
checkout.payment.detectedEnvelopeA 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.failedEnvelopeA 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.completedEnvelopeSession reaches PAID (first time).
checkout.payment.overpaidEnvelopeSession reaches OVERPAID (first time).
checkout.wrong_token_receivedEnvelopeWrong token sent to the deposit address.
checkout.refund.initiatedEnvelopeRefund worker starts (REFUNDING).
checkout.refund.completedEnvelopeRefund transaction confirmed.
checkout.refund.failedEnvelopeRefund could not complete.
checkout.flagged.acceptedEnvelopeMerchant accepted a flagged session.
checkout.flagged.rejectedEnvelopeMerchant rejected a flagged session (refund queued).
checkout.flaggedFlatCompany-tier risk hold (FLAGGED_PENDING_REVIEW).
checkout.flagged.platform_heldFlatPlatform-tier sanctions hold.
checkout.flagged.auto_returnedFlatQuarantine window expired; auto-return queued.

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). Strict clients that require the field must drop it.

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 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):

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

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

"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:

"token_expected": "USDC",
"token_received": "USDT"

checkout.refund.initiated

Extra fields merged into data:

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

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


checkout.refund.completed

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

checkout.refund.failed

"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):

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