Crypto Checkout Quickstart: Accept Your First Payment

This guide walks you through the complete payment flow: spinning up your first payment link, sharing the checkout URL with a customer, and watching the session move from pending all the way to paid. By the end you will have verified that your Crypto Checkout deployment is working correctly and you will be ready to integrate it into your store or application.

Prerequisites

Crypto Checkout is deployed and reachable at a known URL (e.g. https://your-domain.com).
You can sign in to the dashboard at https://your-domain.com/dashboard.

Navigate to your dashboard and sign in. On first launch, Crypto Checkout walks you through the seed setup wizard. Enter your BIP39 mnemonic phrase (or generate a new one) to initialise the HD wallet. Your seed is encrypted immediately with AES-256-GCM and never stored in plaintext.

Write down your BIP39 mnemonic and store it securely offline. Losing it means permanent loss of access to all derived wallet addresses and any funds they hold. There is no recovery option.

Once the wizard is complete, the dashboard home screen will show your wallet status as active.

Generate an API key

Go to Dashboard → API Keys and click Create key. Give the key a descriptive name (e.g. quickstart-test) and select at least the following scopes:

sessions:write — create checkout sessions

links:write — create and manage payment links

Click Create. The full key is shown once — copy it now and store it in a secrets manager or .env file.

Key format:

Test mode keys start with ck_test_ — they only interact with test sessions and never process real funds.
Live mode keys start with ck_live_ — use these only when you are ready to accept real payments.

Use a ck_test_ key for this quickstart.

Create a payment link

You can create a payment link from the dashboard UI or via the API.

Dashboard

Go to Dashboard → Payment Links → New link.
Enter a Title (e.g. My Product), a Fiat amount (e.g. 25.00), and select a Currency (USD).
Click Create link.

The dashboard displays the link’s checkoutUrl and a QR code you can share immediately.

REST API

curl -X POST https://your-domain.com/api/v1/payment_links \
  -H "Authorization: Bearer ck_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Product",
    "fiatAmount": "25.00",
    "fiatCurrency": "USD"
  }'

Example response:

{
  "id": "018f4e2a-...",
  "object": "payment_link",
  "slug": "buy-my-product",
  "title": "My Product",
  "fiatAmount": "25.00",
  "fiatCurrency": "USD",
  "active": true,
  "checkoutUrl": "https://your-domain.com/l/buy-my-product",
  "createdAt": "2024-11-01T12:00:00.000Z",
  "updatedAt": "2024-11-01T12:00:00.000Z"
}

TypeScript SDK

import { CheckoutClient } from "@your-org/checkout-sdk";

const client = new CheckoutClient({
  apiKey: process.env.CHECKOUT_API_KEY!,
  baseUrl: "https://your-domain.com",
});

const link = await client.paymentLinks.create({
  title: "My Product",
  fiatAmount: "25.00",
  fiatCurrency: "USD",
});

console.log(link.checkoutUrl); // https://your-domain.com/l/buy-my-product

The /l/{slug} URL is what your customers visit. When they open the link, Crypto Checkout automatically creates a new session with a fresh deposit address — no action required on your part.

You can share the URL directly, embed it as a button on your site, or display the QR code shown in the dashboard. Every scan of the same link creates an independent session, so the link is safe to reuse.

The dashboard shows a live QR code for every payment link. You can download it as a PNG for use in print materials or in-person point-of-sale displays.

Receive a test payment

Open the checkout URL in a browser. You will see the deposit address and a countdown timer. Send the exact fiat-equivalent amount in the displayed asset to the shown address.

The session moves through the following statuses automatically:

StatusMeaningpendingSession created, waiting for an on-chain transferdetectedA matching transfer was seen on-chain; awaiting confirmationspaidThe required number of confirmations reached — payment completeunderpaidA transfer was received but for less than the required amountoverpaidA transfer was received for more than the required amountpaid_latePayment confirmed after the session expired but within the grace windowfailedThe session encountered an unrecoverable errorexpiredThe session timer elapsed with no detected payment

You can verify the final status in the dashboard, or by polling the API:

curl https://your-domain.com/api/v1/checkout_sessions/SESSION_ID \
  -H "Authorization: Bearer ck_test_YOUR_KEY"

{
  "id": "018f4e2b-...",
  "object": "checkout_session",
  "status": "paid",
  "paidAt": "2024-11-01T12:03:45.000Z",
  "txHash": "0xabc123...",
  "livemode": false
}

If you triggered the payment but the status is stuck on detected, click the Check payment button on the session detail page in the dashboard. This runs an on-chain scan inline and resolves the session immediately.

Set up webhooks

For production use, configure a webhook endpoint so your backend is notified the instant a payment is confirmed — no polling required.

See the Webhooks overview for instructions on registering an endpoint, selecting events (start with session.paid), and verifying the X-Webhook-Signature header.

Quickstart with the TypeScript SDK

If you prefer to create sessions programmatically rather than using payment links, the SDK checkoutSessions.create method gives you full control over amount, metadata, and redirect URLs.

import { CheckoutClient } from "@your-org/checkout-sdk";

const client = new CheckoutClient({
  apiKey: process.env.CHECKOUT_API_KEY!,
  baseUrl: "https://your-domain.com",
});

const session = await client.checkoutSessions.create({
  amount: { value: "25.00", currency: "USD" },
  successUrl: "https://your-store.com/success",
  metadata: { orderId: "order_001" },
});

console.log(session.checkoutUrl); // redirect your customer here

Redirect the customer to session.checkoutUrl. Once the payment is confirmed, Crypto Checkout will redirect them to your successUrl and fire the session.paid webhook.

Test mode vs. live mode

Always use a ck_test_ key during development. Test sessions never move real funds. When you are ready to go live, generate a ck_live_ key from the dashboard and update your environment variables. Live and test sessions are fully isolated — a live key cannot retrieve test sessions and vice versa.

​Prerequisites

​Quickstart with the TypeScript SDK

​Test mode vs. live mode

Prerequisites

Quickstart with the TypeScript SDK

Test mode vs. live mode