Payment resource model

Paybytoken separates what the customer is paying, how the payment is presented and how funds move. Choose the top-level resource that matches the business obligation, then let Checkout Sessions and Payment Intents represent individual attempts.

Choose the top-level resource

Your business need	Start with	What it owns
Collect one stablecoin order now	Checkout Session	One customer-facing stablecoin checkout attempt for a server-owned order.
Offer stablecoin, card and wallets for one order	Payments Router	One provider-neutral Payment with option-based attempts and server-owned routing.
Publish one reusable collection page	Payment Link	Reusable catalog or custom-amount configuration that creates a new Session for each visit.
Collect one known receivable over time	Payment Request	Customer, due amount, delivery history, partial payments and reconciliation.
Hold funds for later customer activity	Customer balances	Persistent deposit accounts and exact-asset balances for payments and withdrawals.
Let a Paybytoken consumer approve from their balance	Paybytoken Pay	A private-beta authorization handoff between a merchant and a Paybytoken consumer.

Do not use a Payment Link as an invoice or a Customer Balance as an order ledger. These resources have different lifetimes, ownership rules and reconciliation behavior.

Payments Router Payment

A Router Payment is the canonical order when the customer can choose across stablecoin, card, Apple Pay or Google Pay. It is not another name for a Core Payment Intent. The Payment owns customer options and logical attempts; Router persists an immutable routing decision before dispatching to a processor-specific attempt.

Use a separate Payments credential and API origin. The browser submits only option_id; provider selection, connected accounts and fallback policy remain server-owned. See Payments Router.

Checkout Session

A Checkout Session is the customer-facing attempt to pay one resolved order. It contains the currency, amount or line items, supported token-and-network pairs, presentation mode, expiry and return behavior.

Choose one presentation mode:

Hosted redirects to a Paybytoken-hosted page.
Embedded mounts the managed checkout inside the merchant page with a session-scoped client secret and an exact allowed origin.
Custom lets the merchant render the interface and confirm the selected token from its server.

A Session is intentionally short-lived. If the customer needs a fresh attempt after expiry or a material order change, create a replacement Session instead of mutating historical payment state.

Payment Intent

A Payment Intent is the authoritative payment state behind a payment attempt. It records what must be collected, the selected payment method and the asynchronous transition from creation to a terminal outcome.

Your application normally creates a Checkout Session and lets Paybytoken create or associate the corresponding Payment Intent. Use the Payment Intent ID for server-side status, support and event correlation. Do not expose internal intent operations as customer controls unless a documented flow requires them.

Fulfill an order only after a verified terminal event such as payment_intent.succeeded. A hosted redirect, embedded completion callback or wallet transaction submission is not proof that the payment settled.

Payment Link

A Payment Link is reusable configuration, not a payment attempt. Each customer visit resolves the current link configuration and creates an isolated Checkout Session and Payment Intent.

Use it for:

a fixed product or campaign;
a reusable donation or account top-up page; or
a customer-entered amount within configured minimum and maximum limits.

Deactivate the link to stop new sessions. Existing Sessions and Payment Intents remain historical records and keep their original snapshots.

Payment Request

A Payment Request is a durable receivable for a known customer. It can remain open across email delivery, reminders, checkout retries and multiple allocated payments.

The request owns the amount due and reconciliation state. A customer payment creates a Checkout Session sourced from the current request version. Successful Payment Intents are allocated back to the request atomically, reducing its remaining amount. The request becomes paid only when its allocated total covers the amount due.

Use Payment Requests when the receivable must survive one browser session. Invoice rendering and tax accounting are separate product concerns and should not be inferred from the Payment Request resource.

Customer balances

Customer balances represent persistent, merchant-scoped funds. A customer can receive deposits, hold exact chain-and-asset balances, authorize an internal payment and request a withdrawal.

Balances are not interchangeable across assets or networks. Treat USDC on Base and USDC on Ethereum as different balance buckets unless an explicit conversion product exists. The merchant must keep its own customer identity and business ledger while Paybytoken records payment and funds movement resources.

How the resources connect

Checkout-based collection

Business source

One orderDirect order

ReusablePayment Link

ReceivablePayment Request

PresentationCheckout Session

Payment statePayment Intent

Server resultSigned event

Each visit or collection attempt receives its own short-lived Session and canonical Payment Intent.

Balance-based authorization

Authorization source

Merchant customerCustomer balance

Consumer handoffPaybytoken Pay

Payment statePayment Intent

Server resultSigned event

Customer Balance and Paybytoken Pay do not create a Checkout Session.

For Payment Links and Payment Requests, the source resource is copied into the Checkout Session as an immutable attribution and version snapshot. Later edits do not rewrite an existing attempt. Balance and Paybytoken Pay flows act on a Payment Intent without creating a Checkout Session.

Store these identifiers

Keep resource IDs next to your own business records:

Identifier	Store it with	Why
Checkout Session ID	Order attempt	Resume, cancel or investigate the customer-facing attempt.
Router Payment and Attempt IDs	Multi-method order	Correlate option selection, routing, provider execution and Payment-root events.
Payment Intent ID	Payment record	Correlate canonical status, events, refunds and support cases.
Source resource ID and version	Order or receivable	Preserve Payment Link or Payment Request attribution.
Event ID	Webhook delivery log	Deduplicate fulfillment and replay processing.
`X-Request-Id`	API operation log	Give support a safe trace identifier without exposing secrets.

Use your own stable order or receivable ID in metadata, but never place secrets or sensitive customer data there.

Next steps

Follow Get started to create the first Checkout Session.
Model retries and replacements with Orders, Sessions and payment attempts.
Choose Payment Links or Payment Requests when the collection must exist before a customer begins checkout.
Use Payment operations to investigate, refund and reconcile completed attempts.