Hosted Pages

Checkout sessions

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

View as MarkdownOpen in Claude

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://api.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

Customizing checkout

Link the checkout session to an existing customer:

$curl -X POST https://api.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://api.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://api.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://api.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"
>}'

Attach custom fields for internal tracking:

$curl -X POST https://api.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.

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://api.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://api.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://api.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.