API reference
Authentication
Secret and restricted keys authorize server operations. Publishable keys and checkout session tokens are browser-safe and narrow.
API keys
X-API-Key: bospay_sandbox_YOUR_SERVER_KEY
Content-Type: application/json
BOSPay-Version: 2026-09-23| Type | Prefix | Where |
|---|---|---|
| Secret | bospay_{env}_ | Server only. Every permission. |
| Restricted | bospay_rk_{env}_ | Server only. Only the listed permissions. Prefer these in production. |
| Publishable | bospay_pk_{env}_ | Browser or app. GET /networks, GET /currencies and POST /realtime/tokens only. |
Keys are shown once and stored only as a SHA-256 digest, so a lost key cannot be recovered, only replaced. Revoking a key takes effect everywhere within 15 seconds.
Permissions
read:invoices, write:invoices, read:events, read:webhooks, write:webhooks, read:settlement, read:keys, write:keys, read:networks, read:currencies, write:realtime. Older keys receive read:events, read:networks and write:realtime through read:invoices; read:currencies is also implied by read:networks or read:invoices. write:settlement is still accepted on older keys but no longer allows any change: payout wallets are console-only.
Rotation
POST /api-keys/:id/rotate issues a replacement. By default the old key keeps working for 24 hours so you can deploy the new one; pass revokeOldKey: true to revoke it immediately.
Checkout sessions
POST /checkout-sessions returns sessionToken. The embed uses it to create the invoice after asset selection. It cannot list invoices, rotate keys, or change destinations. Do not log it.
Console-only: needs a signed-in organization admin. API keys are rejected.
const response = await fetch(`${process.env.BOSPAY_API_BASE}/api-keys`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"BOSPay-Version": "2026-09-23",
"Authorization": "Bearer CONSOLE_ACCESS_TOKEN",
},
body: JSON.stringify({
"name": "Checkout server",
"environment": "sandbox",
"type": "restricted",
"permissions": [
"read:invoices",
"write:invoices",
"read:events"
]
})
});
if (!response.ok) {
throw new Error(`BOSPay request failed: ${response.status}`);
}
const data = await response.json();