Authenticate backend requests

The merchant API uses a Bearer key. The gateway derives the merchant, environment, actor, and scopes from that credential.

Send the key

Include the key in the Authorization header:

Authorization: Bearer your_simplepay_api_key_here

Store it in a secret manager. Never place it in URLs, metadata, logs, screenshots, or client code.

Create one key per service and assign only the required scopes:

Task	Primary scopes
Create and read Checkout	`hosted_checkout:write`, `hosted_checkout:read`
Create and read links	`payment_links:write`, `payment_links:read`
Read payments	`reporting:read`
Manage catalog	`digital_catalog:write`, `digital_catalog:read`
Manage webhooks	`webhooks:write`, `webhooks:read`

An API key cannot create, rotate, or revoke keys. These actions require a Customer session, an administrator role, and recent step-up.

SimplePay returns a new key’s full value once. It stores an obfuscated reference, not a recoverable secret.

Last modified on August 22, 2026