Changelog

2026-09-23

• Every list is { object: "list", data, hasMore, nextCursor }. 2026-09-16 kept bare arrays or { success, data } wrappers for webhooks, deliveries, destinations, API keys and reports.
• Single objects are returned bare with object and id. Deletes return { id, object, deleted: true }.
• New error codes idempotency_in_progress, state_conflict, internal_error and verification_required.

Applies to all versions

• Typed IDs for new objects: inv_, cs_, we_, whd_, evt_, key_. Existing UUIDs stay valid; treat IDs as opaque strings up to 255 characters.
• An invoice's id now equals its invoiceId.
• metadata, object, environment and livemode on invoices and checkout sessions; type on every error.
• Idempotency-Key on every POST, with Idempotent-Replayed on replays.
• Sandbox and live data are isolated per key. Webhook endpoints belong to one environment.
• Events API (list, retrieve, resend), invoice.created, and stable event ids in webhook headers.
• Restricted and publishable keys. Realtime tokens replace API keys in WebSocket URLs.
• POST /invoices/:id/cancel returns 200 and is idempotent.
• Payout wallets are console-only (admins, emailed code, 24-hour hold). API keys get 403 on wallet changes, and invoice merchantAddress must be a registered wallet.
• Console roles: members are read-only; admins make changes. API keys cannot manage API keys. Suspended organizations are blocked.
• Invoices: paymentException, amountRemaining, overpaidAmount and amountRefunded. A short settlement is manual_review (underpaid), never paid; payments after expiry are manual_review (late_payment).
• POST /invoices/:id/refunds and GET /invoices/:id/refunds record refunds you send yourself.
• Invoice creation keeps its quote across retries and crashes. A 4xx releases the Idempotency-Key; non-resumable requests that fail with 5xx return operation_uncertain until an admin resolves them.
• Invoice fiatAmount is stored exactly and must respect the currency's decimals (whole numbers for JPY, three for KWD). Quotes round up at the token's precision (6 decimals for stablecoins, 8 for native coins), so rounding never leaves you short and never costs the customer more than a millionth of a stablecoin.
• X-Request-Id is always a BOSPay req_… ID; an X-Request-Id you send is returned as X-Client-Request-Id.
• merchantAddress in invoice responses is deprecated: it repeats paymentAddress (where the customer pays). Your payout wallet is settlementRecipient. It will be removed from responses in the next API version.
• GET /networks reports the API version of the response in version, matching the BOSPay-Version header.

2026-09-16

• Invoices, checkout sessions, destinations, webhooks, and networks documented as one contract.
• Hosted checkout recommended. Embedded, mobile, and payment links designed on the chooser only.
• Checkout session tokens scoped separately from server API keys.