Authorization, deadlines and recovery
Session access, spending authority and business entitlement have different boundaries. Recovery should restore the original Session and Request before assessing transaction facts, so a network timeout does not become a second payment.
Three authorization layers
Merchant API Keys remain on the business server for Checkout creation, owned Session queries and access renewal where supported. A Session Token is an opaque Bearer bound to one Session, allowing wallet confirmation, private Request reads, optional Credential submission and queries. Wallet/Core authorization permits actual execution. A token does not identify the buyer, and a transaction hash does not grant entitlement to goods.
Obtain the original sessionUrl from trusted delivery. Subsequent links and Location must use its HTTPS origin and the operation's expected method. Do not forward tokens to another origin or follow redirects on authenticated requests. The checkoutUrl fragment contains separately encoded sessionUrl and token values; clear it from the address bar after reading. API calls use Authorization Bearer. Keep tokens out of API URLs, logs and localStorage.
Five separate times
| Time | Purpose |
|---|---|
| Session.expiresAt | First confirmation must occur strictly before this time |
| Request.createdAt | First successful persisted confirmation |
| Request.expiresAt | Deadline for execution, finalized verification and atomic redemption |
| credit.expiresAt | Long-term grant expiry |
| Token lifetime | Access validity; does not change deadlines or chain facts |
For example, a Session expires at 09:55, confirmation occurs at 09:54 and the execution window is ten minutes: the Request expires at 10:04. Session expiry at 09:55 does not end the confirmed execution. Retries, token rotation, device handoff and Broadcaster changes do not refresh 10:04. Inclusion at 09:59 followed by finalized verification and redemption at 10:05 cannot complete normally. Downtime and RPC outages do not extend the window.
States and recovery actions
| State or result | Action |
|---|---|
| open | Not confirmed; display and check options before confirmation |
| requires_action | One Request exists; an execution may still be in flight, so this does not authorize repayment |
| processing | Matching canonical execution observed; wait for finality and redemption |
| succeeded | Read immutable receipt and current evidenceStatus; fulfill idempotently |
| failed | This Checkout has ended; continue reconciling facts without restoring succeeded |
| Credential 202 | Hint accepted only; continue reading the original sessionUrl |
After a lost creation or confirmation response, reuse the original Idempotency-Key and input to recover the original object. Different input under the same key returns 409. Changing confirmation keys cannot bypass one Request per Session. Reading a processing, succeeded or failed Request must not automatically start another wallet execution.
Timeouts, indexing lag and lost broadcast responses cannot prove nonpayment. Restore and query the original transaction first. Retry execution under the same requirements only after the original operation is proven failed or invalid, other in-flight operations are excluded and the deadline remains open. Creating another Checkout while the old outcome is unknown can duplicate payment or credit authorization.
An expired token returns 401. Use the implementation's authenticated merchant process to recover access to the original Session. Renewal preserves the Request and cannot reopen terminal confirmation. 400 means invalid input, 403 a disallowed operation, 404 missing or inaccessible object, 409 state/idempotency conflict, 429 throttling and 503 an unavailable dependency. retryable means repeat the original HTTP operation, not pay again; respect Retry-After.
Receipt health and exceptions
A successful receipt stays immutable while current evidenceStatus can be confirmed, reconciling or disputed. The latter two require holding new dependent business operations and assessing reconciliation or compensation. Temporary RPC unavailability alone does not erase a historical receipt; a historical credit receipt cannot prove present availability.
Late payments, extra receipts and exceptional credit creations have separate records, summarized by exceptionSummary.count and unresolvedCount. Facts found after failed do not create a normal success receipt. Counts do not imply refund or revocation; refunds, manual handling and revocation are separate actions. Merchants bind service origin and sessionId to the original order and caller, enforcing fulfillment idempotency in their own database.