API reference
Swipe lets customers pay with any Solana coin while you receive USDC. The API follows the shape of card-processor checkout APIs: create a session on your server, send the customer to its url, and listen for a webhook.
Base URL: https://swipecheckout.xyz
Quickstart
- Sign up at /dashboard and connect the wallet you want to be paid to.
- Under Developers, create a secret key and set your webhook URL.
- Create a checkout session from your server and redirect the customer to
session.url. - Fulfil the order when
checkout.session.completedarrives.
No code? Create a payment link in the dashboard and share it. Step-by-step setup is in the guides.
Authentication
Send your secret key as a bearer token. Keep it on your server; anyone with it can create checkouts that pay you.
Authorization: Bearer sk_live_...
Create a session
POST /v1/checkout/sessions. JSON or form-encoded.
- amount (required): price in USD as a string, e.g.
"24.00". Between 0.50 and 10,000. - name: what the customer is paying for. Shown on the checkout.
- description: optional extra line on the checkout.
- success_url, cancel_url: where to send the customer after paying, or if they go back.
- metadata: up to 20 string key/value pairs, returned to you on the session and webhook.
curl https://swipecheckout.xyz/v1/checkout/sessions \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{"amount":"24.00","name":"Cold brew subscription",
"success_url":"https://yourshop.com/thanks",
"metadata":{"order_id":"8231"}}'Retrieve a session
GET /v1/checkout/sessions/:id returns the latest state. Use it to double-check a payment before fulfilling, or if you missed a webhook.
curl https://swipecheckout.xyz/v1/checkout/sessions/cs_... \ -H "Authorization: Bearer sk_live_..."
The session object
{
"id": "cs_Qm3x...",
"object": "checkout.session",
"status": "paid", // open | paid | expired
"amount": "24.00",
"currency": "usd",
"name": "Cold brew subscription",
"url": "https://swipecheckout.xyz/pay/cs_Qm3x...",
"success_url": "https://yourshop.com/thanks",
"metadata": { "order_id": "8231" },
"created": 1794810000,
"expires_at": 1794896400, // sessions stay open for 24 hours
"payment": {
"signature": "5h7k...", // Solana transaction
"payer": "7xKX...gAsU",
"sym": "WIF", // what the customer paid with
"net": "23.76", // USDC you received
"fee": "0.24", // USDC Swipe received
"at": 1794810042
}
}Payment links
Links are made in the dashboard. Each visit to /l/pl_... opens a new checkout session for the link's price, so one link can be paid any number of times. Payments made through a link appear in your dashboard and fire the same webhook.
Webhooks
When a payment is confirmed and we've checked on chain that your USDC account received the right amount, we POST an event to your webhook URL. If your server doesn't answer with a 2xx within 8 seconds, we retry after 1 minute, 5 minutes, 30 minutes, 2, 5 and 10 hours, then daily for 2 days. Every retry carries the same event id, so store it and ignore repeats. You can also resend any payment's webhook from the dashboard.
{
"id": "evt_...",
"object": "event",
"type": "checkout.session.completed",
"created": 1794810043,
"data": { "object": { /* the session object */ } }
}Every request carries a Swipe-Signature header: t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of t + "." + rawBody keyed with your signing secret (dashboard → Developers). Reject requests whose signature doesn't match or whose t is more than 5 minutes old.
import crypto from "node:crypto";
export function verify(rawBody, header, secret) {
const { t, v1 } = Object.fromEntries(header.split(",").map((kv) => kv.split("=")));
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}Fees and settlement
Swipe charges 1% per payment, paid by the merchant. The customer pays the price plus the Solana network fee. In the payment transaction, 99% of the price goes to your wallet's USDC account and 1% to Swipe. If the customer pays with a coin other than USDC, the swap is sized with slippage protection, and any small surplus stays in the customer's wallet as USDC.
Payments are final once confirmed. There are no chargebacks; to refund, send USDC back to payment.payer.
Errors
Errors return a non-2xx status with a body like {"error":{"message":"...","type":"invalid_request_error"}}. Types: authentication_error (401), invalid_request_error (400/404), rate_limit_error (429).