Payment sessions

A PaymentSession is everything needed to render a hosted checkout for a single payment. Created server-side, paid by the customer in their wallet, confirmed by the indexer.

Create

POST /v1/payment-sessions

{
  "amount": "50000000",
  "currency": "USDC",
  "description": "Pro plan, August",
  "successUrl": "https://your-site.com/thanks",
  "cancelUrl": "https://your-site.com/cancelled",
  "metadata": { "orderId": "abc-123" }
}

Returns:

{
  "id": "cmq4wck6a0002je6lfmb5bgjp",
  "merchantId": "cmq4w9t1x0000je6l3k2d8hzn",
  "amount": "50000000",
  "currency": "USDC",
  "status": "created",
  "checkoutUrl": "https://checkout.strimz.finance/pay/cmq4wck6a0002je6lfmb5bgjp",
  "expiresAt": "2026-04-29T18:30:00Z",
  "createdAt": "2026-04-29T18:00:00Z",
  "metadata": { "orderId": "abc-123" }
}

The response carries more fields than shown here, such as feeAmount, netAmount and payerWalletAddress.

Optional inputs: customer (walletAddress, email, externalRef), expiresInMinutes (default 30, max 1440) and metadata.

Retrieve

GET /v1/payment-sessions/{id}

List

GET /v1/payment-sessions?limit=50&status=confirmed&cursor=...

Filters: status, and customerId to list one customer's sessions. from and to limit the list to sessions created in a range. See List filters.

Cancel

POST /v1/payment-sessions/{id}/cancel

Cancels an open session (created or awaiting_payment). Any other status returns 403 session_invalid_state. A confirmed payment can't be cancelled; refund it instead.

POST /v1/payment-sessions/{id}/expire works the same way and moves the session to expired.

Status lifecycle

Statuses: created, awaiting_payment, submitted, confirmed, failed, expired, cancelled.

A new session is created. When the relayer broadcasts the payment it becomes submitted, and the indexer moves it to confirmed. An open session (created or awaiting_payment) can be cancelled or can expire.

Sessions expire 30 minutes after creation by default. Set expiresInMinutes to change it. When expiresAt passes, the scheduler moves an open session to expired.

Webhook events