Troubleshooting

Checkout does not mount

Confirm the session was created with ui_mode: 'embedded'.
Return both clientSecret and checkoutUrl from the merchant route.
Mount into an existing, empty element after initialization completes.
Check that CSP allows the exact API in connect-src and checkout host in frame-src.
Handle onInitializationError and loaderror separately: the first happens before an instance is ready; the second reports an iframe load failure.

Compare the session's allowed_origin with window.location.origin. Scheme, hostname and port must match exactly. Do not include a trailing path and do not use a wildcard. Create a new session after changing environments.

Invalid or expired credential

The client_secret is short-lived and belongs to one session. Do not cache it or reuse it after expiry, cancellation or destruction. Call your merchant session endpoint again and initialize a new checkout instance.

The session route creates duplicate sessions

Keep fetchCheckoutSession and walletProvider references stable in React. Initialize only when the customer opens the payment step. Destroy an old instance before replacing it.

Wallet is unavailable

If no injected wallet is present, keep Send manually available. If your application already uses WalletConnect, RainbowKit or wagmi, pass its selected EIP-1193 provider in walletProvider.

Wallet opens with unexpected transaction details

Do not build an ERC-20 transfer from iframe messages or merchant UI state. Upgrade to the current @paybytoken/checkout package and let it derive the destination, chain, contract and amount from the authenticated session.

Browser says complete but the order is unpaid

This is expected while the network is still being confirmed or if the browser signal is untrustworthy. Show a pending state and wait for a verified payment_intent.succeeded webhook or an authenticated server lookup before fulfillment.

Error types

EmbeddedCheckoutError.type can be:

Type	Meaning
`invalid_configuration`	A URL, locale, appearance value, timeout or wallet provider is invalid.
`invalid_request`	The checkout bridge requested malformed or mismatched data.
`api_error`	Paybytoken returned an unsuccessful API response.
`network_error`	The browser could not reach the API.
`request_timeout`	A bridge API request exceeded its configured timeout.
`wallet_error`	Wallet connection, network switching or transfer failed.
`destroyed`	Code attempted to use an instance after `destroy()`.

Log the error type, API status and your own order/session correlation ID. Never log a merchant secret, client secret, webhook signature or complete one-time destination.