Reporting a result
What Localoy does with each answer, and the three refusals worth designing around.
| You send | What happens to the order |
|---|---|
SUCCEEDED | Marked paid. An activity booking or dining reservation is ALSO confirmed, if the partner set confirmation to automatic — that is the moment automatic confirmation describes. amountMinor must match what the session quoted. |
FAILED | Recorded as a failed attempt, with your failureReason kept against it. Not terminal: the same session can still succeed if the customer tries again. |
PROCESSING | Nothing. It marks the interval where the customer has left your page but the money has not landed — real for an async gateway, and otherwise indistinguishable from an abandoned checkout. |
CANCELLED | Nothing, and it is terminal. A payment arriving after it is a 409, because it means your own bookkeeping disagrees with itself. |
A refused result still took money
payment_amount_mismatch means you reported a figure the session did not quote, and the order was NOT marked paid. payment_subject_not_chargeable means it had already been settled another way — paid at the counter, or refunded. Both are recorded in your Payment Log with what you sent, because in both cases your gateway may hold money Localoy will not put against the order. Neither is safe to retry blindly.
Send an Idempotency-Key. Gateways retry callbacks, and a repeat carrying a key we have seen answers 200 with the session as it stands and replayed: true — rather than settling a second time, which for a ticket order would mean a second set of admissions.
A session expires after the window you configured, and a lapsed one reads EXPIRED. It still accepts SUCCEEDED: our clock running out is not a reason to deny a payment that happened. The session comes back flagged settledAfterExpiry, which is your signal that the window is shorter than your checkout actually takes.