Transaction statuses
A transaction has three independent fields that together describe its state and outcome: status, result, and type. PaymentsAI also exposes a combinedStatus field that merges status and result into a single value for display.
Status: Where the transaction is
| Status | Meaning |
|---|---|
waiting | The transaction is waiting for an action to complete (for example, an offsite 3DS step). |
sending | The transaction is being sent to the gateway. |
offsite | The customer has been redirected offsite (for example, to a 3DS challenge or an alternative payment method). |
completed | The transaction completed and funds were captured. |
partially-refunded | Part of the captured amount has been refunded. |
refunded | The full captured amount has been refunded. |
voided | An authorization was released without capture. |
disputed | A chargeback has been opened against the transaction. |
timeout | The gateway did not respond in time. |
not-sent | The transaction was never sent to the gateway. |
suspended | The transaction has been suspended. |
Result: How the transaction turned out
| Result | Meaning |
|---|---|
approved | The gateway approved the transaction. |
declined | The gateway declined the transaction. |
canceled | The transaction was canceled. |
abandoned | The customer abandoned an offsite step without completing it. |
unknown | The outcome is not yet known. |
The declined result is generic. When result is declined, the API response indicates that the transaction was declined and includes any available avsResponse, cvvResponse, and data3ds. It does not return the gateway's raw issuer decline code. The specific decline reason (gateway response code and message) is available in the PAI panel instead of the API response.
For customer-facing UI, show a generic "payment declined, try another card" message. Drive programmatic logic using the result field, and diagnose the specific reason inside the panel.
Type: What kind of transaction it is
| Type | Meaning |
|---|---|
sale | Authorize and capture in one step. |
authorize | Reserve funds without capturing. |
capture | Capture of a prior authorization. |
refund | A refund of a captured transaction. |
credit | A credit to the customer. |
void | A release of a prior authorization without capture. |
3ds-authentication | A 3D Secure authentication step. |
You create only sale and authorize via POST /transactions. The other types appear on transactions that PaymentsAI generates as a result of other actions. For example, refund appears when you call the refund endpoint, and void appears when an authorization is released. The public API does not currently expose an endpoint to create a void transaction directly. See Transactions.
Combined status
The combinedStatus field collapses status and the abandoned value from result into one field, which provides a convenient way to populate a single status column in your UI. It can return any value of status listed above, plus abandoned: completed, refunded, partially-refunded, voided, waiting, timeout, not-sent, disputed, sending, offsite, suspended, or abandoned.
Lifecycle
A transaction starts either as an authorization (type: authorize, status: waiting) or as a direct sale (type: sale, status: completed). From there, it can be refunded, disputed, or remain terminal.
| From | To | Trigger |
|---|---|---|
| start | waiting | POST /transactions with type: "authorize" |
| start | completed | POST /transactions with type: "sale" |
waiting | completed | POST /transactions with type: "sale" (using the same paymentInstrumentId) to capture the authorization. See Authorize and capture. |
completed | partially-refunded | POST /transactions/{id}/refund with amount < refundableAmount |
completed | refunded | POST /transactions/{id}/refund with no body or amount = refundableAmount |
partially-refunded | partially-refunded | Another partial refund action. |
partially-refunded | refunded | Final refund covering the remaining refundableAmount. |
completed | disputed | Cardholder opens a chargeback through their bank. See Dispute process. |
The refunded, voided, and disputed statuses are terminal from the API perspective. The refundableAmount becomes 0, and further refund calls return a 409 Conflict error. The waiting, sending, offsite, timeout, not-sent, and suspended statuses are transient. They resolve to one of the terminal states above or remain unchanged if the gateway fails to respond.