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
- Pause additional automatic delivery or payment reminders for the order and locate all associated Checkout IDs.
- Query the original session from your server. Verify environment, amount, currency, main status, exception and failure reason, and record the query time.
- Check existing fulfillment, refunds and submitted funds transactions so another operator does not repeat them.
- If payment details are enabled, inspect actual payment items and refundable amounts. Otherwise, ask your verified contact to investigate missing details.
- 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
| Situation | Interpretation and action |
|---|---|
Long-running processing | An on-chain payment was detected; keep checking confirmation rather than requesting another payment or declaring success after a fixed delay |
Customer reports funds after failed | Check expiry or closure and late funds; preserve the failed main status and handle funds separately without automatic delivery or another charge |
paidOver | Extra funds remain unrefunded, possibly from duplicate or late payments; decide ordinary order fulfillment under your business policy and handle the excess separately |
paidPartial | Previously 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 order | Inspect all attempts, deliver only the agreed order and handle additional funds separately |
| Customer claims a shortfall without an exception | Verify current records and main status before creating any additional collection or refund |
| Retrieval timeout or loading failure | Keep 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.