Skip to main content
POST
Create a hosted checkout session for payment-method tokenization

Authorizations

Authorization
string
header
required

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

Idempotency-Key
string
required

Required for POST and PATCH requests. Replays identical method + path + body requests and rejects mismatched re-use.

Required string length: 1 - 255

Body

application/json
customer
string
required
setDefault
boolean
default:true
updateSubscriptions
boolean
default:false

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.

returnUrl
string<uri>

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.

Maximum string length: 2048

Response

Checkout session response.

data
object
required
meta
object
required