API v2 is not live yet: it launches in early 2027, and until then these pages are its spec. Switch to v1 (live)

Authentication

Every request authenticates with an API key, sent with HTTP Basic authentication. A key belongs to a shop, a user, or a partner, and may make only the requests it has permission for.

The Authorization header

Send the key as the credentials of HTTP Basic authentication, base64-encoded:

Authorization: Basic base64({apikey})

A key contains a colon, which separates its ID from its secret, as Basic authentication separates a user name from a password. So curl's -u {apikey} sends it as it is, and so does any HTTP library that takes a user name and a password: give it the ID as the user name and the secret as the password.

There is no other way to authenticate: no key in the URL or the body, and no cookies.

API keys

A key starts with whose it is, by a letter and an ID, then the key's own number, and its secret after the colon:

Key	Belongs to
`s{shopid}#{keyid}:{secret}`	A shop. It can act on that shop only.
`u{userid}#{keyid}:{secret}`	A user. It can act on every shop the user has access to, as far as both the key and the user's role in the shop allow.
`p{partnerid}#{keyid}:{secret}`	A partner. It can act on every shop that the partner owns.

The part before the colon is the key's ID, and its {keyid} is unique only among its owner's keys. Everything done with a key, through the API or the dashboard, is recorded with its ID: a capture made with key 1 of shop 1379 has "who": "s1379#1" in the transaction's acts.

Keep a key's secret on your server. A key in a browser or an app can be read by anyone who has the page or the app, and used to capture, refund, and charge as you.

Permissions

A key has permission for some or all of these, and a request that its key lacks permission for fails:

Permission	Requests
`payid`	Create payment link, Create subscriber, and Renew subscriber, which all create a link, and Delete payment link
`seq`	Seq
`capture`	Capture transaction
`refund`	Refund transaction
`void`	Void transaction
`charge`	Charge subscriber and Delete subscriber

A key for a server that only creates links and reads seq needs nothing more, and can't refund if it leaks.

Pings

A key with a ping URL gets a ping whenever something changes in a shop that the key can act on: one shop for a shop's key, and every shop the user or partner has for theirs. You set the ping URL in the dashboard.

Errors

A request that fails to authenticate is answered with:

HTTP/1.1 401 Unauthorized
Content-Type: text/plain

Unauthorized

It is the same, whatever the reason, so that it tells an attacker nothing:

The Authorization header is missing, or is not Basic.
The credentials are not valid base64, or not of a key's form.
The key does not exist, or its secret is wrong.
The key is a shop's, and the URL names another shop.
The key, or the user it belongs to, lacks permission for the request or has no access to the shop.

Don't retry a 401: it will fail the same way until the key or its permissions change. We check the key before we read the body, so a 401 means that nothing was done.