Create a hosted checkout session for payment-method tokenization
Saves a card through a small verification charge (₦50 for NGN, one major unit in most other currencies). The charge is refunded automatically once it settles; the saved card stays on file.
Authorizations
Use a Bouclay secret key (sk_test_..., sk_live_...) or restricted key
(rk_test_..., rk_live_...).
A secret key can call every endpoint. A restricted key can only call the
endpoints its scopes cover. A scope is {resource}:{access}, for example
customers:read or refunds:write, and write includes read. GET
requests need read access and everything else needs write, except
POST /subscriptions/{id}/items/{item}/preview, which only needs
subscriptions:read. A request outside the key's scopes gets 403 permission_denied naming the missing scope, and its Idempotency-Key
is not used up.
Publishable keys (pk_...) are rejected by server-side API endpoints. A
key's mode scopes what it can see and charge: a test key can never reach
a live card.
Headers
Required for POST and PATCH requests. Replays identical method + path + body requests and rejects mismatched re-use.
1 - 255Body
Move the customer's automatic subscriptions (trialing,
active, past due, paused, waiting for a first payment)
onto the new card once it is saved, as the portal's card
update does. Without it, a subscription created with a
paymentMethod keeps charging that card, so send true
when the customer is replacing a card that fails.
Where the customer lands once the gateway is done: https,
or plain http only for a local address (localhost,
127.0.0.1, *.test). Bouclay appends checkoutSession=<id> and
status=complete|failed. Treat those as a hint and confirm
with GET /checkout-sessions/{id} before trusting it.
2048