Understanding Payment Statuses

Payment Statuses

Status	Description	Final?
`INITIATION`	Payment created, waiting for payer action	No
`CHECKOUT_PENDING`	Payer is preparing the payment	No
`CHECKOUT_SUCCESS`	Payer has successfully paid	No
`PAYMENT_RECEIVED`	Funds received by the banking provider	No
`PAYMENT_SUCCESS`	Funds received in the user's account	Yes (success)
`PAYMENT_FAILED`	Payment failed	Yes (failure)
`PARTIAL_REFUNDED`	Part of the payment has been refunded	No (can refund more)
`FULLY_REFUNDED`	Full refund completed	Yes
`REFUND_PENDING`	Refund is being processed	No
`REFUND_FAILED`	Refund failed	Yes (failure)

Status Flow

INITIATION → CHECKOUT_PENDING → CHECKOUT_SUCCESS → PAYMENT_RECEIVED → PAYMENT_SUCCESS
                                                                     ↘ PAYMENT_FAILED

PAYMENT_SUCCESS → REFUND_PENDING → FULLY_REFUNDED
                                 → PARTIAL_REFUNDED

Happy Path

INITIATION → CHECKOUT_PENDING → CHECKOUT_SUCCESS → PAYMENT_RECEIVED → PAYMENT_SUCCESS

Failed Payment

INITIATION → CHECKOUT_PENDING → CHECKOUT_SUCCESS → PAYMENT_FAILED

Refund

PAYMENT_SUCCESS → REFUND_PENDING → FULLY_REFUNDED (full) or PARTIAL_REFUNDED (partial)

In the API

When you query a payment via the API, the status field contains the current status:

{
  "id": "pay_abc123",
  "status": "PAYMENT_SUCCESS",
  "timeline": [
    { "status": "INITIATION", "timestamp": "2025-01-15T10:30:00.000Z" },
    { "status": "CHECKOUT_SUCCESS", "timestamp": "2025-01-15T10:31:00.000Z" },
    { "status": "PAYMENT_SUCCESS", "timestamp": "2025-01-15T10:31:05.000Z" }
  ]
}

The timeline array shows every status transition with timestamps. Duplicate transitions are collapsed — you will see at most one entry per status.

In Webhooks

When a payment status changes, a payment_status_updated webhook event is fired. The payload is the same shape as the getPayment API response. Use this to:

Update your database when a payment reaches PAYMENT_SUCCESS
Notify your customer of a PAYMENT_FAILED event
Trigger fulfillment when a payment reaches CHECKOUT_SUCCESS

Expected Timing Between Statuses

Transition	Expected Delay
`CHECKOUT_SUCCESS` → `PAYMENT_RECEIVED`	3–5 business days (depends on currency)
`PAYMENT_RECEIVED` → `PAYMENT_SUCCESS`	~1 hour (can be faster or slower)

PAYMENT_FAILED is rare for one-time payments. It mainly results from failed recurring subscription invoice charges.

Status Behavior by Payment Method

Behavior	Open Banking	Card Payment
INITIATION → CHECKOUT_SUCCESS	After bank transfer initiated	After card charge authorized
CHECKOUT_SUCCESS → PAYMENT_RECEIVED	3–5 business days	3–5 business days
PAYMENT_RECEIVED → PAYMENT_SUCCESS	~1 hour	~1 hour
Can FAIL after CHECKOUT_SUCCESS	Rare	Possible (e.g., fraud check)
3DS required	No	Sometimes