Checkout Sessions

Server-side checkout session management for programmatic payment flows

Checkout sessions represent an individual payment attempt. You can create sessions server-side to generate unique checkout URLs for each customer, pre-fill payment details, and track conversions with your own reference IDs.

Info

Checkout sessions expire after 30 minutes by default. Use the expires_in parameter to customize the expiration window (minimum 5 minutes, maximum 24 hours).

The Checkout Session object

idstring

Unique identifier for the checkout session (e.g., cs_abc123).

urlstring

The checkout URL to redirect the customer to.

statusstring

Current status of the session. One of: open, processing, completed, expired, failed.

payment_link_idstring | null

Associated payment link ID, if the session was created from a payment link.

product_idstring | null

Associated product ID.

token_addressstring

Contract address of the token to receive.

chain_idnumber

Chain ID where you want to receive payment.

recipient_addressstring

Wallet address that receives the payment.

amountstring

Payment amount in the token's smallest unit.

amount_usdstring | null

USD equivalent at the time of session creation.

success_urlstring | null

URL the customer is redirected to after successful payment. Supports template variables.

cancel_urlstring | null

URL the customer is redirected to if they cancel.

client_reference_idstring | null

Your internal reference ID for this session.

metadataobject | null

Arbitrary key-value pairs passed through to webhooks and the transaction.

customer_emailstring | null

Email address of the customer. Encrypted at rest, included in webhook payloads.

customer_namestring | null

Name of the customer. Encrypted at rest, included in webhook payloads.

payer_addressstring | null

Wallet address of the payer (populated after connection).

tx_hashstring | null

On-chain transaction hash (populated after submission).

customer_idstring | null

Associated customer ID (populated after payment).

form_dataobject | null

Custom form data submitted by the customer.

shipping_addressobject | null

Shipping address provided by the customer.

utm_sourcestring | null

UTM source parameter for attribution.

utm_mediumstring | null

UTM medium parameter for attribution.

utm_campaignstring | null

UTM campaign parameter for attribution.

expires_atstring

ISO 8601 expiration timestamp.

created_atstring

ISO 8601 creation timestamp.

completed_atstring | null

ISO 8601 completion timestamp.

Session statuses

Status	Description
`open`	Session is active and waiting for the customer to pay.
`processing`	Customer has initiated payment; transaction is being processed on-chain.
`completed`	Payment confirmed and received by the recipient.
`expired`	Session expired before the customer completed payment.
`failed`	Payment failed due to on-chain error or timeout.

URL template variables

The success_url and cancel_url fields support template variables that are replaced with actual values when the customer is redirected:

Variable	Description	Example
`{SESSION_ID}`	The checkout session ID	`cs_abc123`

Tip

Use template variables to look up session details on your server after redirect: https://example.com/success?session_id={SESSION_ID}

List checkout sessions

Retrieve a paginated list of checkout sessions.

statusstringquery

Filter by session status: open, processing, completed, expired, failed.

payment_link_idstringquery

Filter by payment link ID.

pagenumberquerydefault: 1

Page number for pagination.

limitnumberquerydefault: 20

Number of results per page (max 100).

curl -X GET "https://platform-api.anyspend.com/api/v1/checkout-sessions?status=completed&page=1&limit=20" \
  -H "Authorization: Bearer asp_xxx"

import { AnySpend } from "@b3dotfun/sdk";

const anyspend = new AnySpend(process.env.ANYSPEND_API_KEY!);

const { data, pagination } = await anyspend.checkoutSessions.list({
  status: "completed",
  page: 1,
  limit: 20,
});

json
{  "data": [    {      "id": "cs_abc123",      "url": "https://anyspend.com/pay/s/cs_abc123",      "status": "completed",      "payment_link_id": "pl_abc123",      "product_id": null,      "token_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",      "chain_id": 1,      "recipient_address": "0x1234567890abcdef1234567890abcdef12345678",      "amount": "50000000",      "amount_usd": "50.00",      "success_url": "https://example.com/success?session_id=cs_abc123",      "cancel_url": "https://example.com/cancel",      "client_reference_id": "order_12345",      "metadata": {        "order_id": "12345"      },      "payer_address": "0xaabb1234ccdd5678eeff9900aabb1234ccdd5678",      "tx_hash": "0x9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e",      "customer_id": "cust_abc123",      "form_data": null,      "shipping_address": null,      "utm_source": "twitter",      "utm_medium": "social",      "utm_campaign": "launch_feb_2026",      "expires_at": "2026-02-25T08:45:00Z",      "created_at": "2026-02-25T08:15:00Z",      "completed_at": "2026-02-25T08:16:30Z"    }  ],  "pagination": {    "page": 1,    "limit": 20,    "total": 340,    "total_pages": 17,    "has_more": true  }}

Create a checkout session

Create a server-side checkout session with a unique payment URL. Use this for programmatic integrations where you control the checkout flow from your backend.

payment_link_idstringbody

Create the session from an existing payment link. This inherits the link's configuration. Either payment_link_id or the manual fields (token_address, chain_id, recipient_address, amount) are required.

token_addressstringbody

Contract address of the token to receive. Required if payment_link_id is not provided.

chain_idnumberbody

Chain ID where you want to receive payment. Required if payment_link_id is not provided.

recipient_addressstringbody

Wallet address that receives the payment. Required if payment_link_id is not provided.

amountstringbody

Payment amount in the token's smallest unit. Required if payment_link_id is not provided.

product_idstringbody

Associate the session with a product.

success_urlstringbody

URL to redirect the customer to after successful payment. Supports {SESSION_ID} template variable.

cancel_urlstringbody

URL to redirect the customer to if they cancel.

client_reference_idstringbody

Your internal reference ID (e.g., order ID). Maximum 200 characters.

metadataobjectbody

Arbitrary key-value pairs passed through to webhooks and the resulting transaction. Up to 50 keys, 500 character values.

customer_emailstringbody

Customer email address. Encrypted at rest and included in webhook payloads for order fulfillment.

customer_namestringbody

Customer name. Encrypted at rest and included in webhook payloads for order fulfillment.

expires_innumberbodydefault: 1800

Session expiration time in seconds. Minimum 300 (5 minutes), maximum 86400 (24 hours). Default: 1800 (30 minutes).

utm_sourcestringbody

UTM source for attribution tracking.

utm_mediumstringbody

UTM medium for attribution tracking.

utm_campaignstringbody

UTM campaign for attribution tracking.

# Create from a payment link
curl -X POST "https://platform-api.anyspend.com/api/v1/checkout-sessions" \
  -H "Authorization: Bearer asp_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_link_id": "pl_abc123",
    "success_url": "https://example.com/success?session_id={SESSION_ID}",
    "cancel_url": "https://example.com/cancel",
    "client_reference_id": "order_12345",
    "metadata": {
      "order_id": "12345"
    },
    "customer_email": "alice@example.com",
    "customer_name": "Alice Smith",
    "expires_in": 3600
  }'

# Create with manual configuration
curl -X POST "https://platform-api.anyspend.com/api/v1/checkout-sessions" \
  -H "Authorization: Bearer asp_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "token_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "chain_id": 1,
    "recipient_address": "0x1234567890abcdef1234567890abcdef12345678",
    "amount": "25000000",
    "success_url": "https://example.com/success?session_id={SESSION_ID}",
    "cancel_url": "https://example.com/cancel",
    "client_reference_id": "inv_67890",
    "utm_source": "email",
    "utm_medium": "newsletter",
    "utm_campaign": "february_promo"
  }'

// Create from a payment link
const session = await anyspend.checkoutSessions.create({
  paymentLinkId: "pl_abc123",
  successUrl: "https://example.com/success?session_id={SESSION_ID}",
  cancelUrl: "https://example.com/cancel",
  clientReferenceId: "order_12345",
  metadata: {
    order_id: "12345",
    user_email: "alice@example.com",
  },
  expiresIn: 3600,
});

// Redirect the customer
console.log(session.url);
// => "https://anyspend.com/pay/s/cs_newSession123"

// Create with manual configuration
const manualSession = await anyspend.checkoutSessions.create({
  tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  chainId: 1,
  recipientAddress: "0x1234567890abcdef1234567890abcdef12345678",
  amount: "25000000",
  successUrl: "https://example.com/success?session_id={SESSION_ID}",
  cancelUrl: "https://example.com/cancel",
  clientReferenceId: "inv_67890",
});

json
{  "id": "cs_newSession123",  "url": "https://anyspend.com/pay/s/cs_newSession123",  "status": "open",  "payment_link_id": "pl_abc123",  "product_id": null,  "token_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",  "chain_id": 1,  "recipient_address": "0x1234567890abcdef1234567890abcdef12345678",  "amount": "50000000",  "amount_usd": "50.00",  "success_url": "https://example.com/success?session_id={SESSION_ID}",  "cancel_url": "https://example.com/cancel",  "client_reference_id": "order_12345",  "metadata": {    "order_id": "12345",    "user_email": "alice@example.com"  },  "payer_address": null,  "tx_hash": null,  "customer_id": null,  "form_data": null,  "shipping_address": null,  "utm_source": null,  "utm_medium": null,  "utm_campaign": null,  "expires_at": "2026-02-27T11:30:00Z",  "created_at": "2026-02-27T10:30:00Z",  "completed_at": null}

Retrieve a checkout session

idstringrequiredpath

The checkout session ID (e.g., cs_abc123).

Tip

Use this endpoint in your success_url handler to verify payment status and retrieve transaction details after the customer is redirected back to your site.

curl -X GET "https://platform-api.anyspend.com/api/v1/checkout-sessions/cs_abc123" \
  -H "Authorization: Bearer asp_xxx"

const session = await anyspend.checkoutSessions.retrieve("cs_abc123");

if (session.status === "completed") {
  // Payment was successful
  console.log("Transaction hash:", session.tx_hash);
  console.log("Payer:", session.payer_address);
}

Returns the full Checkout Session object.

Expire a checkout session

Manually expire an open checkout session. This is useful when the underlying order is cancelled or the payment is no longer needed.

idstringrequiredpath

The checkout session ID.

Warning

Only sessions with status: "open" can be expired. Attempting to expire a session in any other status will return a 400 Bad Request error.

curl -X POST "https://platform-api.anyspend.com/api/v1/checkout-sessions/cs_abc123/expire" \
  -H "Authorization: Bearer asp_xxx"

const expired = await anyspend.checkoutSessions.expire("cs_abc123");
console.log(expired.status); // => "expired"

json
{  "id": "cs_abc123",  "url": "https://anyspend.com/pay/s/cs_abc123",  "status": "expired",  "payment_link_id": "pl_abc123",  "product_id": null,  "token_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",  "chain_id": 1,  "recipient_address": "0x1234567890abcdef1234567890abcdef12345678",  "amount": "50000000",  "amount_usd": "50.00",  "success_url": "https://example.com/success?session_id=cs_abc123",  "cancel_url": "https://example.com/cancel",  "client_reference_id": "order_12345",  "metadata": {    "order_id": "12345",    "user_email": "alice@example.com"  },  "payer_address": null,  "tx_hash": null,  "customer_id": null,  "form_data": null,  "shipping_address": null,  "utm_source": null,  "utm_medium": null,  "utm_campaign": null,  "expires_at": "2026-02-27T10:35:00Z",  "created_at": "2026-02-27T10:30:00Z",  "completed_at": null}

Common patterns

Server-side checkout flow

A typical server-side integration creates a checkout session on your backend and redirects the customer to the session URL:

typescript
// 1. Your server creates a sessionapp.post("/create-checkout", async (req, res) => {  const session = await anyspend.checkoutSessions.create({    paymentLinkId: "pl_abc123",    successUrl: "https://yoursite.com/success?session_id={SESSION_ID}",    cancelUrl: "https://yoursite.com/cart",    clientReferenceId: req.body.orderId,    metadata: {      user_id: req.user.id,    },    expiresIn: 1800, // 30 minutes  });  // 2. Redirect customer to pay  res.redirect(303, session.url);});// 3. Handle the redirect after paymentapp.get("/success", async (req, res) => {  const session = await anyspend.checkoutSessions.retrieve(    req.query.session_id  );  if (session.status === "completed") {    // Fulfill the order    await fulfillOrder(session.client_reference_id, {      txHash: session.tx_hash,      payer: session.payer_address,    });  }  res.render("success", { session });});

Warning

Always verify the session status server-side after redirect. Do not rely solely on the redirect to confirm payment -- use webhooks for reliable payment confirmation.

Polling for session completion

If you prefer polling over webhooks, you can check the session status periodically:

typescript
async function waitForPayment(sessionId: string, timeoutMs = 300000) {  const startTime = Date.now();  while (Date.now() - startTime < timeoutMs) {    const session = await anyspend.checkoutSessions.retrieve(sessionId);    if (session.status === "completed") {      return session;    }    if (session.status === "expired" || session.status === "failed") {      throw new Error(`Session ${session.status}: ${sessionId}`);    }    // Wait 3 seconds before polling again    await new Promise((resolve) => setTimeout(resolve, 3000));  }  throw new Error(`Timeout waiting for payment: ${sessionId}`);}

Tip

For production use, we strongly recommend using webhooks instead of polling. Webhooks provide real-time notifications and do not require keeping a connection open.

Was this page helpful?

Previous Transactions

Next Webhooks