PayOS Wallet Onboard JavaScript SDK

The PayOS Wallet Onboard JavaScript SDK provides an easy way to integrate the PayOS wallet creation and payment method onboarding flow into your web application.

Features

• Simple integration with just a few lines of code
• Mounts an iframe-based UI for the PayOS Wallet Onboard flow
• Handles communication between your application and the PayOS Wallet Onboard UI
• Customizable callbacks for success, close, and error events
• Supports different environments (sandbox, production)

Installation

1npm install @payos-inc/payos-wallet-onboard-js
2# or
3yarn add @payos-inc/payos-wallet-onboard-js

Usage

Simple Initialization (Token Only)

1import PayOSWalletOnboardSDK from '@payos-inc/payos-wallet-onboard-js';
2
3// Initialize with just the link_session_token
4const payOS = PayOSWalletOnboardSDK.init('YOUR_LINK_SESSION_TOKEN');
5
6// The UI is automatically mounted in a default container.
7// To remove it later:
8// payOS.unmount();

Initialization with Options

1import PayOSWalletOnboardSDK from '@payos-inc/payos-wallet-onboard-js';
2
3PayOSWalletOnboardSDK.init({
4  token: 'YOUR_LINK_SESSION_TOKEN',
5  containerId: 'my-custom-container', // Optional: Specify your own container element ID
6  environment: 'sandbox', // 'sandbox' or 'production'
7  merchantName: 'Your Merchant Name', // Optional: Displayed in the UI
8  onSuccess: (walletUserId) => {
9    console.log('PayOS Wallet Onboard successful!', walletUserId);
10    // User completed the flow, proceed with walletUserId
11  },
12  onClose: () => {
13    console.log('PayOS Wallet Onboard closed by user.');
14    // User closed the iframe before completing
15  },
16  onError: (error) => {
17    console.error('PayOS Wallet Onboard error:', error);
18    // Handle errors during the flow
19  }
20});

Initialization with Container Element

Provide an HTML element or a CSS selector string directly:

1import PayOSWalletOnboardSDK from '@payos-inc/payos-wallet-onboard-js';
2
3// Using a selector
4PayOSWalletOnboardSDK.init('#payos-container-div', {
5  token: 'YOUR_LINK_SESSION_TOKEN',
6  // ... other options
7});
8
9// Using an HTMLElement
10const container = document.getElementById('payos-container-div');
11PayOSWalletOnboardSDK.init(container, {
12  token: 'YOUR_LINK_SESSION_TOKEN',
13  // ... other options
14});

Direct Script Inclusion

Include the UMD build from a public CDN:

1<!-- Using unpkg CDN -->
2<script src="https://unpkg.com/@payos-inc/payos-wallet-onboard-js@latest/dist/payos-wallet-onboard.min.js"></script>
3
4<!-- Or using jsdelivr CDN -->
5<script src="https://cdn.jsdelivr.net/npm/@payos-inc/payos-wallet-onboard-js@latest/dist/payos-wallet-onboard.min.js"></script>
6
7<div id="payos-onboard-container"></div>
8<script>
9  // Use the global PayOSWalletOnboard object
10  window.PayOSWalletOnboard.init('#payos-onboard-container', {
11    token: 'YOUR_LINK_SESSION_TOKEN',
12    onSuccess: (walletUserId) => console.log('Success!', walletUserId),
13    onClose: () => console.log('Closed.'),
14    onError: (err) => console.error('Error:', err)
15  });
16
17  // Or use the simplified initPayOS global
18  // window.initPayOS('YOUR_LINK_SESSION_TOKEN', { /* options */ });
19</script>

API Reference

PayOSWalletOnboardSDK.init(tokenOrOptionsOrContainer, [options])

Initializes and mounts the PayOS Wallet Onboard flow. Returns a PayOSWalletOnboardInstance.

Parameters:

• tokenOrOptionsOrContainer: Can be one of:
  • A string with the link_session_token
  • A SimpleOptions object with configuration
  • An HTMLElement or selector string for the container
• options (optional): When providing a container, this should be SimpleOptions or PayOSWalletOnboardOptions

SimpleOptions:

1interface SimpleOptions {
2  token: string;                                  // Required: The link_session_token
3  containerId?: string;                           // Optional: ID of container element or create new if not found
4  environment?: "sandbox" | "production";         // Optional: Which environment to use
5  merchantName?: string;                          // Optional: Display name in the UI
6  customBaseUrl?: string;                         // Optional: Override the iframe URL
7  onSuccess?: (walletUserId?: string) => void;    // Optional: Called on successful completion
8  onClose?: () => void;                           // Optional: Called when user closes 
9  onError?: (error: Error) => void;               // Optional: Called when error occurs
10}

Advanced Usage with PayOSWalletOnboardOptions:

For more advanced configurations, you can import and use PayOSWalletOnboardOptions:

1import { PayOSWalletOnboard, PayOSWalletOnboardOptions } from '@payos-inc/payos-wallet-onboard-js';
2
3const options: PayOSWalletOnboardOptions = {
4  container: '#my-container',
5  token: 'YOUR_LINK_SESSION_TOKEN',
6  environment: 'sandbox',
7  merchantName: 'Your Merchant Name',
8  walletUserId: 'optional-existing-user-id',
9  height: '600px',                                // Custom iframe height
10  onClose: (data) => {                            // More detailed close data
11    if (data.success) {
12      console.log('Success with ID:', data.walletUserId);
13    } else {
14      console.log('Closed without completing');
15    }
16  },
17  onError: (error) => console.error(error)
18};
19
20const instance = new PayOSWalletOnboard(options);
21instance.mount();

PayOSWalletOnboardInstance

The object returned by init().

• mount(): Mounts or re-mounts the iframe UI.
• unmount(): Removes the iframe UI from the DOM.

Events

The SDK communicates with your application through callbacks:

• onSuccess: Called when the user successfully completes the onboarding process with a walletUserId
• onClose: Called when the user closes the iframe without completing
• onError: Called when an error occurs during the onboarding process

The iframe uses the postMessage API internally with the following message types:

• PAYOS_LINK_CLOSE: When the iframe is closed (with success=true/false)
• PAYOS_LINK_ERROR: When an error occurs in the iframe

Browser Support

The SDK is compatible with all modern browsers (Chrome, Firefox, Safari, Edge) that support iframes and the postMessage API.

License

MIT License - see LICENSE file for details.