Release 2026-01-07

This release improves observability across payment lifecycles by introducing a complete events timeline for both payments and checkouts, while also ensuring more reliable handling of payment expirations.

With the new timeline experience, platforms can more easily understand payment flows and key milestones throughout the buyer journey, enabling faster diagnosis, clearer insights, and improved operational visibility. Additionally, action required payments that are not completed within the expected timeframe will now expire, providing a more predictable and reliable lifecycle management.

Events timeline

The Events timeline has been updated for both Payments and Checkouts, giving platforms full visibility into every step of the buyer journey. The Events timeline tab in the details view presents an ordered, last-to-first sequence of events, making it easier to understand how a payment progressed and where actions, issues or delays occurred.

This provides a complete and chronological audit trail, enabling richer operational insights, more effective troubleshooting, and improved analytics for individual payments, while reinforcing transparency across the entire payment process.

Checkouts timeline

Payments timeline

Event node in the API

The GET /checkouts/{id} and GET /payments/{id} endpoints have been enhanced to include an events array, exposing a time-ordered sequence of events. Each entry represents a significant milestone in the checkout or payment lifecycle and directly maps to the events shown in the Events timeline in the Dashboard.

Each event is represented as a discriminated union keyed by the type field. All event objects include the base properties index, type, and occurred_at, along with additional event-specific fields when applicable (for example, amount and currency for initiated events). This structure provides a consistent and extensible way to handle payment lifecycle events.

GET api.getpaid.io/v2/payments/pay_4a4m2pjycdb1jbj68h1rvk9kcz

{
  "id": "pay_4a4m2pjycdb1jbj68h1rvk9kcz",
  [...]
  "events": [
    {
      "index": 3,
      "type": "captured",
      "occurred_at": "2025-12-31T12:34:56Z",
      "amount": 1000,
      "currency": "EUR"
    },
    {
      "index": 2,
      "type": "authorized",
      "occurred_at": "2025-12-31T12:33:10Z",
      "amount": 1000,
      "currency": "EUR"
    },
    [...]
  ]
}

GET api.getpaid.io/v2/checkouts/chk_4a4m2pjycdb1jbj68h1rvk9kcz

{
  "id": "chk_4a4m2pjycdb1jbj68h1rvk9kcz",
  [...]
  "events": [
    {
      "index": 1,
      "type": "payment_initiated",
      "occurred_at": "2025-12-31T11:00:00Z",
      "payment": {
        "id": "pay_4a4m2pjycdb1jbj68h1rvk9kcz",
        "method": { "type": "card" }
      }
    },
    {
      "index": 0,
      "type": "initiated",
      "occurred_at": "2025-12-31T10:59:50Z",
      "amount": 1000,
      "currency": "EUR"
    }
  ]
}

Payment action required expiration

Payments in the action_required status that do not complete the required steps within the defined timeframe (as indicated by estimated_update_before) will now automatically transition to the failed status with an expired reason. This ensures stalled payment attempts are resolved deterministically and that the appropriate webhooks are emitted.

As a result, platforms benefit from more predictable payment lifecycles, clearer event handling, and improved operational reliability. This also unblocks the checkout flow, allowing additional attempts to proceed when applicable and ensuring downstream systems can respond consistently to payment state changes.