Payment states, confirmation and fund exceptions
Checkout is a collection session. HTTP success, chain inclusion, Checkout success, order fulfillment and completed fund collection are separate facts.
| Status | Meaning | Merchant action |
|---|---|---|
open | Awaiting payment, with none yet detected on chain | Retrieve server-side; allow the payer to resume before expiry |
processing | Payment detected on chain, awaiting the selected confirmation level | Show confirmation progress without asking for another payment |
succeeded | Payment reached the selected transaction_speed confirmation requirement before expiry or closure | Verify order, amount, currency and exceptions before idempotent fulfillment |
failed | Terms were unmet before expiry or explicit closure | Handle failure_reason; late funds do not make the failed session successful |
succeeded and failed are terminal and do not flip after refunds, late funds or exception changes. Closing a page or returning to the merchant does not close the Checkout; failure_reason=closed records merchant-requested closure.
Confirmation speed
transaction_speed | Success threshold |
|---|---|
high | Successful execution and block inclusion |
medium | Native safe confirmation |
low | Native finalized confirmation; default |
Faster recognition carries more risk that later funds no longer satisfy requirements. Expiry includes confirmation waiting time: included funds can still miss the selected threshold before cutoff. Match the policy to reversibility of fulfillment; elapsed seconds do not establish a native level.
Fund exceptions
exception_status | Meaning | Application action |
|---|---|---|
null | No current exception, including before payment | Still inspect primary status |
paidOver | Extra, unrefunded funds, including duplicate/late payments | Preserve the original payment and handle extra funds through after-sales processes |
paidPartial | Originally accepted normal funds no longer meet requirements | Review fulfillment under business policy; retrieve updates without substituting other funds |
paidPartial takes priority when both conditions exist. Ordinary after-sales refunds do not themselves create a shortage exception. Clearing an exception does not prove merchant support work is complete.
Closing, retrying and new sessions
Close an open Checkout with the close operation and a separate idempotency key. A successful session cannot be closed into an unpaid one. Creating a new session after termination is a new business decision, not an unconditional retry after network timeout.
Deduplicate fulfillment at the order level across all its Checkouts. Query failures do not change payment facts. Use server retrieval for recovery and check availability before depending on Webhooks or payment details.