***

title: Checkout sessions
subtitle: >-
Create secure, hosted payment pages that handle one-time purchases and
subscriptions using Checkout Sessions.
--------------------------------------

# 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-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-api)**                               |

***

# Using the dashboard (no-code)

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

<Steps>
  <Step title="Navigate to Checkout Sessions from the sidebar" toc={false}>
    Click the Transactions section icon, then select Checkout Sessions.
  </Step>

  <Step title="Click Create Checkout Session" toc={false} />

  <Step title="Configure session details" toc={false}>
    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.
  </Step>

  <Step title="Copy and share the checkout session link">
    After creating the session, copy the secure token from the session details. Use this token with PaymentKit.js to initialize the checkout flow, or share the complete checkout URL with your customer.
  </Step>
</Steps>

***

# Using the API

Create a checkout session programmatically:

```bash
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

```mermaid
sequenceDiagram
    participant Server as Your Server
    participant PK as PaymentKit
    participant Customer

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

## Customizing checkout

<AccordionGroup>
  <Accordion title="Pre-fill customer information">
    Link the checkout session to an existing customer:

    ```bash
    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"
    }'
    ```
  </Accordion>

  <Accordion title="Apply a promotion code">
    Apply a promotion code to the checkout session:

    ```bash
    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:

    ```bash
    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"
    }'
    ```
  </Accordion>

  <Accordion title="Redirect URLs">
    Configure where customers go after checkout:

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

    <Callout intent="info">
      Include the checkout session ID to verify the result: `https://yoursite.com/success?session_id={CHECKOUT_SESSION_ID}`
    </Callout>
  </Accordion>

  <Accordion title="Session expiration">
    Checkout sessions expire after 24 hours by default. You can configure a custom expiration time using `expires_in_hours`:

    ```bash
    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"
    }'
    ```
  </Accordion>

  <Accordion title="Attach custom fields">
    Attach custom fields for internal tracking:

    ```bash
    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.
  </Accordion>

  <Accordion title="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).

    ```bash
    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`.
  </Accordion>

  <Accordion title="Configure processor route">
    Override the default processor route for card checkout:

    ```bash
    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"
    }'
    ```
  </Accordion>

  <Accordion title="Cascade pricing">
    Configure fallback pricing tiers for cascade pricing. If the primary tier fails, the system automatically tries the next tier:

    ```bash
    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"
    }'
    ```
  </Accordion>
</AccordionGroup>

<Callout intent="launch" title="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.
</Callout>