Headless checkout

Headless checkout gives you full control of the buying experience. It's how swopme.co/shop works.

The flowCopy Anchor Link

1. The buyer builds a cart on your site.
2. Your server sends the cart to Swop: POST /checkout-intents. Swop prices everything from your catalogue and returns a checkout.
3. Your page shows the amount and a way to pay: a USDC payment link/QR code, and a card form if card is offered.
4. The buyer pays. Swop detects the payment, creates the order and emails the receipt.
5. Your page polls GET /checkout-intents/{intentId} until it's paid, and your back office gets a checkout.paid webhook.

Key scopes: commerce.checkout (create) and commerce.read (poll). commerce.checkout is the only merchant scope that can create something payable, so give it only to the server that needs it.

1. Create the checkoutCopy Anchor Link

POST https://apps.apiswop.co/api/v5/merchant/checkout-intents

curl -X POST https://apps.apiswop.co/api/v5/merchant/checkout-intents \
  -H "Authorization: Bearer $SWOP_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "productId": "66a1b2c3d4e5f6a7b8c9d0e1", "quantity": 1, "selectedOptions": { "Color": "Black" } }
    ],
    "customerInfo": {
      "name": "Ada Buyer",
      "email": "ada@example.com",
      "address": { "line1": "1 Main St", "city": "Austin", "state": "TX", "postalCode": "78701", "country": "US" }
    },
    "paymentRail": "buyer_choice"
  }'

The 201 response is the full checkout. See the checkout-intents reference for every field; these are the ones your page uses:

2. Take the paymentCopy Anchor Link

Crypto (USDC)Copy Anchor Link

When paymentRequest is set, it's a Solana Pay request for USDC on Solana:

"paymentRequest": {
  "rail": "solana_pay",
  "amount": 30,
  "currency": "USDC",
  "tokenMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "url": "solana:…",
  "status": "awaiting_payment",
  "expiresAt": "2026-10-28T18:00:00.000Z"
}

Show paymentRequest.url as an Open your wallet link (mobile) and as a QR code (desktop). The buyer's wallet pays it; Swop sees the transfer on-chain and completes the order. You don't call anything to confirm.

CardCopy Anchor Link

When cardOffered is true, paymentRequest stays null until the buyer picks a method. Show two buttons and call one of these public endpoints. They need no API key: the unguessable intentId authorises them, so you can call them from the browser or your server.

Card numbers go from the buyer's browser straight to Stripe and never touch Swop or your server. These public endpoints are rate-limited (20 requests per 15 minutes per client).

3. Show "paid"Copy Anchor Link

Poll GET /checkout-intents/{intentId} every few seconds while the buyer is on your payment step:

const res = await fetch(`https://apps.apiswop.co/api/v5/merchant/checkout-intents/${intentId}`, {
  headers: { Authorization: `Bearer ${process.env.SWOP_MERCHANT_KEY}` },
});
const { data } = await res.json();

For card, the checkout can stay active while Stripe processes the charge. Also read GET https://apps.apiswop.co/api/v5/checkout-intents/{intentId}/card-payment (public) and treat a state of transfer_pending, transfer_in_progress or transferred as paid.

Polling is for the buyer's screen. For your order system, use webhooks.

Go-live checklistCopy Anchor Link

• Key in a server environment variable, never in the browser.
• Key has only commerce.checkout and commerce.read (add commerce.embed only if you frame).
• No prices in the checkout request.
• Physical items send name, email and a full address.
• Your webhook endpoint verifies Swop-Signature and de-duplicates deliveries.
• You ship on checkout.paid and book revenue on payout.released.
• Error states never tell a buyer they weren't charged.
• One real low-value purchase completed end to end.