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": "sess_cmh3lmkw50000xv8d",
  "merchantId": "m_xyz",
  "amount": "50000000",
  "currency": "USDC",
  "status": "pending",
  "checkoutUrl": "https://strimz.finance/pay/sess_cmh3lmkw50000xv8d",
  "expiresAt": "2026-04-30T18:00:00Z",
  "createdAt": "2026-04-29T18:00:00Z",
  "metadata": { "orderId": "abc-123" }
}

Retrieve

GET /v1/payment-sessions/{id}

List

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

Filters: status, customerId, createdAfter, createdBefore.

Cancel

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

Cancels a pending session. Already-confirmed sessions can't be cancelled. Refund the payment instead.

Status lifecycle

created  →  pending  →  confirmed  →  refunded
                    ↘
                     cancelled / expired

Sessions expire 24 hours after creation by default. expiresAt is set when you create the session.

Webhook events

Event	Fires when
`payment.created`	The session row was created
`payment.completed`	The on-chain transaction confirmed
`payment.failed`	The session expired or was cancelled