Create Checkout Session | PaymentKit

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

{
  "id": "cs_dev_x7k9m2n4p8q1",
  "account_id": "acc_dev_x7k9m2n4p8q1",
  "secure_token": "tok_abc123xyz789",
  "expires_in_hours": 24,
  "completed": false,
  "state": "open",
  "is_expired": false,
  "success_url": "https://example.com/success",
  "return_url": "https://example.com/return",
  "card_tokenization_mode": "direct",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "customer_id": "user_dev_x7k9m2n4p8q1",
  "customer_email": "taylor@example.com",
  "line_items": [
    {
      "id": "csli_dev_x7k9m2n4p8q1",
      "product_id": "product_dev_x7k9m2n4",
      "price_id": "price_dev_x7k9m2n4",
      "quantity": 1,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "description": "Premium subscription plan"
    }
  ],
  "coupon_id": "coupon_dev_x7k9m2n4",
  "promotion_code": "SAVE20",
  "card_checkout_settings": {
    "three_ds_mode": "prefer_non_3ds"
  },
  "cascade_status": {
    "total_tiers": 3,
    "tier_amounts": [
      10000,
      8000,
      5000
    ]
  },
  "cascade_tiers": [
    {
      "line_items": [
        {
          "price_id": "price_dev_x7k9m2n4",
          "quantity": 1,
          "description": "Fallback subscription plan"
        }
      ],
      "processor_route_id": "proute_dev_x7k9m2n4",
      "inline_route": {
        "processors": [
          {
            "processor_id": "proc_dev_stripe"
          }
        ],
        "name": "string",
        "description": "string"
      }
    }
  ],
  "processor_route_id": "proute_dev_x7k9m2n4",
  "inline_route": {
    "processors": [
      {
        "processor_id": "proc_dev_stripe"
      }
    ],
    "name": "string",
    "description": "string"
  },
  "setup_preferences": {},
  "custom_fields": {},
  "params_for_sub": {
    "custom_fields": {}
  },
  "statement_descriptor_suffix": "string"
}

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_hoursinteger or nullOptional

Number of hours until the checkout session expires. When omitted, the account’s configured checkout session expiration (checkout_settings.session_expiration_minutes) is used.

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.

inline_routeobject or nullOptional

Define processors directly on this session instead of referencing a predefined route. The processors are tried in order as a fallback chain. Mutually exclusive with processor_route_id — set one or the other, not both. Use this for one-off routing configurations; use processor_route_id for reusable routes shared across sessions.

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.

statement_descriptor_suffixstring or nullOptional

Statement descriptor suffix for this checkout session. Overrides the default descriptor for the charge made from this session, and is copied onto any subscription created from it so renewals inherit it. A suffix longer than the account prefix allows is trimmed to fit (the trimmed value is what this endpoint returns); an invalid suffix is rejected with 422.

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