Create Checkout Session | PaymentKit

Create a new checkout session with line items. Works for both User and API Key authentication. Account access is automatically validated via endpoint dependency.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

account_idstringRequired

Request

This endpoint expects an object.

success_urlstringRequired

URL to redirect to on success

return_urlstringRequired

URL to return to on cancellation

modeanyOptional

Checkout session mode. 'payment' charges for line items, 'setup' saves a payment method without charging.

customer_idstring or nullOptional

Customer identifier

expires_in_hoursintegerOptionalDefaults to 24

Number of hours until the checkout session expires

line_itemslist of objectsOptional

List of line items

coupon_idstring or nullOptional

ID of the coupon to apply to this checkout session

promotion_codestring or nullOptional

Promotion code to use for applying a coupon discount

card_checkout_settingsobject or nullOptional

Settings for card checkout behavior (parallel setup, 3DS mode). Defaults apply if not provided.

processor_route_idstring or nullOptional

ID of a processor route to use for card checkout (overrides account default). A processor route contains an ordered list of processors tried sequentially as a fallback chain. Pass a single route ID — to use multiple processors, define them within the route itself.

custom_fieldsmap from strings to any or nullOptional

Custom field values to set on this checkout session. Keys must match defined field keys for the checkout_session entity type. Set a key to null to delete that field’s value.

cascade_line_itemslist of objects or nullOptional

List of fallback tiers for cascade pricing (max 10 tiers). Each tier contains line items and optional processor route.

setup_preferencesobject or nullOptional

Preferences for payment method setup. Valid in both ‘payment’ and ‘setup’ modes. Contains per-processor setup configuration under ‘processors’ key.

params_for_subobject or nullOptional

Parameters to pass to the subscription when created from this checkout session.

Response

Successful Response

idstring

Unique checkout session identifier

account_idstring

Account identifier

secure_tokenstring

Secure token for accessing the checkout session

expires_in_hoursinteger

Number of hours until the checkout session expires

completedboolean

Whether the checkout session has been completed

stateenum

Computed state of the checkout session

Allowed values:

is_expiredboolean

Whether the checkout session has expired

success_urlstring

URL to redirect to on success

return_urlstring

URL to return to on cancellation

card_tokenization_modeenum

Card tokenization mode: ‘direct’ (KMS encryption) or ‘vgs’ (VGS Collect + proxy)

Allowed values:

created_atdatetime

When the checkout session was created

updated_atdatetime

When the checkout session was last updated

customer_idstring or null

Customer identifier

customer_emailstring or null

Customer email address

line_itemslist of objects or null

List of line items in the checkout session

coupon_idstring or null

ID of the coupon applied to this checkout session

promotion_codestring or null

Promotion code used to apply the coupon

card_checkout_settingsobject or null

Settings for card checkout behavior (parallel setup, 3DS mode)

cascade_statusobject or null

Cascade pricing status (None if no cascade configured)

cascade_tierslist of objects or null

Full cascade tier details including processor routes (None if no cascade configured)

processor_route_idstring or null

ID of the processor route used for card checkout. A processor route contains an ordered list of processors tried sequentially as a fallback chain. This is a single route ID, not an array — to use multiple processors, define them within the route itself.

modeany or null

Checkout session mode

setup_preferencesmap from strings to any or null

Preferences for payment method setup

custom_fieldsmap from strings to any or null

Custom field values. Only included when expand=custom_fields is specified.

params_for_subobject or null

Parameters to pass to the subscription when created from this checkout session.

1	curl -X POST https://app.paymentkit.com/api/account_id/checkout-sessions/ \
2	-H "Authorization: Bearer <token>" \
3	-H "Content-Type: application/json" \
4	-d '{
5	"success_url": "https://example.com/success",
6	"return_url": "https://example.com/return"
7	}'

1	{
2	"id": "cs_dev_x7k9m2n4p8q1",
3	"account_id": "acc_dev_x7k9m2n4p8q1",
4	"secure_token": "tok_abc123xyz789",
5	"expires_in_hours": 24,
6	"completed": false,
7	"state": "open",
8	"is_expired": false,
9	"success_url": "https://example.com/success",
10	"return_url": "https://example.com/return",
11	"card_tokenization_mode": "direct",
12	"created_at": "2024-01-15T09:30:00Z",
13	"updated_at": "2024-01-15T09:30:00Z",
14	"customer_id": "user_dev_x7k9m2n4p8q1",
15	"customer_email": "taylor@example.com",
16	"line_items": [
17	{
18	"id": "csli_dev_x7k9m2n4p8q1",
19	"product_id": "product_dev_x7k9m2n4",
20	"price_id": "price_dev_x7k9m2n4",
21	"quantity": 1,
22	"created_at": "2024-01-15T09:30:00Z",
23	"updated_at": "2024-01-15T09:30:00Z",
24	"description": "Premium subscription plan"
25	}
26	],
27	"coupon_id": "coupon_dev_x7k9m2n4",
28	"promotion_code": "SAVE20",
29	"card_checkout_settings": {
30	"three_ds_mode": "prefer_non_3ds"
31	},
32	"cascade_status": {
33	"total_tiers": 3,
34	"tier_amounts": [
35	10000,
36	8000,
37	5000
38	]
39	},
40	"cascade_tiers": [
41	{
42	"line_items": [
43	{
44	"price_id": "price_dev_x7k9m2n4",
45	"quantity": 1,
46	"description": "Fallback subscription plan"
47	}
48	],
49	"processor_route_id": "proute_dev_x7k9m2n4"
50	}
51	],
52	"processor_route_id": "proute_dev_x7k9m2n4",
53	"setup_preferences": {},
54	"custom_fields": {},
55	"params_for_sub": {
56	"custom_fields": {}
57	}
58	}

Authentication

Path parameters

Request

Response

Errors