Skip to main content
Send a secret key as a bearer token in the Authorization header of every request:
A request without a key, or with a key that does not exist or has been revoked, answers 401. See Errors for the codes.

​
Key types

Server endpoints answer without an Access-Control-Allow-Origin header, so a browser cannot call them. The two browser endpoints are the payment method session retrieve and confirm, which is what Payra Elements calls, with the session’s client_secret in the query string; see Payment method sessions.

​
Create and store keys

Keys are created in the Payra dashboard, under Settings → Integrations, by a user whose role has the Manage API Keys and Webhooks permission.
  • The full key is shown once, at creation. Payra keeps only a hash of it and a few characters from each end, to tell keys apart in the list, and cannot show it again.
  • Keep secret keys in a secret manager or an environment variable. Never commit them to a repository or ship them in a mobile or browser app.
  • Each key belongs to one workspace and one environment. See Environments.

​
Rotate and revoke keys

To rotate a key, create a new one, deploy it, then revoke the old one. Rotate key, in the key’s actions menu in Settings → Integrations, does this for you: Create new key mints a key of the same type, with the old key’s name and scope groups filled in, and shows it once, and Revoke old key then revokes the old one. Revoking a key in Settings → Integrations takes effect immediately: the next request with that key answers 401 invalid_api_key.

​
Scopes

Each secret key carries scopes that limit what it can do: customers:read, customers:write, invoices:read, payment_methods:read, payment_methods:write, payments:read, payments:write, terminals:read, terminals:write, webhooks:read and webhooks:write. In the dashboard you pick them in groups, each granting read and write (Invoices grants read only, the API never writes invoices), all selected by default. Customers use the customers scopes and Invoices the invoices scope; Terminals use the terminals scopes to list and rename terminals. A key created before the terminals scopes existed does not have them, and a key’s scopes cannot be changed: create a new key for terminals. Refunds use the payments scopes and events the webhooks scopes. A request to an endpoint that needs a scope the key does not have answers 403 insufficient_scope. Retrieving the account needs no scope. A publishable key carries one scope only, payment_methods:tokenize, and can call only the two browser endpoints above. A workspace on which the API has not been enabled answers every request 403 developer_integrations_disabled; ask Payra to enable it.