Skip to main content
The Events API provides an immutable log of all events fired for your account, including every payment session state change. Events are the same objects delivered to your webhook endpoints — querying this API lets you replay missed deliveries, build audit logs, or debug handler issues without waiting for another payment. Events are retained for 90 days. For real-time delivery, register a webhook endpoint instead.

​
The Event object

​
id
string
Unique identifier for the event, e.g. "evt_01HXYZ".
​
object
string
Always "event".
​
type
string
The event type string describing what happened, e.g. "session.paid". Possible values:
TypeDescription
session.pendingA new checkout session was created.
session.detectedA blockchain transaction has been seen in the mempool.
session.paidPayment was confirmed in full.
session.underpaidA confirmed transaction arrived for less than the required amount.
session.overpaidA confirmed transaction arrived for more than the required amount.
session.expiredThe session TTL elapsed before payment was received.
session.paid_latePayment arrived after the session expired.
session.failedAn unrecoverable processing error occurred.
​
livemode
boolean
true if the event was generated in live mode; false for test mode.
​
data
object
A snapshot of the full resource object at the moment the event was fired. For session.* events this is a CheckoutSession object.
​
createdAt
string
ISO 8601 timestamp of when the event was created.

​
GET /events

Returns a cursor-paginated list of events for your account, ordered by creation time, most recent first. Required scope: events:read

​
Query parameters

​
limit
integer
Number of results to return. Between 1 and 100. Defaults to 25.
​
starting_after
string
An event id used as a pagination cursor. Returns events created before this one.
​
type
string
Filter by event type, e.g. session.paid. Returns only events with this exact type string.
​
createdAfter
string
ISO 8601 datetime. Only return events created at or after this time. Useful for incremental syncs.

​
Example request

curl "https://your-domain.com/api/v1/events?type=session.paid&limit=10" \
  -H "Authorization: Bearer ck_test_YOUR_KEY"

// Single page
const { data, hasMore, nextCursor } = await client.events.list({
  type: "session.paid",
  limit: 25,
});

// Auto-paginate through all matching events
for await (const event of await client.events.list({
  type: "session.paid",
  autoPaginate: true,
})) {
  processEvent(event);
}

​
Example response 200

{
  "data": [
    {
      "id": "evt_01HXYZ",
      "object": "event",
      "type": "session.paid",
      "livemode": true,
      "data": {
        "id": "cs_01HABC",
        "object": "checkout_session",
        "status": "paid",
        "txHash": "0xdef456...",
        "paidAt": "2024-01-15T10:35:00.000Z"
      },
      "createdAt": "2024-01-15T10:35:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

​
GET /events/{id}

Retrieves a single event by its ID. Required scope: events:read

​
Path parameters

​
id
string
required
The ID of the event to retrieve, e.g. "evt_01HXYZ".

​
Example request

curl https://your-domain.com/api/v1/events/evt_01HXYZ \
  -H "Authorization: Bearer ck_test_YOUR_KEY"

const event = await client.events.retrieve("evt_01HXYZ");

​
Example response 200

{
  "id": "evt_01HXYZ",
  "object": "event",
  "type": "session.paid",
  "livemode": true,
  "data": {
    "id": "cs_01HABC",
    "object": "checkout_session",
    "status": "paid",
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "txHash": "0xdef456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef01",
    "paidAt": "2024-01-15T10:35:00.000Z",
    "fiat": { "amount": "149.99", "currency": "USD" },
    "amount": { "wei": "45230000000000000", "eth": "0.04523" }
  },
  "createdAt": "2024-01-15T10:35:00.000Z"
}

​
Common use cases

Order fulfillment reconciliation — Poll GET /events?type=session.paid&createdAfter=<last-sync-time> on a schedule to catch any payments your webhook handler may have missed. Audit logging — Stream all events into your data warehouse using autoPaginate: true on the SDK for a complete, immutable record of every transaction. Debugging webhook delivery — If a webhook delivery failed, retrieve the original event by ID and re-send the payload manually to your handler for testing.
Events are retained for 90 days from their createdAt timestamp. For longer-term storage, export events to your own database or data warehouse before they age out.