Payments Router

Payments Router is the multi-method orchestration layer. It creates one Payment, exposes the customer-facing options eligible for that merchant and mode, and selects an authorized provider connection on the server. The browser chooses an option_id; it never chooses a processor or provider account.

Use Router when one order should offer more than the native stablecoin flow. Continue using a Core Checkout Session when the order is intentionally stablecoin-only and you need direct token-and-network control.

Choose the correct control plane

Requirement	Start with	API origin	Credential
Native stablecoin checkout	Core Checkout Session	`https://api-prod.paybytoken.io/api/v1`	Core merchant secret
Stablecoin plus card or wallet options	Router Payment	`https://payments-api.paybytoken.io/v2`	Payments merchant credential
Persistent customer crypto balances	Core Customers and balances	`https://api-prod.paybytoken.io/api/v1`	Core merchant secret
Post-payment conversion or settlement	Paybytoken operations	Not a browser integration surface	Internal service assertion

The Core and Payments credentials are deliberately independent. Do not reuse one as the other, and never place either credential in browser code.

Resource model

Provider-neutral payment execution

MerchantOrder

RouterPayment

Customer options

CryptoStablecoin

Card railCard

WalletApple Pay

WalletGoogle Pay

Server-ownedProvider connection

Customer choice and processor selection are separate decisions.

The Router persists four different records:

Payment is the merchant order and canonical multi-method status.
Payment Attempt records one customer option selection.
Routing Decision is the immutable policy and ordered provider candidate snapshot.
Processor Attempt records dispatch to one provider connection and any scoped customer action.

An ambiguous processor result becomes unknown and remains bound to the same processor until reconciliation resolves it. Router does not automatically try another processor after a possible authorization.

Operations after payment

Keep the Router payment.id as the merchant support and reconciliation identifier. Retrieve /v2/payments/{payment_id}/operations for the successful option, processor evidence, settlement, refund exposure and disputes. Use /sync to refresh uncertain provider evidence and create refunds under the Payment so Router can enforce the original processor and merchant connection.

The legacy payment_sessions API remains a compatibility surface. New Router integrations should not translate a Payment back into that shape or mix v1 session operations with v2 creation.

Customer actions

The selected attempt returns a generic action envelope:

Action	Client behavior
`redirect`	Navigate to the scoped Paybytoken or provider URL.
`embedded`	Mount the stablecoin checkout with `@paybytoken/checkout`.
`sdk`	Dispatch by `provider` and `component` at the renderer boundary.
`none`	Wait for an authoritative server status.

Card uses Stripe Payment Element when Stripe is the selected processor. Apple Pay and Google Pay use their matching Express Checkout wallet and do not silently fall back to card entry.

Completion boundary

Fulfill only after a verified payment.succeeded event or an authenticated retrieval where payment.status === "succeeded". A redirect, iframe close, wallet sheet completion or frontend SDK callback is not settlement evidence.

Continue with Hosted Router checkout or the Router HTTP API.