Payment status transitions 🧶

In the PAYSTRAX Gateway system, each payment object — an authorisation, a transfer, and so on — evolves through a small set of status changes.

The status field in the response body tells you the outcome of an operation. Always read it before updating your system.

Status	Meaning
pending	Accepted and queued for the card network. Normal outcome for sales, payouts, funding, and refunds.
success	Confirmed by the network. Normal outcome for pre-auth authorisations and cancellations.
fail	Declined or errored. The body contains a failure object with code and reason.
unknown	Outcome indeterminate at response time. Treat as potentially in-flight; check status before retrying.

note

HTTP 201 Created only confirms the gateway received the request. The real outcome is in the status field of the response body.

Transition scenarios

unknown is excluded from the table below — it's an edge case, not astep in the normal lifecycle.

Flow	Status evolution	Notes
authorise	success or fail	Often synchronous.
transfer	pending → success or fail	Often asynchronous — expect pending first.
🧶authorise + Capture	success (authorisation) → success (capture)	Two objects; often asynchronous.
authorise + Cancel	success (authorisation) → fail (authorisation updated)	Cancelled before capture.
🧶transfer → Refund	success or fail (transfer updated)	Refunded fully or partially.

Authorisations are usually synchronous, but captures, cancels, and reversals can be asynchronous depending on the processor. Always confirm the final state via GET or webhook rather than assuming the initial response is final.