CryptoCheckout documentation

The checkout runs in an iframe you open from your own page. Your customer never leaves your site.

Install

<script src="https://www.cryptocheckout.ai/sdk/1.2.0/sdk.js"
        integrity="sha384-KIvEacqFSEzotx+MVVRl/PQe+BwMOiDqPfHG2Dtx5bCIHt92kUDgpb5wSl9CY3rF"
        crossorigin="anonymous"></script>

Copy the snippet from API & SDK in your dashboard rather than this page. Yours has your merchant ID and payout address filled in, and it pins the newest release.

Versions

The script URL names a version. A released version never changes, so its integrity hash stays valid for as long as you use it, and nothing we ship later can break a page that pins it. To upgrade, re-copy the snippet from your dashboard; you get the newest version and its hash together. https://www.cryptocheckout.ai/sdk.js, with no version, always serves the newest release. It changes whenever we release, so it is only for trying things out. Don’t put an integrity attribute on it: the next release would stop the checkout from loading.

Minimal integration

<script>
  const checkout = CryptoCheckout.init({
    merchantId: "your-merchant-id",
    settlementAnchor: "0xYourPayoutWalletAddress",
    onPaymentConfirmed: (payload) => {
      window.location = "/thank-you";
    },
  });

  document.querySelector("#pay").addEventListener("click", () => {
    checkout.updateCart({ total: 49.00, currency: "EUR" });
    checkout.open();
  });
</script>

`CryptoCheckout.init(config)`

Returns a checkout instance.

string

required

Your merchant ID, from the dashboard.

string

Your on-chain payout address. The checkout verifies this against the blockchain before accepting payment and blocks on mismatch. Why this matters.Strongly recommended, but not enforced: init() throws only when merchantId is missing. Leave the anchor out and the checkout still takes payment — it just shows a “destination not independently verifiable” notice instead of verifying. Because nothing errors, a refactor that drops the anchor degrades silently, so keep it in your snippet.

string

default:"light"

light or dark. Sets the checkout’s appearance.

string

default:"modal"

modal opens the checkout in a centred overlay. inline renders it inside an element on your page.The modal has a close button, reachable by keyboard, and closes on Esc. On a phone-width screen it goes full-screen under a bar that holds the close button, so there is always something to tap.

string

The id of the DOM element to render into. Required for inline mode — if the element isn’t found, the SDK logs a warning and falls back to modal.

function

Called once when the payment completes. Receives the payment payload, including your orderId and our intentId. On a wallet payment it waits for our settlement step, which lands later than the moment the customer’s payment became irreversible — see Browser events.UI only — fulfil orders from webhooks.

function

Called when a payment attempt fails, with a reason and retryable. A retryable failure means nothing moved and the customer can still pay in the same checkout — don’t cancel the order on it. Not called when the customer simply declines in their wallet. Reasons.

function

Called when the price lock lapsed before funds arrived. Check lateSettlementWatched: when true, a payment still on its way will complete this order, so don’t cancel it yet.

Called when the checkout closes, with reason: completed when the customer pressed Done after paying, dismissed otherwise.

function

Called when the checkout has loaded and completed its handshake with your page. This fires before the cart, the quote, and the on-chain check of your settlementAnchor — it is not a signal that verification passed.

Instance methods

method

Sets the amount to charge. Call before open().

Show cart

number

required

Order total in your display currency.

string

required

EUR or USD.

string

Your order reference. It travels with the quote and comes back to you as orderId on every browser event and every webhook, so you can match a payment to an order. If you leave it out, the SDK generates one.

method

Opens the checkout. In modal mode this shows the overlay; in inline mode the checkout is already on your page, so this only starts it.

method

Closes it programmatically.

method

Switches the checkout between light and dark after it has loaded — useful if your page has its own theme toggle.

method

Tears down the instance and removes its listeners. Call this in your framework’s cleanup hook.

Framework examples

import { useEffect, useRef } from "react";

export function PayButton({ total, currency = "EUR" }) {
  const checkout = useRef(null);

  useEffect(() => {
    checkout.current = window.CryptoCheckout.init({
      merchantId: import.meta.env.VITE_CC_MERCHANT_ID,
      settlementAnchor: import.meta.env.VITE_CC_ANCHOR,
      onPaymentConfirmed: () => (window.location.href = "/thank-you"),
    });
    return () => checkout.current?.destroy();
  }, []);

  const pay = () => {
    checkout.current.updateCart({ total, currency });
    checkout.current.open();
  };

  return <button onClick={pay}>Pay with crypto</button>;
}

<script setup>
import { onMounted, onUnmounted, ref } from "vue";

const props = defineProps({ total: Number, currency: { default: "EUR" } });
const checkout = ref(null);

onMounted(() => {
  checkout.value = window.CryptoCheckout.init({
    merchantId: import.meta.env.VITE_CC_MERCHANT_ID,
    settlementAnchor: import.meta.env.VITE_CC_ANCHOR,
    onPaymentConfirmed: () => (window.location.href = "/thank-you"),
  });
});

onUnmounted(() => checkout.value?.destroy());

function pay() {
  checkout.value.updateCart({ total: props.total, currency: props.currency });
  checkout.value.open();
}
</script>

<template><button @click="pay">Pay with crypto</button></template>

Content Security Policy

If you set a CSP, allow our origin:

script-src  https://www.cryptocheckout.ai;
frame-src   https://www.cryptocheckout.ai;

Use https://www.cryptocheckout.ai, with the www. The apex redirects, and a redirect breaks the origin check the SDK performs.

Troubleshooting

The checkout opens but stays blank

Almost always CSP. Check the browser console for a frame-src violation.

The script doesn't execute at all

An integrity hash that doesn’t match the file. The browser refuses to run it. The usual cause is a hash pinned to the unversioned /sdk.js, which changes with every release. Re-copy the snippet from your dashboard: it pins a versioned URL.

It shows a configuration mismatch warning

Your settlementAnchor doesn’t match the recipient attested on-chain — most often the address in your HTML is an old one. Your payout address isn’t a settings field: it’s locked to the wallet you sign in with, and shown read-only under Pool → Payout (and as your connected wallet under Account). Compare that address with the one in your snippet. This is the protection working. Verification.

onPaymentConfirmed never fires

Expected if the customer closed the tab. The payment still completed — your webhook is the reliable signal. Finality.

Get started

Core concepts

Integration

Webhooks

Your money

Dashboard

Compliance

Reference

Embed the checkout

Install

Versions

Minimal integration

`CryptoCheckout.init(config)`

Instance methods

Framework examples

Content Security Policy

Troubleshooting

​Install

​Versions

​Minimal integration

​CryptoCheckout.init(config)

​Instance methods

​Framework examples

​Content Security Policy

​Troubleshooting

Install

Versions

Minimal integration

`CryptoCheckout.init(config)`

Instance methods

Framework examples

Content Security Policy

Troubleshooting