Payment statuses
A payment walks a predictable path from created to a terminal state. Map these to your own order states and reconcile against the matching webhook events.
Lifecycle
The status field follows the order below. Most statuses are in progress and will advance on their own; the rest are end states. The exact path depends on whether the payment is direct or routed.
- createdIn progress
The checkout session exists but no payment has been made yet. Moves on once the customer picks a pay asset and pays.
- pendingIn progress
Awaiting the customer's payment — Apa is waiting for them to sign and broadcast from their wallet. Moves on once the payment is detected.
- routingIn progress
A routed payment is being converted into your payout asset. Moves to settling.
- settlingIn progress
The routed conversion is delivering the converted funds to your payout wallet. Moves to paid.
- paidTerminal
Funds have landed in your payout wallet. Terminal success — safe to fulfil the order.
- failedTerminal
The payment could not complete, e.g. the route expired or the transaction reverted. Terminal; no funds moved to you.
- expiredTerminal
The customer did not pay within the checkout window. Terminal; no funds moved.
- refund_requiredTerminal
Funds arrived but a refund is owed to the customer (e.g. underpayment). The merchant settles it; Apa is non-custodial. Terminal until refunded.
- refundedTerminal
The merchant has refunded the customer and marked it done. Terminal; emits payment.refunded.
End states
Failed routes & returns
A direct payment either reaches paid or fails outright. A routed payment carries one extra safeguard: if the conversion cannot complete — no liquidity, a reverted leg or an expired quote — the route is built to return the funds to the customer's source wallet, and the payment ends failed.
Cases that need a person in the loop resolve to refund_required instead: funds arrived but could not be settled to your payout asset, so the customer is owed a manual refund. Either way Apa is non-custodial and never holds the funds — it surfaces the outcome through the payment.failed or payment.refund_required webhook and on your dashboard.