CryptoCheckout documentation

Never fulfil an order from a browser callback.These fire in the customer’s browser. If they close the tab, lose signal, or their battery dies, the callback never runs — but the payment still completed. Use webhooks for fulfilment and these for UI.

The callbacks

function

The checkout has loaded and completed on-chain verification. Good moment to hide your own loading state.

function

The payment reached finality. Receives the payment payload.Use it to redirect to a thank-you page or show a success state — not to release goods.

function

The payment attempt failed. Receives an error payload.

The customer dismissed the checkout. Fires whether or not they paid — a customer can pay and then close, so don’t read this as abandonment on its own.

Typical usage

const checkout = CryptoCheckout.init({
  merchantId: "…",
  settlementAnchor: "0x…",

  onReady: () => {
    setLoading(false);
  },

  onPaymentConfirmed: (payload) => {
    // UI only. Your webhook is what actually fulfils.
    analytics.track("payment_confirmed", { orderId: payload?.orderId });
    window.location.href = "/thank-you";
  },

  onPaymentFailed: (err) => {
    showBanner("Payment didn't complete. Nothing was charged.");
    console.error(err);
  },

  onWidgetClosed: () => {
    // Don't assume abandonment — the webhook may still arrive.
    setLoading(false);
  },
});

Checkout states

The customer may see these. Worth recognising them in support conversations.

State	What happened
Verified	On-chain verification passed. Normal.
Unverified badge	No `settlementAnchor` pinned. Payment still works, verification didn’t run.
Configuration mismatch	Verification failed. Signing blocked, address hidden. Check your payout settings.
Recipient changed	The on-chain payout address moved between quote and signature. Customer is asked to refresh.
Rate limited	Too many requests. Counts down and retries automatically.
Session expired	Quote lapsed before payment. A fresh quote is issued.

Set up webhooks

The reliable path. Do this before going live.

Get started

Core concepts

Integration

Webhooks

Your money

Dashboard

Compliance

Reference

Browser events

The callbacks

Typical usage

The race you need to handle

Checkout states

Set up webhooks

​The callbacks

​Typical usage

​The race you need to handle

​Checkout states

Set up webhooks

The callbacks

Typical usage

The race you need to handle

Checkout states