UQPay Checkout SDK

Overview

UQPay Checkout SDK is a universal payment SDK that provides seamless payment integration for all JavaScript frameworks and environments.

Key Features

1. Cross-Framework Compatibility - Works in any JavaScript environment, whether React, Vue, Angular, or vanilla JS projects
2. Multiple Integration Options - Supports both NPM package installation and direct CDN reference, accommodating different development scenarios
3. Multi-Environment Support - Provides complete environment configuration options (develop, local, testing, sandbox, demo, production) for seamless development and testing
4. Diverse Payment Methods - Supports credit cards, Alipay, WeChat Pay, Apple Pay, Google Pay, and other payment methods
5. Event Listening System - Comprehensive event system to monitor payment success, failure, and other status changes
6. Security - Supports client-side secret verification to ensure payment process security
7. Responsive Design - Adapts to different device screen sizes, providing an excellent mobile experience
8. Lightweight - The built SDK has a small footprint that won't significantly increase your application's loading time
9. Node.js Compatible - Supports server-side URL generation for Node.js environments

Supported Payment Methods

• Card
• Alipay
• WeChat Pay
• UnionPay
• And more...

📦 Installation

NPM Installation

npm install @uqpay/checkout-sdk

CDN Usage

<script src="https://unpkg.com/@uqpay/checkout-sdk/dist/uqpay-checkout-sdk.min.js"></script>
<script>
  // After script loads, UQPayCheckout is available globally
  const { init, createElement, generatePaymentUrl, redirectToCheckout } = UQPayCheckout;
  
  // Example: Using redirectToCheckout directly (simplified API)
  async function redirectToPayment() {
    await redirectToCheckout({
      env: "production", // 'develop' | 'local' | 'testing' | 'sandbox' | 'demo' | 'production'
      mode: "payment",
      currency: "USD",
      intent_id: "pi_1234567890", // Required
      client_secret: "pi_1234567890_secret_abcdef", // Required
      success_url: window.location.href + "/success", // Optional
      failure_url: window.location.href + "/failure", // Optional
    });
  }
  
  // Example: Using init + redirectToCheckout (full API)
  async function redirectToPaymentWithInit() {
    const uqpay = await init({
      env: "production", // 'develop' | 'local' | 'testing' | 'sandbox' | 'demo' | 'production'
      enabledElements: ["payments"],
    });
    
    await uqpay.payments.redirectToCheckout({
      mode: "payment",
      currency: "USD",
      intent_id: "pi_1234567890", // Required
      client_secret: "pi_1234567890_secret_abcdef", // Required
      success_url: window.location.href + "/success", // Optional
      failure_url: window.location.href + "/failure", // Optional
    });
  }
</script>

🚀 Quick Start

Import the SDK

// ES6 module import
import { init, createElement, generatePaymentUrl, redirectToCheckout } from '@uqpay/checkout-sdk';

// or CommonJS
const { init, createElement, generatePaymentUrl, redirectToCheckout } = require('@uqpay/checkout-sdk');

📋 Usage Examples

1. Redirect to Payment Page (Recommended)

Option A: Using redirectToCheckout directly (Simplified)

import { redirectToCheckout } from '@uqpay/checkout-sdk';

async function redirectToPayment() {
  // Redirect to payment page directly (no need to call init first)
  await redirectToCheckout({
    env: 'production', // 'develop' | 'local' | 'testing' | 'sandbox' | 'demo' | 'production'
    mode: 'payment',
    currency: 'USD',
    intent_id: 'pi_1234567890', // Required
    client_secret: 'pi_1234567890_secret_abcdef', // Required
    success_url: 'https://yoursite.com/success', // Optional
    failure_url: 'https://yoursite.com/failure', // Optional
  });
}

Option B: Using init + redirectToCheckout (Full API)

import { init } from '@uqpay/checkout-sdk';

async function redirectToPayment() {
  // Initialize SDK
  const uqpay = await init({
    env: 'production', // 'develop' | 'local' | 'testing' | 'sandbox' | 'demo' | 'production'
    enabledElements: ['payments']
  });

  // Redirect to payment page
  await uqpay.payments.redirectToCheckout({
    mode: 'payment',
    currency: 'USD',
    intent_id: 'pi_1234567890', // Required
    client_secret: 'pi_1234567890_secret_abcdef', // Required
    success_url: 'https://yoursite.com/success', // Optional
    failure_url: 'https://yoursite.com/failure', // Optional
  });
}

2. Embedded Payment Form (Drop-in)

import { init, createElement } from '@uqpay/checkout-sdk';

async function createPaymentForm() {
  // Initialize SDK first
  await init({
    env: 'sandbox', // 'develop' | 'local' | 'testing' | 'sandbox' | 'demo' | 'production'
    enabledElements: ['payments']
  });

  // Create payment element
  const paymentElement = await createElement({
    intent_id: 'pi_1234567890', // Required
    client_secret: 'pi_1234567890_secret_abcdef', // Required
    currency: 'USD', // Required
    amount: 1000, // Optional: 10.00 USD (in cents)
    description: 'Order #12345', // Optional
    success_url: 'https://yoursite.com/success', // Optional
    failure_url: 'https://yoursite.com/failure', // Optional
    style: {
      width: '100%',
      height: '600px',
      border: '1px solid #e1e5e9',
      position: 'relative'
    }
  });

  // Mount to page
  paymentElement.mount('payment-container');
  
  // Or mount to an element directly
  // const container = document.getElementById('payment-container');
  // paymentElement.mount(container);
}

3. Server-side Payment Link Generation

// Node.js server-side usage
import { generatePaymentUrl } from '@uqpay/checkout-sdk';

async function createPaymentLink(req, res) {
  try {
    const paymentUrl = await generatePaymentUrl({
      env: 'production', // 'develop' | 'testing' | 'sandbox' | 'production'
      mode: 'payment',
      currency: 'USD',
      intent_id: req.body.intent_id, // Required
      client_secret: req.body.client_secret, // Required
      success_url: 'https://yoursite.com/success', // Optional
      failure_url: 'https://yoursite.com/failure', // Optional
      // Optional: Add theme customization
      theme: {
        popupWidth: 800,
        popupHeight: 600
      },
      // Optional: Add recurring payment options
      recurringOptions: {
        card: {
          next_triggered_by: 'merchant',
          merchant_trigger_reason: 'scheduled'
        }
      }
    });

    res.json({ paymentUrl });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
}

Note: generatePaymentUrl is designed for server-side use and returns the payment URL without redirecting. It's perfect for generating payment links in emails, SMS, or API responses.

🔧 Advanced Usage

Event Listening

// Listen for payment element ready event
document.getElementById('payment-container').addEventListener('onReady', (event) => {
  console.log('Payment element ready:', event.detail);
  // event.detail contains: { element: 'dropIn', intent_id: 'pi_1234567890' }
});

Dynamic Updates and Cleanup

// Create payment element
const paymentElement = await createElement({
  intent_id: 'pi_1234567890',
  client_secret: 'pi_1234567890_secret_abcdef',
  currency: 'USD',
  success_url: 'https://yoursite.com/success',
  failure_url: 'https://yoursite.com/failure'
});

// Mount to container
paymentElement.mount('payment-container');

// Later, unmount the element (removes from DOM but keeps element object)
paymentElement.unmount();

// Finally, destroy the element (cleans up resources)
paymentElement.destroy();

📱 Framework Integration Examples

Check specific framework integration examples:

• React Example
• Vue Example
• Angular Example
• Vanilla HTML Example
• Node.js Server Example

⚠️ Important Notes

1. Environment Configuration:
   • develop - Development environment
   • local - Local development
   • testing - Testing environment
   • sandbox - Sandbox environment for testing
   • demo - Demo environment
   • production - Production environment (default)
2. Security:
   • client_secret should be obtained from your server, never hardcode in frontend
   • Always use HTTPS in production environment
3. Error Handling:
   • Always wrap SDK calls with try-catch to handle potential errors
   • Check for browser environment before using browser-specific APIs
4. Node.js Compatibility:
   • generatePaymentUrl is designed for server-side use
   • createElement and redirectToCheckout require browser environment
   • Browser-specific functions will return mock objects in Node.js environment
5. Required Parameters:
   • intent_id and client_secret are required for all payment operations
   • currency is required for checkout operations

🔗 API Reference

init(options: InitOptions): Promise<SDKInstance>

Initialize the UQPay SDK instance.

Parameters:

• options.env (required): 'develop' | 'local' | 'testing' | 'sandbox' | 'demo' | 'production' - Environment configuration
• options.enabledElements (optional): string[] - Enabled feature modules, default: ['payments']

Returns: Promise<SDKInstance> - SDK instance with payment interfaces

Example:

const uqpay = await init({
  env: 'production',
  enabledElements: ['payments']
});

redirectToCheckout(options: RedirectToCheckoutOptions & { env?: string }): Promise<string>

Redirect to payment checkout page. Can be used standalone without calling init first.

Parameters:

• options.env (optional): 'develop' | 'local' | 'testing' | 'sandbox' | 'demo' | 'production' - Environment, default: 'production'
• options.mode (required): 'payment' | 'recurring' - Payment mode
• options.currency (required): string - Currency code (e.g., 'USD', 'CNY')
• options.intent_id (required): string - Payment intent ID
• options.client_secret (required): string - Client secret key
• options.success_url (optional): string - Success redirect URL
• options.failure_url (optional): string - Failure redirect URL
• options.recurringOptions (optional): RecurringOptions - Recurring payment options (required when mode is 'recurring')
• options.theme (optional): object - Theme customization options
• options[key: string] (optional): any - Additional parameters

Returns: Promise<string> - Final checkout URL (redirects in browser, returns URL in Node.js)

Example:

await redirectToCheckout({
  env: 'production',
  mode: 'payment',
  currency: 'USD',
  intent_id: 'pi_1234567890',
  client_secret: 'pi_1234567890_secret_abcdef',
  success_url: 'https://yoursite.com/success'
});

createElement(options: CreateElementOptions): Promise<ElementType>

Create an embedded payment element (Drop-in). Requires browser environment.

Parameters:

• options.intent_id (required): string - Payment intent ID
• options.client_secret (required): string - Client secret key
• options.currency (required): string - Currency code
• options.amount (optional): number - Payment amount in cents
• options.description (optional): string - Payment description
• options.success_url (optional): string - Success redirect URL
• options.failure_url (optional): string - Failure redirect URL
• options.style (optional): object - Style configuration
  • style.width (optional): string - Element width, default: '100%'
  • style.height (optional): string - Element height, default: '850px'
  • style.border (optional): string - Border style, default: 'none'
  • style.position (optional): string - Position, default: 'relative'
• options[key: string] (optional): any - Additional parameters

Returns: Promise<ElementType> - Element object with mount/unmount/destroy methods

ElementType Methods:

• mount(containerId: string | HTMLElement): HTMLElement | null - Mount element to container
• unmount(): void - Unmount element from DOM
• destroy(): void - Destroy element and cleanup resources

Example:

const element = await createElement({
  intent_id: 'pi_1234567890',
  client_secret: 'pi_1234567890_secret_abcdef',
  currency: 'USD',
  success_url: 'https://yoursite.com/success',
  style: { width: '100%', height: '600px' }
});

element.mount('payment-container');

generatePaymentUrl(options: RedirectToCheckoutOptions & { env?: string }): Promise<string>

Generate payment URL without redirection. Designed for server-side use (Node.js friendly).

Parameters:

• Same as redirectToCheckout options
• options.env (optional): 'develop' | 'testing' | 'sandbox' | 'production' - Environment, default: 'develop'

Returns: Promise<string> - Payment checkout URL

Example:

const url = await generatePaymentUrl({
  env: 'production',
  mode: 'payment',
  currency: 'USD',
  intent_id: 'pi_1234567890',
  client_secret: 'pi_1234567890_secret_abcdef',
  success_url: 'https://yoursite.com/success'
});
// Returns: 'https://checkout.uqpay.com/standalone?intent_id=...&client_secret=...'

SDKInstance.payments.redirectToCheckout(options: RedirectToCheckoutOptions): Promise<string>

Redirect to checkout using SDK instance (requires init to be called first).

Parameters: Same as standalone redirectToCheckout function (except env is taken from init)

Returns: Promise<string> - Final checkout URL

Example:

const uqpay = await init({ env: 'production' });
await uqpay.payments.redirectToCheckout({
  mode: 'payment',
  currency: 'USD',
  intent_id: 'pi_1234567890',
  client_secret: 'pi_1234567890_secret_abcdef'
});