---
title: "Payment boundaries"
description: "Keep payment, order, device, and external-service responsibilities separate."
canonical: https://docs.ordering.co/docs/developers/customer-app/payment-boundaries/
---

# Payment boundaries

Use this reference to keep payment presentation, order placement, an external payment handoff, and Ordering.co settlement as separate stages. This guide does not establish payment execution.

> **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.co 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.co 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.co authorization, charge success, or order creation |
| External payment service | Own its own collection surface and transaction response                                                                                | That Ordering.co 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 state model defines the boundaries a payment flow must meet. 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.co placement:** A payment flow must have Ordering.co 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.co settlement:** A payment flow must have Ordering.co 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.co settlement.

## Eligibility is not readiness

A visible payment choice, saved instrument, wallet value, or completion path does not establish availability 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.co 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 payment flow must query an authorized Ordering.co 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.co returns an authoritative result.

A unified operation-status receipt and safe automatic recovery contract are not established by the current application paths.

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

## Safe implementation and verification

A payment flow 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.co 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 change triggers

Revalidate 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-component, or API versions.

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](https://docs.ordering.co/docs/developers/customer-app/native-integrations/) · [Choose a payment method](https://docs.ordering.co/docs/products/customer-app/cart-checkout/payment-methods/) · [Checkout status and retry guidance](https://docs.ordering.co/docs/products/customer-app/cart-checkout/failures-retries/) · [Customer App configuration boundaries](https://docs.ordering.co/docs/developers/customer-app/configuration/)