Skip to navigation

Checkout sessions

Create secure, hosted payment pages that handle one-time purchases and subscriptions using Checkout Sessions.

View as Markdown

Quickstart

Choose the fastest way to create a checkout session based on your setup.

OptionWhen to use itNext steps
Using the dashboardYou want the simplest setup or are validating flows quickly.Continue to Using the dashboard (no-code) →
Using the APIYou need programmatic control or want to integrate Checkout into an existing flow.Continue to Using the API →

Using the dashboard (no-code)

Create and share a checkout session directly from the PaymentKit dashboard:

2

Click Create Checkout Session

3

Configure session details

Configure the following session details:

  • Customer (optional): Select an existing customer
  • Expires In (Hours): Set expiration time (default: 24 hours)
  • Success URL: URL to redirect customers after successful payment
  • Return URL: URL to redirect customers if they cancel
  • Line Items: Add one or more prices with quantities. Each line item consists of a price (linked to a product) and a quantity.

Using the API

Create a checkout session programmatically:

curl -X POST https://app.paymentkit.com/api/{account_id}/checkout-sessions \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"customer_id": "cus_abc123",
"line_items": [
{
"price_id": "price_xyz",
"quantity": 1
}
],
"success_url": "https://yoursite.com/success",
"return_url": "https://yoursite.com/cancel"
}'

The response includes a CheckoutSession object with an id and secure_token. Use the secure_token to construct the hosted checkout page URL and redirect the customer to begin checkout.

How checkout sessions work

POST /api/{account_id}/checkout-sessions CheckoutSession response (id, secure_token, etc.) Redirect to hosted checkout page Access hosted checkout page Complete payment Redirect to success_url Your Server PaymentKit Customer

Customizing checkout

Link the checkout session to an existing customer:

curl -X POST https://app.paymentkit.com/api/{account_id}/checkout-sessions \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"customer_id": "cus_abc123",
"success_url": "https://yoursite.com/success",
"return_url": "https://yoursite.com/settings"
}'

Apply a promotion code to the checkout session:

curl -X POST https://app.paymentkit.com/api/{account_id}/checkout-sessions \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"promotion_code": "SAVE20",
"line_items": [{"price_id": "price_xyz", "quantity": 1}],
"success_url": "https://yoursite.com/success",
"return_url": "https://yoursite.com/cancel"
}'

Or apply a coupon directly by ID:

curl -X POST https://app.paymentkit.com/api/{account_id}/checkout-sessions \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"coupon_id": "coupon_dev_abc123",
"line_items": [{"price_id": "price_xyz", "quantity": 1}],
"success_url": "https://yoursite.com/success",
"return_url": "https://yoursite.com/cancel"
}'

Configure where customers go after checkout:

URLDescription
success_urlDestination after successful checkout
return_urlDestination if the customer cancels checkout

Include the checkout session ID to verify the result: https://yoursite.com/success?session_id={CHECKOUT_SESSION_ID}

Checkout sessions expire after 24 hours by default. You can configure a custom expiration time using expires_in_hours:

curl -X POST https://app.paymentkit.com/api/{account_id}/checkout-sessions \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"expires_in_hours": 48,
"line_items": [{"price_id": "price_xyz", "quantity": 1}],
"success_url": "https://yoursite.com/success",
"return_url": "https://yoursite.com/cancel"
}'

When the checkout’s customer (the session’s customer_id, or an existing customer matched by email) holds a credit balance, the balance is applied to the invoice at checkout and the customer pays the remainder. Set apply_customer_balance to false to leave the credit untouched for a later purchase, for example when a promo code should not stack with a referral credit. The customer then pays the full amount after any coupon. Only credit is skipped: if the customer owes you money (a negative balance), it is handled exactly as on a session without this flag.

curl -X POST https://app.paymentkit.com/api/{account_id}/checkout-sessions \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"customer_id": "cus_xyz",
"apply_customer_balance": false,
"promotion_code": "WELCOME20",
"line_items": [{"price_id": "price_xyz", "quantity": 1}],
"success_url": "https://yoursite.com/success",
"return_url": "https://yoursite.com/cancel"
}'

The flag is fixed when the session is created. An update request that sends it returns a 422 error; create a new session to change it. It only affects the invoice created from this session: a subscription started from it applies the balance to its renewals as usual. With a free trial, the session’s invoice is $0 and the first paid invoice comes after the trial, so that invoice applies the balance. The session and its invoice both report the value as apply_customer_balance.

Attach custom fields for internal tracking:

curl -X POST https://app.paymentkit.com/api/{account_id}/checkout-sessions \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"custom_fields": {
"order_id": "order_12345",
"campaign": "halloween_sale"
},
"line_items": [{"price_id": "price_xyz", "quantity": 1}],
"success_url": "https://yoursite.com/success",
"return_url": "https://yoursite.com/cancel"
}'

Custom fields are included in webhooks and retrievable from the API when expand=custom_fields is specified.

A checkout that includes a recurring price with a free trial creates the subscription in trialing state. The first invoice is $0, the card is saved, and the first charge happens when the trial ends.

By default the session uses the trial set on the price (Free trial for N days in the product catalog). When several line items carry a trial, the shortest one applies. A basket that also holds a one-time price (a setup fee, say) takes no trial by default, because a trial makes the whole first invoice $0 and that one-time line would never be charged — send free_trial_days explicitly if you want it anyway. Set free_trial_days to use a different length, or 0 to skip the trial for this session:

curl -X POST https://app.paymentkit.com/api/{account_id}/checkout-sessions \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"free_trial_days": 14,
"line_items": [{"price_id": "price_xyz", "quantity": 1}],
"success_url": "https://yoursite.com/success",
"return_url": "https://yoursite.com/cancel"
}'

The response reports the trial the session will apply in free_trial_days (null when there is none). Adding a line item to the session works the trial out again with the same rules, so adding a setup fee removes a default trial. A free_trial_days you sent on create still applies. A trial needs at least one recurring price and is not available in setup mode. With cascade pricing only the first tier sets the trial length, because the fallback tiers are decline fallbacks. A trialing checkout stays $0 on whichever tier pays for it, as long as that tier has a recurring price. A tier with only one-time prices creates no subscription, so it is charged in full. A fallback tier that holds a one-time price also stops the default trial, for the same reason as a one-time line in the first tier.

Use params_for_sub to pass parameters to the subscription created by the checkout session. Currently supports custom_fields, which are validated against subscription custom field definitions (not checkout session ones).

curl -X POST https://app.paymentkit.com/api/{account_id}/checkout-sessions \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"line_items": [{"price_id": "price_xyz", "quantity": 1}],
"params_for_sub": {
"custom_fields": {
"tier": "enterprise",
"region": "us-east"
}
},
"success_url": "https://yoursite.com/success",
"return_url": "https://yoursite.com/cancel"
}'

After the checkout completes, these custom fields appear on the created subscription and are retrievable via the API with expand=custom_fields.

Override the default processor route for card checkout:

curl -X POST https://app.paymentkit.com/api/{account_id}/checkout-sessions \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"processor_route_id": "proute_dev_x7k9m2n4",
"line_items": [{"price_id": "price_xyz", "quantity": 1}],
"success_url": "https://yoursite.com/success",
"return_url": "https://yoursite.com/cancel"
}'

Configure fallback pricing tiers for cascade pricing. If the primary tier fails, the system automatically tries the next tier:

curl -X POST https://app.paymentkit.com/api/{account_id}/checkout-sessions \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"line_items": [{"price_id": "price_premium", "quantity": 1}],
"cascade_line_items": [
{
"line_items": [{"price_id": "price_standard", "quantity": 1}],
"processor_route_id": null
},
{
"line_items": [{"price_id": "price_basic", "quantity": 1}],
"processor_route_id": "proute_dev_fallback"
}
],
"success_url": "https://yoursite.com/success",
"return_url": "https://yoursite.com/cancel"
}'
Best practices
  • Always verify payments using the API or webhooks.
  • Use webhooks for fulfillment instead of redirects.
  • Handle expired sessions by creating a new session when needed.
  • Pre-fill customer details to reduce friction and improve conversion.