UseePay Checkout Session Usage Guide

Product Illustration

Overview

Quick Start

Complete Flow Diagram

API Reference

Best Practices

FAQ

Overview

Checkout Session is a simplified payment integration method provided by UseePay SDK. By creating a Checkout Session on the server side in advance, the frontend only needs to use checkoutSessionId and clientSecret to quickly integrate payment functionality without handling complex payment parameter configurations.

Key Features

Simplified Integration: Server creates the Session, frontend only needs ID and secret

High Security: Sensitive information is configured on the server, frontend only holds temporary credentials

Centralized Management: Payment configuration, amount, currency and other information are managed uniformly on the server

Quick Start

1. Include SDK

The sdk url for the production environment has not been launched yet. Below is the address for the sandbox environment

2. Initialize UseePay

3. Initialize Checkout

checkout_session.client_secret and checkout_session.id are available after the checkout session is successfully created.

eg:

4. Create and Mount Payment Element

5. Load Actions and Confirm Payment

Complete Flow Diagram

Flow Description

Server Creates Session: Merchant server calls UseePay API to create Checkout Session, obtaining checkoutSessionId and clientSecret

Frontend Initialization: Frontend initializes SDK with publishable key and initializes Checkout with Session credentials

Create Payment Element: Call createPaymentElement() to create payment form component

Mount to Page: Mount payment element to specified DOM container

Load Actions Object: Call loadActions() to get payment action methods

User Action: User fills in payment information (card number, expiration date, etc.)

Confirm Payment: Call actions.confirm() to submit payment

3DS Verification (if required): SDK automatically handles 3D Secure verification flow

Return Result: After payment completion, return result for frontend to handle accordingly

API Reference

UseePay(apiKey)

Initialize UseePay SDK instance.

Parameters:

Parameter	Type	Required	Description
`apiKey`	`string`	✅	Publishable key, format: `UseePay_PK_*` or `UseePay_PK_TEST_*`

Returns: UseePay instance

Example:

useepay.initCheckout(options)

Initialize Checkout Session.

Parameters:

Parameter	Type	Required	Description
`options`	`InitCheckoutOptions`	✅	Checkout configuration object
`options.checkoutSessionId`	`string`	✅	Checkout Session ID, format: `cs_xxxxxxxxxxxx`
`options.clientSecret`	`string`	✅	Client secret, format: `cs_xxxxxxxxxxxx_xxxxxxxxxxxxxxx`

Returns: Checkout instance

Example:

Important Notes:

checkoutSessionId and clientSecret must be obtained from server

Each Session can only be used once, must recreate after payment completion

clientSecret has expiration time, need to recreate Session after expiration

checkout.createPaymentElement()

Create standard payment element.

Returns: PaymentElement instance

Example:

Important Notes:

Each Checkout instance can only create one Payment Element

Repeated calls will throw an error

Must call mount() method after creation to display

paymentElement.mount(domId)

Mount payment element to specified DOM element.

Parameters:

Parameter	Type	Required	Description
`domId`	`string`	✅	DOM element ID (without `#` prefix)

Returns: void

Example:

Important Notes:

DOM element must already exist on the page

Recommended to set appropriate width for container (e.g., width: 60vw)

Payment form will automatically load after mounting

paymentElement.unmount()

Unmount payment element.

Returns: void

Example:

Important Notes:

Element is removed from DOM after unmounting

Can call mount() again to remount

checkout.loadActions()

Load payment actions object.

Returns: Promise<LoadActionsResult>

LoadActionsResult Type:

Example:

Important Notes:

Must be called after creating payment element

Returned actions object contains confirm() method

Recommended to call this method when page loads

actions.confirm()

Confirm and submit payment.

Returns: Promise<{ session?: CheckoutSession; error?: Error }>

Return Value Description:

Field	Type	Description
`session`	`object`	Session object returned on successful payment
`session.checkout_session_id`	`string`	Checkout Session ID
`session.payment_status`	`string`	Payment status: `'paid'`, `'un_paid'`, etc.
`session.payment_intent_id`	`string`	Payment Intent ID for tracking payment intent
`session.payment_intent_status`	`string`	Payment Intent status
`session.status`	`string`	Overall Checkout Session status
`error`	`object`	Error information on payment failure
`error.message`	`string`	Error description
`error.type`	`string`	Error type (optional)

Complete session Object Structure:

Example:

Important Notes:

Ensure user has filled in complete payment information before calling

May trigger 3DS verification, SDK handles automatically

Do not call this method repeatedly during payment process

Best Practices

1. Security

✅ Must use HTTPS: Production environment must use HTTPS protocol

✅ Secret Management: Do not expose clientSecret in public code repositories

✅ Server Verification: Must verify payment status on server after payment completion

2. Performance Optimization

Load SDK script in advance to avoid blocking page rendering

Call loadActions() when page loads, don't wait for user to click payment button

Set appropriate container width to avoid frequent repaints

3. User Experience

Display loading state during payment process to avoid user repeated clicks

Provide clear error messages

Redirect or display success page promptly after successful payment

Do not close or refresh page during 3DS verification

4. Compatibility

Apple Pay: Only available on Safari browser and supported iOS devices

Google Pay: Requires user to be logged into Google account

Browser Requirements: Recommended to use modern browsers (Chrome 90+, Safari 14+, Firefox 88+)

5. Debugging Tips

Use test environment API Key (UseePay_PK_TEST_***) for development

Check SDK output logs in browser console

Use test card numbers for testing (obtain from UseePay documentation)

6. FAQ

Q: Can each Checkout instance create multiple Payment Elements?
A: No. Each Checkout instance can only create one Payment Element.

Q: Can Sessions be reused?
A: No. Each Session can only be used once, must recreate after payment completion.

Q: How to handle 3DS verification?
A: SDK automatically handles 3DS verification flow, no additional code needed.

Q: Can payment amount be modified on frontend?
A: No. Payment amount is determined when creating Session on server, frontend cannot modify.

Checkout Session Element

UseePay Checkout Session Usage Guide

Product Illustration

Table of Contents

Overview

Key Features

Quick Start

1. Include SDK

2. Initialize UseePay

3. Initialize Checkout

4. Create and Mount Payment Element

5. Load Actions and Confirm Payment

Complete Flow Diagram

Flow Description

API Reference

UseePay(apiKey)

useepay.initCheckout(options)

checkout.createPaymentElement()

paymentElement.mount(domId)

paymentElement.unmount()

checkout.loadActions()

actions.confirm()

Best Practices

1. Security

2. Performance Optimization

3. User Experience

4. Compatibility

5. Debugging Tips

6. FAQ

Checkout Session Element

UseePay Checkout Session Usage Guide#

Product Illustration#

Table of Contents#

Overview#

Key Features#

Quick Start#

1. Include SDK#

2. Initialize UseePay#

3. Initialize Checkout#

4. Create and Mount Payment Element#

5. Load Actions and Confirm Payment#

Complete Flow Diagram#

Flow Description#

API Reference#

UseePay(apiKey)#

useepay.initCheckout(options)#

checkout.createPaymentElement()#

paymentElement.mount(domId)#

paymentElement.unmount()#

checkout.loadActions()#

actions.confirm()#

Best Practices#

1. Security#

2. Performance Optimization#

3. User Experience#

4. Compatibility#

5. Debugging Tips#

6. FAQ#

UseePay Checkout Session Usage Guide

Product Illustration

Table of Contents

Overview

Key Features

Quick Start

1. Include SDK

2. Initialize UseePay

3. Initialize Checkout

4. Create and Mount Payment Element

5. Load Actions and Confirm Payment

Complete Flow Diagram

Flow Description

API Reference

UseePay(apiKey)

useepay.initCheckout(options)

checkout.createPaymentElement()

paymentElement.mount(domId)

paymentElement.unmount()

checkout.loadActions()

actions.confirm()

Best Practices

1. Security

2. Performance Optimization

3. User Experience

4. Compatibility

5. Debugging Tips

6. FAQ