Quickstart

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

Option	When to use it	Next steps
Using the dashboard	You want the simplest setup or are validating flows quickly.	Continue to Using the dashboard (no-code) →
Using the API	You 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:

Click Create Checkout Session

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

Customizing checkout

Pre-fill customer information

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

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"
}'

Redirect URLs

Configure where customers go after checkout:

URL	Description
`success_url`	Destination after successful checkout
`return_url`	Destination if the customer cancels checkout

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

Session expiration

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"
}'

Attach custom fields

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.

Pass parameters to the subscription

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.

Configure processor route

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"
}'

Cascade pricing

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.