API reference
Create invoice from session
Checkout-scoped invoice creation. No API key.
POST
/checkout-sessions/:token/create-invoiceCalled from hosted or embedded checkout after the customer selects asset and network. Uses the session token, not X-API-Key.
- Permission
- session
- Auth
- session
- Idempotent
- No
- Language
- Node.js
| Field | In | Type | Required | Description |
|---|---|---|---|---|
| token | path | string | Yes | sessionToken from POST /checkout-sessions. |
| tokenSymbol | body | string | Yes | Asset selected in checkout. |
| chain | body | string | Yes | Network selected in checkout. |
Uses the checkout session token, not your secret API key.
const response = await fetch(`${process.env.BOSPAY_API_BASE}/checkout-sessions/CHECKOUT_SESSION_TOKEN/create-invoice`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"BOSPay-Version": "2026-09-23",
"X-Checkout-Session": "CHECKOUT_SESSION_TOKEN",
},
body: JSON.stringify({
"tokenSymbol": "USDC",
"chain": "sepolia"
})
});
if (!response.ok) {
throw new Error(`BOSPay request failed: ${response.status}`);
}
const data = await response.json();Success
201
{
"id": "inv_1048",
"object": "invoice",
"invoiceId": "inv_1048",
"status": "pending",
"environment": "sandbox",
"livemode": false,
"fiatAmount": 150,
"fiatCurrency": "ZAR",
"cryptoAmount": "8.42",
"tokenSymbol": "USDC",
"chain": "sepolia",
"paymentAddress": "0xinvoicePaymentAddress",
"paymentLink": "https://checkout.bospay.co/checkout/inv_1048",
"metadata": {
"orderId": "1048"
},
"expiresAt": "2026-09-23T18:42:00.000Z",
"createdAt": "2026-09-23T10:42:00.000Z"
}Validation error
400
{
"error": {
"type": "invalid_request_error",
"code": "validation_error",
"message": "A valid fiatAmount is required.",
"field": "fiatAmount",
"requestId": "req_3f0c9a1b2c4d5e6f7a8b9c0d"
}
}Events: invoice.payment_detected, invoice.paid. Event catalogue