Testing and security

Test and live origins

allowed_origin is one exact origin: scheme, hostname and optional port. It cannot contain a path, query, fragment, credentials or wildcard.

https://shop.example.com
http://localhost:3000

Live sessions require HTTPS. Test sessions may use HTTP only for local development on localhost, *.localhost, 127.0.0.1 or ::1. The value must exactly match window.location.origin, including a non-default port.

Create separate sessions for separate origins. Do not reuse a session created for a preview URL on production.

Test mode currently exposes Circle's official USDC contract on Polygon Amoy. It does not expose a Polygon test USDT because no Paybytoken-verified USDT0 contract is available on Amoy. Do not use a third-party faucet token as though it were the live asset.

Credential handling

Credential	Location	Rules
`sk_test_...` / `sk_live_...`	Merchant server only	Store in a secret manager; never return it to the browser.
`chk_client_...`	Matching merchant page, in memory	Session-scoped; do not log, persist, analyze or put it in a URL.
Checkout Session CSRF token	Merchant server only	Keep it bound to the matching custom session and authenticated customer.
`whsec_...`	Webhook server only	Verify the exact raw request body and rotate deliberately.

The iframe URL contains a signed bootstrap value, not a merchant API credential. The SDK validates the checkout origin, iframe window, protocol version and session ID before accepting messages.

Content Security Policy

Production:

connect-src 'self' https://api-prod.paybytoken.io;
frame-src https://checkout.paybytoken.io;

Add your merchant logo host to img-src if needed. Avoid wildcard domains and keep your own application's existing CSP directives.

Test matrix

Before live launch, cover:

hosted, embedded and custom checkout;
every enabled token and network;
single and multi-item orders;
injected wallet, selected EIP-1193 provider and manual transfer;
wallet rejection, wrong network, insufficient balance and expired session;
cancel, retry, return and page refresh;
duplicate and delayed webhook delivery;
current Chrome, Edge, Firefox and Safari;
iOS Safari, Android Chrome and the wallet browsers your customers use;
responsive height changes, keyboard navigation and reduced motion; and
CSP and exact-origin behavior on preview and production domains.

Use a new Checkout Session for each test attempt. A Checkout Session and its one-time destination belong to one order and must not be recycled.

When this matrix passes, continue with the go-live checklist. Test-mode success does not migrate keys, webhooks, branding or resources into live mode.