Skip to main content

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.

StatusMeaningMerchant action
openAwaiting payment, with none yet detected on chainRetrieve server-side; allow the payer to resume before expiry
processingPayment detected on chain, awaiting the selected confirmation levelShow confirmation progress without asking for another payment
succeededPayment reached the selected transaction_speed confirmation requirement before expiry or closureVerify order, amount, currency and exceptions before idempotent fulfillment
failedTerms were unmet before expiry or explicit closureHandle 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_speedSuccess threshold
highSuccessful execution and block inclusion
mediumNative safe confirmation
lowNative 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_statusMeaningApplication action
nullNo current exception, including before paymentStill inspect primary status
paidOverExtra, unrefunded funds, including duplicate/late paymentsPreserve the original payment and handle extra funds through after-sales processes
paidPartialOriginally accepted normal funds no longer meet requirementsReview 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.