💳 Checkout Session Guide

📖 Overview

Checkout Session is a unified payment session object that simplifies the payment integration process. It supports both one-time payments and subscription payments, providing a seamless payment experience for merchants and customers.

✨ Key Features

🎯 Unified Payment Interface - Single API for both one-time and subscription payments

🔄 Automatic Object Creation - Automatically creates PaymentIntent, Subscription, and Invoice

💰 Flexible Pricing - Support for discount periods, trial periods, and promotional pricing

🔐 Secure Payment Flow - Built-in security with client secrets and session expiration

📊 Real-time Status Tracking - Monitor payment progress through session status

🌍 Multi-currency Support - Accept payments in multiple currencies

API	URL
create session	https://docs-v2.useepay.com/405702890e0
element	https://docs-v2.useepay.com/8034530m0

🏗️ Object Relationships

Payment Mode (One-time Payment)

Subscription Mode (Recurring Payment)

Complete Object Relationship Diagram

📋 Object Relationship Table

Object	Created By	Purpose	Lifecycle
Checkout Session	Merchant API call	Payment session container	24 hours (default)
Subscription	Checkout Session (subscription mode)	Recurring billing configuration	Until canceled
Invoice	Subscription	Individual billing period	Per period
Payment Intent	Checkout Session or Invoice	Actual payment execution	Single use

🔄 Status Flow

Checkout Session Status Flow

Payment Status Flow

Combined Status Flow (Session + Payment)

📊 Status Combinations

Session Status	Payment Status	Description	Next Action
`open`	`unpaid`	🟡 Awaiting payment	Customer needs to confirm payment
`complete`	`paid`	✅ Payment succeeded	No action needed
`expired`	`unpaid`	⏰ Session expired	Create new session

🎯 Use Cases

1️⃣ One-time Payment

Scenario: Customer purchases a product for $99.99

{
  "mode": "payment",
  "amount": 99.99,
  "currency": "USD",
  "line_items": [...]
}

Flow:

Create Checkout Session

Customer enters payment details

Confirm payment → Creates PaymentIntent

Payment succeeds → Session status: complete

2️⃣ Subscription (No Discount)

Scenario: Customer subscribes to a monthly plan at $99.99/month

{
  "mode": "subscription",
  "amount": 99.99,
  "currency": "USD",
  "subscription_data": {},
  "collection_method": "auto_charge",
  "line_items": [{
    "price_data": {
      "recurring": {
        "interval": "month",
        "interval_count": 1
      }
    }
  }]
}

Flow:

Create Checkout Session

Confirm payment → Creates:

Subscription (recurring: $99.99/month)

Invoice #1 (amount: $99.99)

PaymentIntent (amount: $99.99)

Payment succeeds → Session status: complete

Future billing: System auto-creates Invoice #2, #3... at $99.99 each month

collection_method is empty (Merchant-managed subscription)

If collection_method is empty / not provided, it means the merchant maintains the subscription lifecycle by themselves.

In this mode:

Checkout Session is still used as a unified checkout container.

For the initial confirmation, the system still creates objects in order:

Subscription → Invoice → PaymentIntent

The difference is future billing is not automatically triggered by the system.

The merchant triggers renewals when needed:

The merchant creates a new billing period by calling our Invoice API (with subscription_id)

Then calls invoice.pay to charge the customer for that invoice

The merchant is responsible for subscription lifecycle management (schedule, cancel/pause/resume, retries, etc.).

3️⃣ Subscription with Discount Period

Scenario: First month

0.01, t h e n

99.99/month

{
  "mode": "subscription",
  "amount": 99.99,
  "currency": "USD",
  "subscription_data": {
    "discount_period_config": {
      "discount_period_count": 1,
      "discount_period_amount": 0.01
    }
  },
  "collection_method": "auto_charge"
}

Flow:

Create Checkout Session

Confirm payment → Creates:

Subscription (recurring:

99.99/ m o n t h, d i sco u n t : 1 p er i o d @

0.01)

Invoice #1 (amount: $0.01 - discount period)

PaymentIntent (amount: $0.01)

Payment succeeds → Session status: complete

Month 2+: System auto-creates Invoice #2, #3... at $99.99 each month

Pricing Timeline:

🔐 Security Features

Client Secret

Each Checkout Session has a unique client_secret for secure access:

{
  "id": "cs_1A2B3C4D5E6F7G8H",
  "client_secret": "cs_1A2B3C4D5E6F7G8H_secret_abc123"
}

Usage: Pass client_secret when confirming payment to ensure only authorized clients can complete the transaction.

Session Expiration

Default: 24 hours from creation

Purpose: Prevent stale sessions and reduce security risks

Behavior: Expired sessions cannot be confirmed

📝 API Workflow

Complete Payment Flow (Sequence Diagram)

Payment Mode Flow (Flowchart)

🎨 Best Practices

✅ DO

✅ Set appropriate expiration time - Default 24 hours is suitable for most cases

✅ Store session_id - Save it in your database for status tracking

✅ Use metadata - Pass custom data that will be propagated to Subscription/Invoice

✅ Validate amounts - Ensure line_items total matches the session amount

✅ Handle webhooks - Listen for payment status changes asynchronously

❌ DON'T

❌ Don't reuse expired sessions - Create a new session instead

❌ Don't expose client_secret - Keep it secure on the client side

❌ Don't skip validation - Always validate input before creating sessions

❌ Don't hardcode prices - Use dynamic pricing from your product catalog

🔍 Troubleshooting

Common Issues

Issue	Cause	Solution
❌ "mode required"	Missing required field	Include `mode` in request
❌ "amount not equals to item lines"	Line items total ≠ amount	Recalculate line items total
❌ "subscription_data required"	Subscription mode missing config	Add `subscription_data` object
❌ "Session expired"	Session > 24 hours old	Create new session
❌ "current period start time required"	Missing subscription start time	System auto-sets (no action needed)

Quick Reference

Object	API Endpoint	Purpose
Checkout Session	`/v1/checkout/sessions`	Payment session management
Payment Intent	`/v1/payment_intents`	Execute individual payments
Subscription	`/v1/subscriptions`	Manage recurring billing
Invoice	`/v1/invoices`	Individual billing periods
Customer	`/v1/customers`	Customer management

💡 Examples

Minimal One-time Payment

{
  "mode": "payment",
  "amount": 99.99,
  "currency": "USD",
  "merchant_order_id": "order_123",
  "customer": {
    "email": "customer@example.com",
    "name": "John Doe",
    "merchant_customer_id": "cust_123"
  },
  "line_items": [{
    "quantity": 1,
    "price_data": {
      "product_data": {
        "name": "Premium Product"
      },
      "unit_amount": 99.99
    }
  }],
  "payment_method_types": ["card"]
}

Minimal Subscription

{
  "mode": "subscription",
  "amount": 99.99,
  "currency": "USD",
  "merchant_order_id": "sub_123",
  "customer": {
    "email": "subscriber@example.com",
    "name": "Jane Smith",
    "merchant_customer_id": "cust_456"
  },
  "line_items": [{
    "quantity": 1,
    "price_data": {
      "product_data": {
        "name": "Monthly Plan"
      },
      "unit_amount": 99.99,
      "recurring": {
        "interval": "month",
        "interval_count": 1
      }
    }
  }],
  "subscription_data": {},
  "collection_method": "auto_charge",
  "payment_method_types": ["card"]
}

🎓 Summary

Checkout Session is your all-in-one payment solution:

🚀 Simple Integration - One API for all payment types

🔄 Automatic Management - Handles object creation and lifecycle

💰 Flexible Billing - Support for discounts, trials, and promotions

📊 Real-time Tracking - Monitor payment status in real-time

🔐 Enterprise Security - Built-in security features

Start accepting payments in minutes with Checkout Session! 🎉

Checkout Session Guide

💳 Checkout Session Guide#

📖 Overview#

✨ Key Features#

🏗️ Object Relationships#

Payment Mode (One-time Payment)#

Subscription Mode (Recurring Payment)#

Complete Object Relationship Diagram#

📋 Object Relationship Table#

🔄 Status Flow#

Checkout Session Status Flow#

Payment Status Flow#

Combined Status Flow (Session + Payment)#

📊 Status Combinations#

🎯 Use Cases#

1️⃣ One-time Payment#

2️⃣ Subscription (No Discount)#

collection_method is empty (Merchant-managed subscription)#

3️⃣ Subscription with Discount Period#

🔐 Security Features#

Client Secret#

Session Expiration#

📝 API Workflow#

Complete Payment Flow (Sequence Diagram)#

Payment Mode Flow (Flowchart)#

🎨 Best Practices#

✅ DO#

❌ DON'T#

🔍 Troubleshooting#

Common Issues#

📚 Related Objects#

Quick Reference#

💡 Examples#

Minimal One-time Payment#

Minimal Subscription#

🎓 Summary#

💳 Checkout Session Guide

📖 Overview

✨ Key Features

🏗️ Object Relationships

Payment Mode (One-time Payment)

Subscription Mode (Recurring Payment)

Complete Object Relationship Diagram

📋 Object Relationship Table

🔄 Status Flow

Checkout Session Status Flow

Payment Status Flow

Combined Status Flow (Session + Payment)

📊 Status Combinations

🎯 Use Cases

1️⃣ One-time Payment

2️⃣ Subscription (No Discount)

collection_method is empty (Merchant-managed subscription)

3️⃣ Subscription with Discount Period

🔐 Security Features

Client Secret

Session Expiration

📝 API Workflow

Complete Payment Flow (Sequence Diagram)

Payment Mode Flow (Flowchart)

🎨 Best Practices

✅ DO

❌ DON'T

🔍 Troubleshooting

Common Issues

📚 Related Objects

Quick Reference

💡 Examples

Minimal One-time Payment

Minimal Subscription

🎓 Summary