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 or Setup Intent.
What a Checkout Session does
A Checkout Session coordinates the customer-facing part of a payment or setup flow.
| Mode | What it does | Related resource |
|---|---|---|
payment |
Collects payment details and completes a one-time payment. | Payment Intent |
setup |
Collects and saves a payment method for future use without charging now. | Setup Intent |
subscription |
Reserved for subscription checkout flows. | Subscription |
In payment mode, Checkout creates or confirms the underlying Payment Intent. In setup mode, Checkout uses a Setup Intent to save a payment method.
Hosted, embedded, and custom UI modes
Checkout Sessions support different UI modes:
| UI mode | Use when |
|---|---|
hosted |
You want to redirect the customer to a Paypercut-hosted payment page. |
embedded |
You want to render Checkout inside your own page while Paypercut still controls the payment form. |
custom |
You need a more customized client integration that still uses Checkout Session state. |
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:
| Field | Purpose |
|---|---|
mode |
Selects whether the session collects a payment or saves a payment method. |
ui_mode |
Selects hosted, embedded, or custom rendering. |
currency |
Currency used for the checkout amount. |
line_items |
Products or services shown to the customer. |
success_url |
Where hosted Checkout sends the customer after completion. |
cancel_url |
Where hosted Checkout sends the customer if they cancel. |
return_url |
Where redirect-based payment methods return after authentication. |
customer |
Existing Paypercut Customer, when known. |
customer_email |
Email used to prefill or create customer data. |
client_reference_id |
Your own order, cart, customer, or session reference for reconciliation. |
payment_intent_data |
Payment Intent options such as capture_method or setup_future_usage. |
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 subscriptions because a recurring Price defines the amount, currency, billing interval, and usage model.
Payment options
Use payment_intent_data to configure the Payment Intent created by Checkout.
Common examples:
| Goal | Field |
|---|---|
| Authorize now and capture later | payment_intent_data.capture_method=manual |
| Prepare the payment method for future use | payment_intent_data.setup_future_usage |
| Attach an existing customer | customer |
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.
After completion
A Checkout Session has two status fields:
| Field | Meaning |
|---|---|
status |
The checkout session lifecycle, such as open, complete, or expired. |
payment_status |
Whether payment is paid, unpaid, processing, or no_payment_required. |
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.
