Lifecycle

Payment & Refund objects can have only 3 statuses: pending, success & canceled and only the pending status is muttable, i.e. once an object gets the success or canceled status it is guaranteed that it will not change again.

Because of the complexity of payments, objects also have a sub-status. Sub-statuses are always joined with their parent status with an underscore character.

For your first implementation, we advise you to focus on statuses only and to use sub-statuses for data analytics or specific gateway-specific operations / reconciliations once you have live transactions going through.

You can either listen for (sub-)statuses change from your webhooks or call the Payment Intent API to query up to date data on a given Payment Intent.

Lifecycle Chart

You can download it in PDF format to zoom in better.

Refund Statuses

Pending

All relevant sub-statuses to the pending status.

pending_created

The refund was just created. This can happen when you create it through the API or when we create one automatically to cancel a ghost payment.

pending_promise

The refund is a promise and we are not ready yet with a status. This can last minutes to hours depending on the gateway. We listen & poll the gateway continuously for updates.

pending_canceled_failure

We tried multiple times but could not create a refund with the gateway because of undocumented technical failure on their end. You will need to create a new reufnd or contact the gateway.

pending_timeout_potential_ghost

The refund timed-out, we could not cancel it with the gateway directly and you need to contact the gateway to manually cancel the refund promise.

Success

All relevant sub-statuses to the success status.

success

The refund was successfully completed.

success_manual

The refund was successfully completed manually on the gateways side and someone from your team (typically ops / finops) manually marked the transaction as successful through our dashboard.

success_timeout_manual

A refund that was potentially a ghost (previously `pending_timeout_potential_ghost`) was successfully completed by the gateway and someone from your team manually marked it as completed in our dashboard.

Canceled

All relevant sub-statuses to the canceled status.

canceled_rejected

The refund was rejected, potentially before reaching the gateway's API and you have received a human-readable error message related to this failure as part of the Refunds API response. These failures are expected and documented, they are not technical issues.

canceled_timeout_e2e

The refund timed-out without being successful.

canceled_timeout_e2e_manual

The refund was potentially a ghost (previously `pending_timeout_potential_ghost`) and the gateway informed your team that the refund was canceled. A member of your team manually marked the refund as such through our dashboard.

canceled_failure_manual

The refund previously failed with an undocumented technical error from the gateway's side and after your team enquired to them, they confirmed that the refund did not go through and updated its status through our dashboard accordingly.

Payment Statuses

Pending

All relevant sub-statuses to the pending status.

pending_created

The intent was just created.

pending_interacting

The end user has started to interact with the gateway, e.g. they attempted to login or they engaged in a way with the gateway. Certain gateways will argue this is the starting point to calculate the success rate of transactions and not `pending_created`.

pending_canceled_timeout

The intent timed out and is about to get canceled in the next 50-200ms.

pending_canceled_preflight_immutableOnly for: Payment Intents

Another Payment Intent that belongs to the same Checkout Intent as this Payment Intent has succeeded and this intent is about to be canceled in the next 10-20ms.

pending_preflight_potential_ghost

The intent status is unknown and we need it canceled. Your team must contact the gateway to make sure the transaction is canceled on their end.

pending_timeout_potential_ghost

The intent status is unknown and we need it canceled. Your team must contact the gateway to make sure the transaction is canceled on their end.

pending_canceled_timeout

The intent has timed out and is about to be confirmed canceled with the gateway's API within the next 10-500ms.

pending_timeout_ghost

This transaction is a ghost and we've attempted to automatically refund it, however the refund process failed.

pending_preflight_ghost

This transaction is a ghost and we've attempted to automatically refund it, however the refund process failed.

pending_timeout_refund_potential_ghost

This transaction is supposed to be refunded but the refund process is pending a manual confirmation from the gateway.

pending_preflight_refund_potential_ghost

This transaction is supposed to be refunded but the refund process is pending a manual confirmation from the gateway.

Success

All relevant sub-statuses to the success status.

success

The transaction was successful.

Canceled

All relevant sub-statuses to the canceled status.

canceled_user_ui

The user canceled the intent through the UI (e.g. by clicking on the X button).

canceled_rejected

The intent was rejected by the gateway for a specific, documented reason. E.g. the customers credit limit was too low for the purhcase.

canceled_failure

A technical error occured before an intent could have been created with the gateway.

canceled_timeout_e2e

The intent was successfully canceled because it timed out and is known to be canceled at the gateway's side (it's canceled end-to-end).

canceled_preflight_e2e

The intent was successfully canceled because another Payment Intent belonging to the same Checkout Intent was successful, and it is known to be canceled at the gateway's side (it's canceled end-to-end).

canceled_timeout_e2e_manual

The intent could not be canceled automatically with the gateway, a manual request from your team was made and the gateway confirmed that the intent was canceled on their side. Your team subsequently updated the status of this transaction through our dashboard.

canceled_preflight_e2e_manual

The intent could not be canceled automatically with the gateway, a manual request from your team was made and the gateway confirmed that the intent was canceled on their side. Your team subsequently updated the status of this transaction through our dashboard.

canceled_timeout_refund_e2e

This transaction was cancelled & refunded and the refund process worked smoothly.

canceled_preflight_refund_e2e

This transaction was cancelled & refunded and the refund process worked smoothly.

canceled_timeout_refund_e2e_manual

This transaction was cancelled & refunded but the refund process did not work as expected and a member of your team had to reach out to manually confirm the underlying refund of this transaction. Your team then updated the status through our dashboard.

canceled_preflight_refund_e2e_manual

This transaction was cancelled & refunded but the refund process did not work as expected and a member of your team had to reach out to manually confirm the underlying refund of this transaction. Your team then updated the status through our dashboard.