API reference
Create checkout session
Short-lived hosted checkout token and embed URL.
POST
/checkout-sessionsCreate a short-lived hosted checkout. Returns a session token and embed URL. Keep the secret API key on the server.
- Permission
- write:invoices
- Auth
- api-key
- Idempotent
- Yes — send Idempotency-Key
- Language
- Node.js
| Field | In | Type | Required | Description |
|---|---|---|---|---|
| fiatAmount | body | number | Yes | Amount the customer should pay, in fiatCurrency. Respect that currency's decimals from GET /currencies (0, 2 or 3). |
| fiatCurrency | body | string | No · ZAR | Supported ISO 4217 code returned by GET /currencies. Validated before the session is stored. Defaults to ZAR. |
| reference | body | string | No | Your order identifier. Stored on the resulting invoice. |
| expiresInMinutes | body | number | No · 15 | Session lifetime from 1 to 60 minutes. |
| restrictNetworks | body | string[] | No | Limit networks to those your destinations support in this environment. |
| metadata | body | object | No | Copied to the invoice created from this session and included in its events. |
| successUrl | body | string | No | HTTPS URL checkout returns the customer to after settlement completes. Never treat the redirect as proof of payment: fulfill from a verified invoice.paid event. |
| cancelUrl | body | string | No | HTTPS URL for a customer who leaves without paying. |
const response = await fetch(`${process.env.BOSPAY_API_BASE}/checkout-sessions`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"BOSPay-Version": "2026-09-23",
"X-API-Key": process.env.BOSPAY_API_KEY,
"Idempotency-Key": "order-1048-attempt-1",
},
body: JSON.stringify({
"fiatAmount": 150,
"fiatCurrency": "ZAR",
"reference": "order-1048",
"expiresInMinutes": 15,
"restrictNetworks": [
"sepolia"
],
"metadata": {
"orderId": "1048"
}
})
});
if (!response.ok) {
throw new Error(`BOSPay request failed: ${response.status}`);
}
const data = await response.json();Success
201
{
"id": "cs_example",
"object": "checkout_session",
"sessionToken": "CHECKOUT_SESSION_TOKEN",
"embedUrl": "https://checkout.bospay.co/embed?session=CHECKOUT_SESSION_TOKEN",
"expiresAt": "2026-09-23T10:57:00.000Z",
"restrictNetworks": [
"sepolia"
],
"environment": "sandbox",
"livemode": false,
"metadata": {
"orderId": "1048"
}
}Validation error
400
{
"error": {
"type": "invalid_request_error",
"code": "validation_error",
"message": "A valid fiatAmount is required.",
"field": "fiatAmount",
"requestId": "req_3f0c9a1b2c4d5e6f7a8b9c0d"
}
}