Authentication

The Paybytoken API uses bearer credentials. Send a server API key in the Authorization header:

curl https://api-prod.paybytoken.io/api/v1/checkout_sessions \
  -H "Authorization: Bearer $PAYBYTOKEN_SECRET_KEY"

The production API base URL is:

https://api-prod.paybytoken.io/api/v1

API key types

Prefix	Type	Use
`sk_test_...` / `sk_live_...`	Secret	Server-side API requests for the merchant account.
`rk_test_...` / `rk_live_...`	Restricted	Server-side requests limited to explicitly granted scopes.
`pk_test_...` / `pk_live_...`	Publishable	Public, read-only operations that explicitly support publishable access.

Use a secret or appropriately scoped restricted key to create Checkout Sessions. Never expose an sk_... or rk_... key in browser code, a mobile application, logs, analytics or a public environment variable.

Embedded checkout does not use a merchant API key in the browser. Your server creates the session and returns its short-lived chk_client_... credential to the exact allowed origin.

Test and live mode

The key prefix selects the data environment:

test keys access test resources only;
live keys access live resources only; and
a resource created in one mode cannot be retrieved with a key from the other mode.

Use test keys throughout development. Rotate a key immediately if it is exposed, and update the server secret atomically so requests do not fall back to a revoked credential.

Restricted key permissions

Restricted keys are merchant-scoped and grant only selected operations, such as checkout_sessions.create or payment_intents.read. Give each backend service the smallest set of permissions it needs.

A 403 response usually means the key is valid but lacks the operation's scope. A 401 response means the credential is missing, malformed, inactive or belongs to an invalid mode.

Request correlation

API responses include an X-Request-Id header. Record this value with your own order or trace ID when diagnosing a failed request. Do not log the bearer credential, embedded client secret, webhook signature or complete one-time destination address.

Continue with API errors or create your first Checkout Session.