Get Checkout Session

GET

/api/:account_id/checkout-sessions/:external_id

GET

/api/:account_id/checkout-sessions/:external_id

$ curl https://app.paymentkit.com/api/account_id/checkout-sessions/external_id \
>      -H "Authorization: Bearer <token>"

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       "inline_route": {
51         "processors": [
52           {
53             "processor_id": "proc_dev_stripe"
54           }
55         ],
56         "name": "string",
57         "description": "string"
58       }
59     }
60   ],
61   "processor_route_id": "proute_dev_x7k9m2n4",
62   "inline_route": {
63     "processors": [
64       {
65         "processor_id": "proc_dev_stripe"
66       }
67     ],
68     "name": "string",
69     "description": "string"
70   },
71   "setup_preferences": {},
72   "custom_fields": {},
73   "params_for_sub": {
74     "custom_fields": {}
75   },
76   "statement_descriptor_suffix": "string"
77 }

Get checkout session by ID (authenticated).

Works for both User and API Key authentication. Account access is automatically validated via endpoint dependency.

Pass expand=custom_fields to include the session’s custom fields.

Authentication

AuthorizationBearer

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

Path parameters

external_idstringRequired

account_idstringRequired

Query parameters

expandlist of strings or nullOptional

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

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)

created_atdatetime

When the checkout session was created

updated_atdatetime

When the checkout session was last updated

customer_idstring or nullOptional

Customer identifier

customer_emailstring or nullOptional

Customer email address

line_itemslist of objectsOptional

List of line items in the checkout session

coupon_idstring or nullOptional

ID of the coupon applied to this checkout session

promotion_codestring or nullOptional

Promotion code used to apply the coupon

card_checkout_settingsobjectOptional

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

cascade_statusobject or nullOptional

Cascade pricing status (None if no cascade configured)

cascade_tierslist of objects or nullOptional

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

processor_route_idstring or nullOptional

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.

inline_routeobject or nullOptional

Inline processor route defined directly on this session. Contains the ordered list of processors to try as a fallback chain. Null if a predefined processor_route_id is used instead, or if no route is configured.

modeanyOptional

Checkout session mode

setup_preferencesmap from strings to any or nullOptional

Preferences for payment method setup

custom_fieldsmap from strings to any or nullOptional

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

params_for_subobject or nullOptional

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

statement_descriptor_suffixstring or nullOptional

Statement descriptor suffix for this checkout session. Applied to the charge made from this session and copied onto any subscription created from it, so renewals inherit it. Null when not set.

Errors

422

Unprocessable Entity Error