API Reference
Create a checkout session
Creates a checkout session and a payment intent at the merchant's active
connector. Returns a session_secret and (when a hosted-checkout origin is
configured) a checkout_url you can redirect the buyer to, plus the
render hints the SDK needs to mount the PSP surface.
Authorization
apiKey AuthorizationBearer <token>
A secret API key, e.g. Authorization: Bearer sk_test_....
In: header
Header Parameters
Idempotency-Key?string
A client-chosen key that makes this POST safe to retry. Replaying the same
key returns the original response. A different body with the same key
returns 422 idempotency_key_reuse; an in-flight key returns
409 idempotency_conflict.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/checkout-sessions" \ -H "Content-Type: application/json" \ -d '{ "amount": 5000, "currency": "MUR", "description": "Order #1234", "customer_email": "buyer@example.com", "metadata": { "order_id": "1234" } }'{ "id": "cs_01ARZ3NDEKTSV4RRFFQ69G5FAV", "session_secret": "cs_secret_9f8e...", "render": {}, "connector": "peach", "surface": "string", "amount": 0, "currency": "string", "status": "string", "expires_at": "2019-08-24T14:15:22Z", "checkout_url": "string"}{ "error": { "code": "invalid_body", "message": "invalid request body" }}{ "error": { "code": "payment_blocked", "message": "payment blocked by risk screening" }}{ "error": { "code": "no_connector", "message": "no active connector" }}{ "error": { "code": "idempotency_key_reuse", "message": "idempotency key reused with a different request" }}{ "error": { "code": "connector_error", "message": "connector request failed" }}