API docs
Create a checkout, send your customer to it, get a signed webhook when Solana says it is paid.
Overview
REST over HTTPS, JSON in and out. Base address: https://blushpay.fun/api/v1. Amounts are US dollars as decimal strings with at most two decimals ("24.00"), settled in USDC. The smallest payment is $1.00, the largest $50,000.00. The fee is 1% of the amount, taken in USDC inside the payment.
Authentication
Make a secret key in your dashboard under Developers. It is shown once; Blushpay keeps only its SHA-256, so it cannot show it again. Send it on every request:
Authorization: Bearer bp_live_...Keep it on your server. Never put it in a web page or an app. Revoke a key in the dashboard the moment it leaks.
Create a checkout session
POST /api/v1/checkout_sessions
Authorization: Bearer bp_live_...
Idempotency-Key: order-1042
Content-Type: application/json
{
"amount": "24.00",
"description": "Order 1042",
"success_url": "https://yourshop.com/thanks?order=1042",
"metadata": { "order": "1042" },
"expires_in_minutes": 60
}| Field | Required | What it does |
|---|---|---|
amount | yes | The price in US dollars, “1.00” to “50000.00”. |
description | no | Shown to the buyer and on the receipt. Up to 500 characters. |
success_url | no | Where the buyer is sent after the payment is finalized. |
metadata | no | Up to 20 keys of your own, returned on the session and in webhooks. |
expires_in_minutes | no | 5 to 10,080. Default 1440. |
Answer (201):
{
"id": "cs_...",
"object": "checkout.session",
"status": "open",
"amount": "24.00",
"currency": "USDC",
"url": "https://blushpay.fun/c/cs_...",
"reference": "8tD2...",
"expires_at": "2026-11-18T10:00:00.000Z",
"payment": null
}Send your customer to url. Unknown fields are refused, so a typo never passes silently.
Retrieve and list
GET /api/v1/checkout_sessions/cs_...
GET /api/v1/checkout_sessions?limit=25&status=paid&starting_after=cs_...Status is open, paid or expired. A paid session carries payment: the transaction signature, the payer, the coin they paid with, what you received, the fee, the slot and a Solscan link. Lists come newest first with has_more.
Idempotency
Send Idempotency-Key (8 to 128 letters, digits, _ . : -) when you create a session. Repeating the same request with the same key returns the first answer again (header idempotent-replayed: true), so a retry never makes two checkouts. The same key with a different body is refused with 409.
The checkout page
The buyer connects Phantom, Solflare or Backpack, sees what each coin in their wallet would cost, picks one and signs once. The price is held for 60 seconds. The transaction is simulated on mainnet before it is shown, and is only offered if you receive exactly your amount. The session becomes paid when Blushpay reads it back from Solana, finalized; never on the browser's word.
Webhooks
Set a webhook address in the dashboard (https only). When a session is paid, Blushpay POSTs:
POST https://yourshop.com/blushpay-webhook
Content-Type: application/json
Blushpay-Event-Id: evt_...
Blushpay-Signature: t=1795000000,v1=5f2c...
{
"id": "evt_...",
"type": "checkout.session.paid",
"created": 1795000000,
"data": { "id": "cs_...", "status": "paid", "amount": "24.00", "payment": { "signature": "...", "merchant_amount": "23.76", "fee": "0.24" } }
}Answer with any 2xx within 10 seconds. Anything else is retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h, then marked failed. Every attempt is in your delivery log, and you can send one again from the dashboard. The same event id is sent on every attempt: store the ids you have handled and ignore repeats. A test.ping event can be sent from the dashboard to check your endpoint.
Verify a webhook
Check the signature with your webhook signing secret (dashboard, Developers) before you trust a webhook. Use the raw body exactly as received.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verify(secret, rawBody, header, toleranceS = 300) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const t = Number(parts.t), now = Math.floor(Date.now() / 1000);
if (!t || !parts.v1 || Math.abs(now - t) > toleranceS) return false;
const want = createHmac("sha256", secret).update(t + "." + rawBody).digest();
const got = Buffer.from(parts.v1, "hex");
return got.length === want.length && timingSafeEqual(want, got);
}Errors
Every error is JSON: { "error": "plain words", "field": "amount" }.
| Status | Meaning |
|---|---|
| 400 | The request is not valid (the field is named). |
| 401 | No key, or the key is unknown or revoked. |
| 404 | No such session in your store. |
| 409 | An Idempotency-Key reused with a different body. |
| 429 | Too many requests; wait retry_after seconds. |
| 503 | Payments are paused for a moment. |
Limits
300 requests a minute per key. Sessions: $1.00 to $50,000.00. Coins refused at checkout: tokens with a transfer fee, a transfer hook, a permanent delegate or that cannot be transferred, and coins with no route to USDC.
Payment links (no code)
In the dashboard, make a link with a fixed price or one where the buyer types the amount (with a smallest and largest), single-use or reusable, with an end date if you like. Each link has a QR code for the counter. Payments from links arrive in the same list and send the same webhooks.
Questions? Read how it works and the risks.