API ReferenceCheckout
Create a checkout session
Initiates a new checkout session for a payment link. The session tracks the full payment lifecycle from creation through on-chain confirmation.
Sessions expire after 30 minutes if no transaction hash is submitted. The
quoteToken must come from a prior call to the tax quote endpoint — it
contains the signed tax calculation.
This endpoint does not require authentication because it is called from the customer-facing checkout page.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://api.justusebag.xyz/api/checkout/session" \ -H "Content-Type: application/json" \ -d '{ "linkId": "d4e5f6a7-b8c9-4d0e-a1f2-b3c4d5e6f7a8", "quoteToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0YXgiLCJjYWxjIjoiY2FsY18xMjM0In0.abc123", "walletAddress": "0xCuStOmEr1234567890abCdEf1234567890aBcDeF", "walletType": "evm", "network": "base", "customer": { "name": "Alice Johnson", "email": "alice@example.com", "address": "123 Main St, San Francisco, CA 94105", "country": "US" }, "totalsSnapshot": { "subtotalCents": 2999, "taxCents": 262, "totalCents": 3261, "calculationId": "calc_7f8e9d0c1b2a3456" } }'{
"status": "success",
"data": {
"_id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
"paymentLinkId": "d4e5f6a7-b8c9-4d0e-a1f2-b3c4d5e6f7a8",
"walletAddress": "0xCuStOmEr1234567890abCdEf1234567890aBcDeF",
"walletType": "evm",
"network": "base",
"expectedAmount": 32.61,
"status": "payment_session_created",
"customer": {
"name": "Alice Johnson",
"email": "alice@example.com",
"address": "123 Main St, San Francisco, CA 94105",
"country": "US"
},
"expiresAt": "2026-03-01T10:30:00.000Z",
"createdAt": "2026-03-01T10:00:00.000Z"
}
}{
"status": "error",
"message": "amount: Amount must be a positive number up to 999,999,999.99; network: Invalid enum value",
"code": "BAD_REQUEST"
}{
"status": "error",
"message": "Not found",
"code": "NOT_FOUND"
}{
"status": "error",
"message": "Too many requests. Please slow down.",
"retryAfter": 10
}