API keys

Every request to the API is authenticated with a secret key of a merchant account. The key says which account the request acts on and in which mode, test or live.

Key	Mode	Example prefix
sk_test_<market>_…	Test: no real money moves (Test mode)	sk_test_in_4fQx9aZ2
sk_live_<market>_…	Live: real payments	sk_live_in_7Hq2LmP0

The part after the mode is the account’s market (in for India). The first characters of a key, such as sk_live_in_7Hq2LmP0, are its prefix: it is how we show a key, in lists and in our messages to you, so you can tell keys apart without seeing a secret.

Where your keys live

Your account’s keys are in the merchant portal, under Settings › Developers › API keys. An admin or a developer of the account sees the page and manages the keys. Our support team can also create, rotate or expire a key for you; the list then shows it as done by Support team. The page shows the keys of one mode at a time: switch the portal to Test mode for the test keys.

Every key in the list has its name and note, its prefix, who created it and when, when it was last used (updated about once a minute), and whether it works: Working; Expires in… while a rotated key’s expiration runs; Expired, with the day, once it has passed; or Revoked, with the day and who, after Expire key…. Show expired keys lists the keys that have stopped as well.

A change to the keys, Create, Rotate or Expire, asks you to confirm it’s you when you have not signed in recently.

Creating a key

Create secret key asks for a name, such as “Production” or “Staging”, and an optional note, such as where you will store it. The secret is shown once, right after: we keep only a hash of it and cannot show it to you again. Copy it into your secret manager straight away. A key whose secret is lost cannot be recovered: rotate it, or create a new one and expire the old one.

Create secret key stops at 10 working keys of a mode: a key that is due to expire still counts, one that has expired does not. At the limit, expire a key before you create another. A rotation is never refused by the limit, as it replaces one key with one, so during its expiration the old key and its replacement both work and both count.

Edit key changes a key’s name and note. They tell keys apart and change nothing about what the key can do.

Test keys and live keys are kept apart: the page in Test mode lists and creates test keys, which work only in test mode, and in live mode it lists and creates live keys. An admin or a developer of the account makes both, with no request to us. A test key works as soon as your merchant is in test on the account’s market; a live key once we activate your merchant there for live: until then a request with it gets 403 market_not_enabled (see Authentication). A market with no test environment yet says so on the page in Test mode, and has no test keys to create.

Emails about your keys

When a key is created, rotated or expired, every admin of the account gets an email. It says who did it (a person of your team, or Support team), when, and the key’s name and prefix; for a rotated or expired key, when it was last used; for a rotation, the new key’s prefix and when the old key stops working. It never contains a secret. Editing a key’s name or note sends nothing, and neither does expiring the old key of a rotation within a minute of when it stops anyway: the rotation’s email already said when. An email you did not expect means someone changed your keys. Check the list by prefix: after a rotation, the new key has the old one’s name, so match the new prefix from the email. Expire any key you do not recognise. After a rotation you did not make, expire the new key; the old one still stops when the email says and cannot be rotated again, so create a new key and move your servers to it before then.

Keeping keys safe

A secret key can do everything the API can do on its account, so:

• Use it only on your servers. Never put it in a mobile app, a web page, or anything else that runs on your customer’s device.
• Keep it out of your code and repositories: read it from your secret manager or an environment variable.
• Do not send it in email or chat. We never ask you for a key.
• Allow your live keys only from your own servers with an IP allowlist. A leaked key is then useless anywhere else.

Rotating a key

Rotate keys on a schedule, and at once when someone who had access leaves or a key may have leaked. Rotate key… replaces one key: it creates a new key with the same name and shows its secret once, and Expiration sets when the old key stops working: Now, 1 hour, 24 hours, 3 days or 7 days. The account’s other keys are not touched.

To rotate without downtime, choose an expiration long enough to deploy:

1. Rotate the key and store the new secret.
2. Deploy the new key to every server that sends the old one.
3. Watch your logs, and the old key’s Last used (reload the page to read it again), until nothing sends the old key.
4. Let the old key expire, or expire it yourself.

A rotation never extends a key: a key is replaced once, and one that is already due to expire cannot be rotated again. Rotate its replacement instead, or expire it.

Expiring a key

Expire key… stops a key at once, and it cannot be undone: the list shows it as Revoked. Expire a key that has leaked rather than rotating it with an overlap. When the key was used in the last 24 hours, you confirm by typing its name.

A request with a key that was revoked with Expire key…, or replaced by a rotation whose expiration has passed, gets 401 with the code api_key_expired and the key’s prefix in the message, so you can tell which key your server still sends. A key that is wrong or unknown gets 401 with no code (see Authentication).