Create Checkout Session
Create a hosted checkout session and redirect your customer to pay.
POST
/checkout-sessionsCreates a new checkout session with an auto-created Payment Intent. Returns a hosted checkout URL for customer redirect.
Requires an Idempotency-Key header. Use a UUID — if your request fails mid-flight, you can safely retry.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
mode | string | Yes | "payment" to collect a payment |
amount | integer | Yes | Amount in smallest currency unit (e.g. 5000 = $50.00) |
currency | string | Yes | ISO 4217 code: "USD", "EUR", "TTD", etc. |
return_url | string | No | Where to redirect after success. Must be HTTPS. |
cancel_url | string | No | Where to redirect on cancel. Must be HTTPS. |
description | string | No | For receipts and your reference. Max 500 chars. |
metadata | object | No | Your key-value pairs. Max 50 keys. |
line_items | array | No | Itemized breakdown. If used with amount, totals must match. |
expires_in | integer | No | TTL in seconds. Default 1800 (30 min). Range: 300–86400. |
customer_email | string | No | Pre-fill email on checkout page. |
capture_method | string | No | "automatic" (default) or "manual" for auth-then-capture. |
Line Items
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Display name. Max 200 chars. |
quantity | integer | Yes | Number of units. Min 1. |
unit_amount | integer | Yes | Price per unit in smallest currency unit. |
description | string | No | Item description. Max 500 chars. |
Response 200
{
"id": "cs_01JQXYZ...",
"object": "checkout_session",
"status": "open",
"mode": "payment",
"amount": 5000,
"currency": "USD",
"url": "https://pay.cxpay.net/cs/cs_01JQXYZ...",
"client_secret": "pi_01JQ..._secret_abc123",
"payment_intent": "pi_01JQ...",
"return_url": "https://yoursite.com/success",
"cancel_url": "https://yoursite.com/cancel",
"metadata": { "order_id": "ORD-123" },
"expires_at": "2026-04-07T19:00:00.000Z",
"livemode": false,
"created_at": "2026-04-07T18:30:00.000Z"
}| Field | Description |
|---|---|
id | Checkout session ID (cs_...) |
url | Redirect your customer here. This is the hosted payment page. |
payment_intent | PI ID — use this to check payment status later. |
client_secret | For SDK/embedded use. Ignore if using hosted checkout. |
status | open → complete or expired or canceled |
livemode | true = real money. false = test mode. |
Errors
| Status | Meaning |
|---|---|
400 | Bad request — missing fields, invalid currency, line items don't sum to amount |
401 | Auth failed — bad signature, expired timestamp, invalid key |
409 | Idempotency conflict — same key but different body |
429 | Rate limited — slow down |
Try It
POST
/checkout-sessionstest