Skip to main content
Version: Current guides

Handle late, excess and insufficient payments

Availability and principles​

Checkout retrieval currently exposes the main status and funds exception. Payment-level details and refunds remain pending confirmation. Without details, open an unresolved case rather than estimating refundable funds or promising an automatic refund.

The main status describes whether a session met payment conditions; exception_status describes funds issues. They are independent. Later funds, exceptions and refunds do not reverse succeeded or failed. A null exception does not prove payment.

Start an investigation​

  1. Pause additional automatic delivery or payment reminders for the order and locate all associated Checkout IDs.
  2. Query the original session from your server. Verify environment, amount, currency, main status, exception and failure reason, and record the query time.
  3. Check existing fulfillment, refunds and submitted funds transactions so another operator does not repeat them.
  4. If payment details are enabled, inspect actual payment items and refundable amounts. Otherwise, ask your verified contact to investigate missing details.
  5. Record the decision, owner and next review time. A payment screenshot helps locate a case but cannot establish payment or authorize a refund.

Act on the situation​

SituationInterpretation and action
Long-running processingAn on-chain payment was detected; keep checking confirmation rather than requesting another payment or declaring success after a fixed delay
Customer reports funds after failedCheck expiry or closure and late funds; preserve the failed main status and handle funds separately without automatic delivery or another charge
paidOverExtra funds remain unrefunded, possibly from duplicate or late payments; decide ordinary order fulfillment under your business policy and handle the excess separately
paidPartialPreviously recognized normal payment no longer meets funds requirements; pause or review unfinished fulfillment and keep querying, without substituting another receipt yourself
Two successful Checkouts for one orderInspect all attempts, deliver only the agreed order and handle additional funds separately
Customer claims a shortfall without an exceptionVerify current records and main status before creating any additional collection or refund
Retrieval timeout or loading failureKeep the result unknown and recover queries for the original session; do not declare it unpaid

If excess and insufficient funds coexist, paidPartial takes display priority. An ordinary refund does not itself create a shortfall exception, and a cleared exception does not establish that support work is finished.

Late funds and confirmation speed​

The validity window includes confirmation time. Default low requires native finalized confirmation; medium requires safe; high requires successful execution and inclusion in a block. Faster confirmation carries higher subsequent risk. Do not substitute fixed waiting periods or universal block counts for these native confirmation levels. Business and technical owners should assess whether goods can be recovered before changing policy.

Close the case​

Confirm fulfillment, the final destination of excess funds, actual refund success and any unresolved sessions. See refunds for eligibility and orders for delivery deduplication. Keep unresolved funds under review rather than marking them resolved without evidence.