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: payment_methods:read, payment_methods:write, payments:read, payments:write, webhooks:read and webhooks:write. In the dashboard you pick them in groups, each granting read and write, all selected by default; the dashboard also offers a Customers group (customers:read, customers:write), which no endpoint of this API requires. 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.