API reference
Versioning
Send BOSPay-Version on every request. Breaking changes ship behind a new date; your integration only changes when you change the header.
Pin a version
Send BOSPay-Version: 2026-09-23. The response echoes the version it used in the BOSPay-Version header. Supported versions are 2026-09-16 and 2026-09-23; anything else returns 400 unsupported_version.
Without the header
API-key requests without the header use your organization's pinned version. Organizations created before 2026-09-23 are pinned to 2026-09-16. Check it with GET /account/api-version; an admin can move the pin in the console after testing with the header.
const response = await fetch(`${process.env.BOSPAY_API_BASE}/account/api-version`, {
method: "GET",
headers: {
"Content-Type": "application/json",
"BOSPay-Version": "2026-09-23",
"X-API-Key": process.env.BOSPAY_API_KEY,
}
});
if (!response.ok) {
throw new Error(`BOSPay request failed: ${response.status}`);
}
const data = await response.json();What counts as breaking
New fields, new event types and new endpoints can appear in any version, so ignore fields you do not recognise. Removing, renaming or reshaping a field, or changing an error code, only happens in a new dated version.