Checkout Sessions
A Checkout Session creates a secure, PaymentKit-hosted page to collect payment details. It's a foundational component for processing one-time payments (payment mode) and setting up recurring billing (subscription mode). A session orchestrates the entire checkout flow, from displaying line items to handling payment confirmation and redirection.
Before creating a session, you'll typically need to have configured your offerings. For more information, see the Products & Prices guide. To learn how to manage the resulting subscriptions after a successful checkout, refer to the Subscriptions guide.
The Checkout Flow#
The process involves your application's frontend and backend interacting with the PaymentKit API. The user is redirected to a hosted PaymentKit page to complete the payment, ensuring that sensitive payment information is never handled directly by your server.
Create a Checkout Session#
This creates a new Checkout Session. Once created, you can redirect your user to the url returned in the response object.
Parameters
Name | Type | Description |
|---|---|---|
|
| Required. The URL to which the customer will be redirected upon successful payment. |
|
| Required. The URL to which the customer will be redirected if they cancel the payment. |
|
| Required. An array of objects, each representing an item for purchase. See |
|
| Required. The mode of the session. Must be one of |
|
| The ID of an existing customer to associate with this session. |
|
| Data used when |
|
| A Unix timestamp (in seconds) at which the session expires. The session must be completed before this time. |
|
| A set of key-value pairs that you can attach to the object. Useful for storing additional information. |
|
| Enables the use of promotion codes on the Checkout page. |
line_items Structure
Name | Type | Description |
|---|---|---|
|
| Required. The ID of the Price object. |
|
| Required. The quantity of the price to purchase. |
subscription_data Structure
Name | Type | Description |
|---|---|---|
|
| Number of days a trial will last. |
|
| An array of custom actions to display to the user on the subscription management page. |
Example Request
import payment from '@blocklet/payment-js';
async function createSession() {
try {
const session = await payment.checkout.sessions.create({
success_url: 'https://example.com/success',
cancel_url: 'https://example.com/cancel',
mode: 'subscription',
line_items: [
{ price_id: 'price_xxx', quantity: 1 }
],
subscription_data: {
service_actions: [
{
type: 'notification',
text: { en: 'View Documentation', zh: '查看文档' },
link: 'https://docs.example.com',
triggerEvents: ['customer.subscription.started']
}
]
},
expires_at: Math.floor(Date.now() / 1000) + (60 * 30) // Expires in 30 minutes
});
console.log('Checkout Session URL:', session.url);
// Redirect your customer to session.url
} catch (error) {
console.error('Error creating checkout session:', error.message);
}
}
createSession();Example Response
{
"id": "cs_xxx",
"object": "checkout.session",
"livemode": false,
"url": "https://pay.arcblock.io/checkout/cs_xxx",
"status": "open",
"mode": "subscription",
"success_url": "https://example.com/success",
"cancel_url": "https://example.com/cancel",
"customer_id": null,
"line_items": {
"object": "list",
"data": [
{
"id": "li_xxx",
"price_id": "price_xxx",
"quantity": 1
}
]
},
"expires_at": 1729245600,
"payment_status": "unpaid"
}Retrieve a Checkout Session#
Fetches the details of a Checkout Session that has previously been created.
Parameters
Name | Type | Description |
|---|---|---|
|
| Required. The unique identifier of the Checkout Session. |
Example Request
import payment from '@blocklet/payment-js';
async function retrieveSession(sessionId) {
try {
const session = await payment.checkout.sessions.retrieve(sessionId);
console.log('Session status:', session.status);
console.log('Payment status:', session.payment_status);
} catch (error) {
console.error('Error retrieving session:', error.message);
}
}
retrieveSession('cs_xxx');Example Response
{
"id": "cs_xxx",
"object": "checkout.session",
"status": "complete",
"payment_status": "paid",
"customer_id": "cus_xxx",
"subscription_id": "sub_xxx",
"livemode": false,
"url": null,
"line_items": { ... },
"created_at": "2024-10-18T10:00:00.000Z"
}List Checkout Sessions#
Returns a paginated list of Checkout Sessions.
Parameters
Name | Type | Description |
|---|---|---|
|
| Only return sessions for the given customer ID. |
|
| Only return sessions with the given status. Can be |
|
| Only return the session for the given Payment Intent. |
|
| Only return the session for the given Subscription. |
|
| The page number for pagination. Defaults to 1. |
|
| The number of items per page. Defaults to 20. |
Example Request
import payment from '@blocklet/payment-js';
async function listCompletedSessions(customerId) {
try {
const sessions = await payment.checkout.sessions.list({
customer_id: customerId,
status: 'complete',
pageSize: 5
});
console.log(`Found ${sessions.count} completed sessions for customer.`);
sessions.list.forEach(session => {
console.log(`- Session ID: ${session.id}`);
});
} catch (error) {
console.error('Error listing sessions:', error.message);
}
}
listCompletedSessions('cus_xxx');Example Response
{
"count": 15,
"list": [
{
"id": "cs_yyy",
"object": "checkout.session",
"status": "complete",
"payment_status": "paid",
"customer_id": "cus_xxx"
},
{
"id": "cs_zzz",
"object": "checkout.session",
"status": "complete",
"payment_status": "paid",
"customer_id": "cus_xxx"
}
]
}Expire a Checkout Session#
A Checkout Session can be expired if it is still open. Once expired, it cannot be used for payment.
Parameters
Name | Type | Description |
|---|---|---|
|
| Required. The ID of the Checkout Session to expire. |
Example Request
import payment from '@blocklet/payment-js';
async function expireSession(sessionId) {
try {
const session = await payment.checkout.sessions.expire(sessionId);
console.log(`Session ${session.id} has been expired. Status: ${session.status}`);
} catch (error) {
console.error('Error expiring session:', error.message);
}
}
expireSession('cs_abc');Example Response
{
"id": "cs_abc",
"object": "checkout.session",
"status": "expired",
"payment_status": "unpaid",
"livemode": false
}Fulfilling Orders After Payment#
While redirecting the user to a success_url provides immediate feedback, it is not a secure way to fulfill an order. A customer could bookmark the success URL and access it directly without paying.
To reliably and securely manage post-payment logic, you should use Webhooks. By listening for the checkout.session.completed event, your server can receive a notification from PaymentKit when a payment is successful, allowing you to safely provision services or ship goods.
For a detailed guide, see Webhooks.
This guide has covered the lifecycle of a Checkout Session. You can now create payment pages for your customers. For a complete list of all available parameters and methods, please visit the Checkout Sessions API Reference.