Payment boundaries

Use this reference to keep payment presentation, order placement, an external payment handoff, and Ordering settlement as separate stages. Payment execution is source-only and pre-action for this documentation wave.

Do not infer payment completion

A visible method, a completed external handoff, a callback, or navigation away from checkout does not prove that an order was placed or paid. Only the current, authorized Ordering result can establish the final application state.

Responsibility model

Layer	Responsibility	Does not prove
Customer App	Present the current checkout state, prerequisites, available choices, and safe status	Eligibility, provider readiness, or final settlement
Ordering services	Authorize the customer and cart, validate the amount and method, begin placement, and reconcile the authoritative order/payment result	External-service availability or device capability
Operating system	Report platform capability and own any platform-level presentation or handoff	Ordering authorization, charge success, or order creation
External payment service	Own its own collection surface and transaction response	That Ordering accepted the response or created the order

Business and project configuration can narrow which methods are candidates, but configuration and presentation are not authorization.

Required safe payment state model

This is the normative state model required for a future accepted implementation. It does not describe a unified operation contract already established by the current Customer App paths. Treat each transition as independently observable:

1. Eligibility: Customer App receives a method that may apply to the current business, customer, cart, amount, and device.
2. Customer action: the customer deliberately requests the next step.
3. Ordering placement: a future accepted implementation must have Ordering validate the current cart and create or resume one payment operation.
4. External handoff: the operating system or external service can return a cancellation, failure, success indication, or no conclusive result.
5. Ordering settlement: a future accepted implementation must have Ordering reconcile that result with the same authorized operation and return the authoritative order/payment state.

Do not collapse these stages into a single “pay” result. In particular, an external success indication still requires Ordering settlement.

Eligibility is not readiness

Source inspection does not establish that a payment choice, saved instrument, wallet value, or completion path is available for a particular customer, business, device, or order. Verify presentation separately from:

• current customer and cart authorization;
• amount, currency, and cart revision;
• operating-system capability;
• external-service readiness; and
• the final Ordering settlement.

Keep saved-instrument references and wallet balances masked and minimal. Never use presentation as evidence that an instrument can be charged or that funds are available.

Unknown outcomes and retries

A closed handoff, timeout, connection loss, app restart, callback error, or missing response can leave the result unknown. Unknown is not the same as failed, cancelled, unpaid, or completed.

When the result is unknown:

1. Do not automatically repeat placement, payment, confirmation, or provider work.
2. A future accepted implementation must query an authorized Ordering operation status without initiating a new financial action.
3. That implementation must keep the same operation identity and cart revision while reconciling.
4. It must present a final state only after Ordering returns an authoritative result.

The current pinned paths remain blocked: they do not establish one unified operation-status receipt or a safe automatic recovery contract.

Account, project, cart, amount, currency, or session changes invalidate a pending handoff until it is safely reconciled.

Safe implementation and verification

A future accepted implementation must:

• use one idempotent operation identity across placement, handoff, callback, reconciliation, and retry-safe status reads;
• validate every returned intent against the expected account, project, cart, amount, currency, revision, and freshness before using it;
• allowlist external destinations and accepted return messages so unknown origins, payloads, and navigation fail closed;
• keep payment data, credentials, provider identifiers, customer data, and internal request details out of logs, URLs, examples, screenshots, and support tickets;
• cancel or ignore stale callbacks after logout, account/project change, cart change, or unmount; and
• verify disabled, unavailable, cancelled, failed, pending, and unknown states with isolated synthetic fixtures and zero external effects.

Do not collect payment information, create or remove an instrument, initiate a payment, open an external payment surface, or test a live handoff for documentation.

Failure ownership

A method is visible but unavailable

Recheck current customer, cart, business, amount, device, and method prerequisites. Do not treat the visible choice as an entitlement or provider health signal.

The external handoff closes or reports an error

Preserve the current operation and return to the Ordering status. Do not infer whether money moved from the external message alone.

The app returns to checkout with no final result

Treat the result as unknown. Reconcile through the existing operation instead of creating another placement or payment attempt.

The account, project, amount, or cart changed

Stop the pending flow. A result for the previous context must not update or navigate the new context.

Security and recertification

Recertify this boundary after changes to payment-method eligibility, cart or order revision rules, amount/currency authority, saved-instrument handling, platform capability, external destinations or messages, callbacks, idempotency, status recovery, session/project teardown, or App/shared-components/API pins.

Public documentation must remain provider-neutral. Do not publish setup values, credentials, identifiers, tokens, endpoints, payload shapes, or live test instructions.

---

Related references: Native integration boundaries · Choose a payment method · Checkout status and retry guidance · Customer App configuration boundaries