Checkout sessions

The checkout sessions endpoints of the Kashu API, with their parameters, objects, errors and examples. The guide explains how they fit together.

Endpoint	What it does
POST `/v1/checkout_sessions`	Create a checkout session for Kashu.js to take payment for. The response is the only place its client secret appears.
GET `/v1/checkout_sessions`	List checkout sessions, newest first.
GET `/v1/checkout_sessions/{id}`	Retrieve a checkout session.
POST `/v1/checkout_sessions/{id}/expire`	Expire an open checkout session now, so it takes no payment. A session whose payment is in flight or made cannot be expired.
GET `/v1/checkout_sessions/{id}/client`	Read what the card form shows of a session, with the publishable key and the session's client secret.
POST `/v1/checkout_sessions/{id}/pay`	Pay a checkout session with a card token. Kashu's card form calls this for you.

The checkout session object

Field	Type	About
`id`	string	An id that starts `cs_`.
`object`	string	Always `"checkout_session"`.
`status`	enum	One of `open`, `complete`, `expired`.
`payment_status`	enum	unpaid until a payment is made or after one failed; processing while one is in flight; authorized when held for capture; paid once captured. One of `unpaid`, `processing`, `authorized`, `paid`.
`amount`	integer	In the currency's minor unit, such as cents for USD. More than 0.
`currency`	string	Three capital letters, such as `USD`.
`capture_method`	enum	One of `automatic`, `manual`.
`customer`	string or null	An id that starts `cu_`.
`payment`	string or null	The latest payment made for the session. An id that starts `py_`.
`store`	string	An id that starts `st_`.
`success_url`	string
`cancel_url`	string or null
`client_secret`	string or null	For Kashu.js in the buyer's page. Shown only in the response that created the session; keep it with the order.
`expires_at`	integer	Unix seconds.
`completed_at`	integer or null	Unix seconds.
`metadata`	map of strings
`livemode`	boolean
`created`	integer	Unix seconds.

{
  "id": "cs_1a2B3c4D5e6F7g8H9i0J1k2L",
  "object": "checkout_session",
  "status": "open",
  "payment_status": "unpaid",
  "amount": 4999,
  "currency": "USD",
  "capture_method": "automatic",
  "customer": "cu_1a2B3c4D5e6F7g8H9i0J1k2L",
  "payment": "py_1a2B3c4D5e6F7g8H9i0J1k2L",
  "store": "st_1a2B3c4D5e6F7g8H9i0J1k2L",
  "success_url": "https://shop.example.com/thanks",
  "cancel_url": null,
  "client_secret": null,
  "expires_at": 1762473600,
  "completed_at": null,
  "metadata": {
    "order": "1001"
  },
  "livemode": false,
  "created": 1762473600
}

The checkout session client object

Field	Type	About
`id`	string	An id that starts `cs_`.
`object`	string	Always `"checkout_session"`.
`status`	enum	One of `open`, `complete`, `expired`.
`payment_status`	enum	unpaid until a payment is made or after one failed; processing while one is in flight; authorized when held for capture; paid once captured. One of `unpaid`, `processing`, `authorized`, `paid`.
`payment_error`	enum or null	Why the latest attempt failed, while the session is open for another. One of `card_declined`, `processing_error`.
`amount`	integer	In the currency's minor unit, such as cents for USD. More than 0.
`currency`	string	Three capital letters, such as `USD`.
`collect_email`	boolean	Whether the form asks for the buyer's email: the session names no customer.
`success_url`	string
`expires_at`	integer	Unix seconds.
`livemode`	boolean

{
  "id": "cs_1a2B3c4D5e6F7g8H9i0J1k2L",
  "object": "checkout_session",
  "status": "open",
  "payment_status": "unpaid",
  "payment_error": null,
  "amount": 4999,
  "currency": "USD",
  "collect_email": false,
  "success_url": "https://shop.example.com/thanks",
  "expires_at": 1762473600,
  "livemode": false
}

POST `/v1/checkout_sessions`

Create a checkout session for Kashu.js to take payment for. The response is the only place its client secret appears.

Scope: checkout_sessions:write
Keys: Secret, or restricted with the scope below.
Idempotency-Key: Optional. Without one, Kashu makes one and returns it. See Idempotency.
Answers: 201 with the Checkout session.

Parameters

Name	In	Type	Required	About
`Idempotency-Key`	header	string	Optional	Optional. When absent, Kashu mints one and returns it. Up to 255 characters.
`Kashu-Version`	header	string	Optional	The API version to answer in. Defaults to the key's pinned version.

Request body

Field	Type	Required	About
`amount`	integer	Required	In the currency's minor unit, such as cents for USD. More than 0. Up to 99999999.
`currency`	string	Required	Three capital letters, such as `USD`.
`success_url`	string	Required	Where Kashu.js sends the buyer once the session is paid. https; a test session may use http://localhost. Up to 2048 characters.
`cancel_url`	string	Optional	Where the buyer goes back to if they leave. The same rules as success_url. Up to 2048 characters.
`customer`	string	Optional	The buyer, if you know them. Without one the form asks for an email and makes a customer. An id that starts `cu_`.
`capture_method`	enum	Optional	One of `automatic`, `manual`.
`store`	string	Optional	An id that starts `st_`.
`expires_at`	integer	Optional	When the session stops taking payment: 30 minutes to 24 hours from now. Defaults to 24 hours. Unix seconds.
`metadata`	map of strings	Optional	Keys up to 40 characters, values up to 500.

Errors

Status	Codes
400	`invalid_json`, `parameter_missing`, `parameter_invalid`, `parameter_unknown`, `api_version_invalid`, `idempotency_key_invalid`, `idempotency_key_reused`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`, `publishable_key_not_allowed`, `payments_not_enabled`
404	`resource_missing`
409	`idempotency_key_in_use`
429	`rate_limited`
500	`api_error`

Examples

curl https://api.kashupay.com/v1/checkout_sessions \
  -H "Authorization: Bearer $KASHU_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":4999,"currency":"USD","success_url":"https://shop.example.com/thanks"}'

const checkoutSession = await kashu("POST", "/v1/checkout_sessions", {
  "amount": 4999,
  "currency": "USD",
  "success_url": "https://shop.example.com/thanks"
});
console.log(checkoutSession.status);

GET `/v1/checkout_sessions`

List checkout sessions, newest first.

Scope: checkout_sessions:read
Keys: Secret, or restricted with the scope below.
Idempotency-Key: Not used. A read changes nothing.
Answers: 200 with a list of Checkout session, newest first.

Parameters

Name	In	Type	Required	About
`status`	query	enum	Optional	One of `open`, `complete`, `expired`.
`customer`	query	string	Optional	An id that starts `cu_`.
`limit`	query	integer	Optional	At least 1. Up to 100. Defaults to `10`.
`cursor`	query	string	Optional
`Kashu-Version`	header	string	Optional	The API version to answer in. Defaults to the key's pinned version.

Errors

Status	Codes
400	`parameter_missing`, `parameter_invalid`, `parameter_unknown`, `cursor_invalid`, `cursor_expired`, `api_version_invalid`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`, `publishable_key_not_allowed`
500	`api_error`

Examples

curl "https://api.kashupay.com/v1/checkout_sessions?limit=3" \
  -H "Authorization: Bearer $KASHU_SECRET_KEY"

const list = await kashu("GET", "/v1/checkout_sessions?limit=3");
console.log(list.has_more);

GET `/v1/checkout_sessions/{id}`

Retrieve a checkout session.

Scope: checkout_sessions:read
Keys: Secret, or restricted with the scope below.
Idempotency-Key: Not used. A read changes nothing.
Answers: 200 with the Checkout session.

Parameters

Name	In	Type	Required	About
`id`	path	string	Required	An id that starts `cs_`.
`Kashu-Version`	header	string	Optional	The API version to answer in. Defaults to the key's pinned version.

Errors

Status	Codes
400	`parameter_unknown`, `api_version_invalid`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`, `publishable_key_not_allowed`
404	`resource_missing`
500	`api_error`

Examples

curl https://api.kashupay.com/v1/checkout_sessions/cs_1a2B3c4D5e6F7g8H9i0J1k2L \
  -H "Authorization: Bearer $KASHU_SECRET_KEY"

const checkoutSession = await kashu("GET", "/v1/checkout_sessions/cs_1a2B3c4D5e6F7g8H9i0J1k2L");
console.log(checkoutSession.status);

POST `/v1/checkout_sessions/{id}/expire`

Expire an open checkout session now, so it takes no payment. A session whose payment is in flight or made cannot be expired.

Scope: checkout_sessions:write
Keys: Secret, or restricted with the scope below.
Idempotency-Key: Optional. Without one, Kashu makes one and returns it. See Idempotency.
Answers: 200 with the Checkout session.

Parameters

Name	In	Type	Required	About
`id`	path	string	Required	An id that starts `cs_`.
`Idempotency-Key`	header	string	Optional	Optional. When absent, Kashu mints one and returns it. Up to 255 characters.
`Kashu-Version`	header	string	Optional	The API version to answer in. Defaults to the key's pinned version.

Request body

Send no body, or an empty JSON object.

Errors

Status	Codes
400	`invalid_json`, `parameter_unknown`, `api_version_invalid`, `idempotency_key_invalid`, `idempotency_key_reused`, `checkout_session_unexpected_state`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`, `publishable_key_not_allowed`
404	`resource_missing`
409	`idempotency_key_in_use`
429	`rate_limited`
500	`api_error`

Examples

curl https://api.kashupay.com/v1/checkout_sessions/cs_1a2B3c4D5e6F7g8H9i0J1k2L/expire \
  -X POST \
  -H "Authorization: Bearer $KASHU_SECRET_KEY"

const checkoutSession = await kashu("POST", "/v1/checkout_sessions/cs_1a2B3c4D5e6F7g8H9i0J1k2L/expire");
console.log(checkoutSession.status);

GET `/v1/checkout_sessions/{id}/client`

Read what the card form shows of a session, with the publishable key and the session's client secret.

Scope: checkout_sessions:read
Keys: Publishable, for the card form, or secret.
Idempotency-Key: Not used. A read changes nothing.
Answers: 200 with the Checkout session client.

Parameters

Name	In	Type	Required	About
`id`	path	string	Required	An id that starts `cs_`.
`client_secret`	query	string	Required	Up to 200 characters.
`Kashu-Version`	header	string	Optional	The API version to answer in. Defaults to the key's pinned version.

Errors

Status	Codes
400	`parameter_missing`, `parameter_invalid`, `parameter_unknown`, `api_version_invalid`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`
404	`resource_missing`
500	`api_error`

Examples

curl "https://api.kashupay.com/v1/checkout_sessions/cs_1a2B3c4D5e6F7g8H9i0J1k2L/client?client_secret=cs_..._secret_x" \
  -H "Authorization: Bearer $KASHU_PUBLISHABLE_KEY"

const checkoutSessionClient = await kashu("GET", "/v1/checkout_sessions/cs_1a2B3c4D5e6F7g8H9i0J1k2L/client?client_secret=cs_..._secret_x");
console.log(checkoutSessionClient.status);

POST `/v1/checkout_sessions/{id}/pay`

Pay a checkout session with a card token. Kashu's card form calls this for you.

Scope: checkout_sessions:write
Keys: Publishable, for the card form, or secret.
Idempotency-Key: Required. This endpoint moves money. See Idempotency.
Answers: 200 with the Checkout session client.

Parameters

Name	In	Type	Required	About
`id`	path	string	Required	An id that starts `cs_`.
`Idempotency-Key`	header	string	Required	Required. Retry with the same key and get the same result. Up to 255 characters.
`Kashu-Version`	header	string	Optional	The API version to answer in. Defaults to the key's pinned version.

Request body

Field	Type	Required	About
`client_secret`	string	Required	Up to 200 characters.
`token`	string	Required	A card token (tok_) from the card form. Paying spends it. An id that starts `tok_`.
`email`	string	Optional	The buyer's email, required when the session names no customer. An email address. Up to 254 characters.
`name`	string	Optional	The name on the card. Up to 200 characters.

Errors

Status	Codes
400	`invalid_json`, `parameter_missing`, `parameter_invalid`, `parameter_unknown`, `api_version_invalid`, `idempotency_key_missing`, `idempotency_key_invalid`, `idempotency_key_reused`, `token_already_used`, `token_expired`, `checkout_session_unexpected_state`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`, `payments_not_enabled`
404	`resource_missing`
409	`idempotency_key_in_use`, `operation_in_progress`
429	`rate_limited`
500	`api_error`

Examples

curl https://api.kashupay.com/v1/checkout_sessions/cs_1a2B3c4D5e6F7g8H9i0J1k2L/pay \
  -H "Authorization: Bearer $KASHU_PUBLISHABLE_KEY" \
  -H "Idempotency-Key: checkout-sessions-pay-1001" \
  -H "Content-Type: application/json" \
  -d '{"client_secret":"cs_..._secret_x","token":"tok_1a2B3c4D5e6F7g8H9i0J1k2L"}'

const checkoutSessionClient = await kashu("POST", "/v1/checkout_sessions/cs_1a2B3c4D5e6F7g8H9i0J1k2L/pay", {
  "client_secret": "cs_..._secret_x",
  "token": "tok_1a2B3c4D5e6F7g8H9i0J1k2L"
}, { idempotencyKey: "checkout-sessions-pay-1001" });
console.log(checkoutSessionClient.status);

Checkout sessions

The checkout session object

The checkout session client object

POST /v1/checkout_sessions

Parameters

Request body

Errors

Examples

GET /v1/checkout_sessions

Parameters

Errors

Examples

GET /v1/checkout_sessions/{id}

Parameters

Errors

Examples

POST /v1/checkout_sessions/{id}/expire

Parameters

Request body

Errors

Examples

GET /v1/checkout_sessions/{id}/client

Parameters

Errors

Examples

POST /v1/checkout_sessions/{id}/pay

Parameters

Request body

Errors

Examples

POST `/v1/checkout_sessions`

GET `/v1/checkout_sessions`

GET `/v1/checkout_sessions/{id}`

POST `/v1/checkout_sessions/{id}/expire`

GET `/v1/checkout_sessions/{id}/client`

POST `/v1/checkout_sessions/{id}/pay`