Checkout Sessions API

Checkout Sessions are the recommended starting point for most payment integrations. A Checkout Session represents a customer-facing checkout flow that Paypercut can host or embed for you.

Use Checkout Sessions when you want Paypercut to collect payment details, handle payment method selection, run required customer authentication, and create the underlying Payment Intent, Setup Intent, or Subscription.

What a Checkout Session does

A Checkout Session coordinates the customer-facing part of a payment, setup, or subscription signup flow.

In payment mode, Checkout creates or confirms the underlying Payment Intent. In setup mode, Checkout uses a Setup Intent to save a payment method. In subscription mode, Checkout creates the Subscription from recurring line items and stores a reusable payment method for future billing cycles.

Hosted, embedded, and custom UI modes

Checkout Sessions support different UI modes:

Hosted Checkout is the simplest integration. Embedded and custom modes give more control over the page experience, but still keep sensitive payment details out of your backend.

Core fields

When creating a Checkout Session, you typically provide:

Use client_reference_id to connect the Checkout Session back to your own cart or order. Do not use it as the source of truth for payment completion; use webhooks and retrieved API objects for that.

Line items and catalog prices

Checkout line items can use catalog-backed prices or inline pricing data. Catalog-backed prices are useful when the same product or plan is sold repeatedly. Inline pricing is useful for one-off or dynamically calculated checkout amounts.

Use Products and Prices when the item should be reusable across Checkout, invoices, and subscriptions. This is especially important for subscription checkout because a recurring Price defines the amount, currency, billing interval, and usage model.

Subscription checkout

Use mode=subscription when Checkout should create the subscription, collect the first payment, and save the customer's payment method for renewal billing.

Subscription checkout uses the same line_items array as payment checkout. Pass recurring Price-backed line items for subscription plans. Use client_reference_id to connect the Checkout Session back to your signup, cart, or internal subscription record.

{
  "mode": "subscription",
  "ui_mode": "hosted",
  "currency": "EUR",
  "customer": "01HD7M6DRKZ4Q4QEVWJB0RC1S6",
  "line_items": [
    {
      "price": "01HFRECURRINGPRICE000000000",
      "quantity": 1
    }
  ],
  "success_url": "https://example.com/subscription/success",
  "cancel_url": "https://example.com/subscription/cancel",
  "client_reference_id": "signup_1042"
}

After the customer completes Checkout, use webhooks and the Checkout Session response to inspect the created Subscription. Do not rely only on the browser redirect to provision subscription access.

Update a Checkout Session

You can update an open Checkout Session to select one of the session's existing shipping rates. Use this when the customer chooses a shipping option after the session is created.

Define the available shipping options when you create the Checkout Session. The response includes resolved shipping rate IDs that can be passed to the update endpoint.

Send the selected shipping_rate to the update endpoint. Paypercut applies that shipping cost to the Checkout Session and updates the related Payment Intent amount before confirmation.

Checkout Sessions cannot be updated after payment confirmation has started. If a session is complete, expired, or already confirming, create a new Checkout Session for the next checkout attempt.

Payment options

Use payment_intent_data to configure the Payment Intent created by Checkout in payment mode.

Common examples:

For saving payment methods during a payment-mode checkout, use saved_payment_method_options.payment_method_save=enabled when you want Checkout to offer the customer an option to save a new payment method for future on-session use.

Use Checkout Session metadata for context about the checkout flow itself. Use payment_intent_data.metadata for context that should be stored on the underlying Payment Intent and included in Payment Intent webhook events. When the first Payment is created from the Payment Intent, Paypercut copies the Payment Intent metadata onto that Payment as its initial metadata snapshot. If no Payment Intent metadata is present, Paypercut uses the checkout context available at Payment creation time.

After completion

A Checkout Session has two status fields:

For order fulfillment, listen for webhook events and retrieve the related Payment Intent or Payment. Browser redirects can be interrupted and should not be the only signal used to mark an order as paid.

checkout_session.completed events include the Checkout Session metadata. Payment Intent events include the Payment Intent metadata. Payment events include the Payment metadata snapshot used for reconciliation.

API reference

• Create a Checkout Session
• Update a Checkout Session
• Retrieve a Checkout Session
• Checkout Experience
• Payment Intents
• Products and Prices