UseePay Checkout Session Usage Guide#
Product Illustration#
Table of Contents#
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.4. Create and Mount Payment Element#
5. Load Actions and Confirm Payment#
Complete Flow Diagram#
Flow Description#
1.
Server Creates Session: Merchant server calls UseePay API to create Checkout Session, obtaining checkoutSessionId and clientSecret
2.
Frontend Initialization: Frontend initializes SDK with publishable key and initializes Checkout with Session credentials
3.
Create Payment Element: Call createPaymentElement() to create payment form component
4.
Mount to Page: Mount payment element to specified DOM container
5.
Load Actions Object: Call loadActions() to get payment action methods
6.
User Action: User fills in payment information (card number, expiration date, etc.)
7.
Confirm Payment: Call actions.confirm() to submit payment
8.
3DS Verification (if required): SDK automatically handles 3D Secure verification flow
9.
Return Result: After payment completion, return result for frontend to handle accordingly
API Reference#
UseePay(apiKey)#
Initialize UseePay SDK instance.| Parameter | Type | Required | Description |
|---|
apiKey | string | ✅ | Publishable key, format: UseePay_PK_*** or UseePay_PK_TEST_*** |
Returns: UseePay instance
useepay.initCheckout(options)#
Initialize Checkout Session.| 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 instancecheckoutSessionId 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 instanceEach 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.| Parameter | Type | Required | Description |
|---|
domId | string | ✅ | DOM element ID (without # prefix) |
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()#
Element is removed from DOM after unmounting
Can call mount() again to remount
checkout.loadActions()#
Load payment actions object.Returns: Promise<LoadActionsResult>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: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
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.