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

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

Usage

Simple Initialization (Token Only)

import PayOSWalletOnboardSDK from '@payos-inc/payos-wallet-onboard-js';

// Initialize with just the link_session_token
const payOS = PayOSWalletOnboardSDK.init('YOUR_LINK_SESSION_TOKEN');

// The UI is automatically mounted in a default container.
// To remove it later:
// payOS.unmount();

Initialization with Options

import PayOSWalletOnboardSDK from '@payos-inc/payos-wallet-onboard-js';

PayOSWalletOnboardSDK.init({
  token: 'YOUR_LINK_SESSION_TOKEN',
  containerId: 'my-custom-container', // Optional: Specify your own container element ID
  environment: 'sandbox', // 'sandbox' or 'production'
  merchantName: 'Your Merchant Name', // Optional: Displayed in the UI
  onSuccess: (walletUserId) => {
    console.log('PayOS Wallet Onboard successful!', walletUserId);
    // User completed the flow, proceed with walletUserId
  },
  onClose: () => {
    console.log('PayOS Wallet Onboard closed by user.');
    // User closed the iframe before completing
  },
  onError: (error) => {
    console.error('PayOS Wallet Onboard error:', error);
    // Handle errors during the flow
  }
});

Initialization with Container Element

Provide an HTML element or a CSS selector string directly:

import PayOSWalletOnboardSDK from '@payos-inc/payos-wallet-onboard-js';

// Using a selector
PayOSWalletOnboardSDK.init('#payos-container-div', {
  token: 'YOUR_LINK_SESSION_TOKEN',
  // ... other options
});

// Using an HTMLElement
const container = document.getElementById('payos-container-div');
PayOSWalletOnboardSDK.init(container, {
  token: 'YOUR_LINK_SESSION_TOKEN',
  // ... other options
});

Direct Script Inclusion

Include the UMD build from a public CDN:

<!-- Using unpkg CDN -->
<script src="https://unpkg.com/@payos-inc/payos-wallet-onboard-js@latest/dist/payos-wallet-onboard.min.js"></script>

<!-- Or using jsdelivr CDN -->
<script src="https://cdn.jsdelivr.net/npm/@payos-inc/payos-wallet-onboard-js@latest/dist/payos-wallet-onboard.min.js"></script>

<div id="payos-onboard-container"></div>
<script>
  // Use the global PayOSWalletOnboard object
  window.PayOSWalletOnboard.init('#payos-onboard-container', {
    token: 'YOUR_LINK_SESSION_TOKEN',
    onSuccess: (walletUserId) => console.log('Success!', walletUserId),
    onClose: () => console.log('Closed.'),
    onError: (err) => console.error('Error:', err)
  });

  // Or use the simplified initPayOS global
  // window.initPayOS('YOUR_LINK_SESSION_TOKEN', { /* options */ });
</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:

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

Advanced Usage with PayOSWalletOnboardOptions:

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

import { PayOSWalletOnboard, PayOSWalletOnboardOptions } from '@payos-inc/payos-wallet-onboard-js';

const options: PayOSWalletOnboardOptions = {
  container: '#my-container',
  token: 'YOUR_LINK_SESSION_TOKEN',
  environment: 'sandbox',
  merchantName: 'Your Merchant Name',
  walletUserId: 'optional-existing-user-id',
  height: '600px',                                // Custom iframe height
  onClose: (data) => {                            // More detailed close data
    if (data.success) {
      console.log('Success with ID:', data.walletUserId);
    } else {
      console.log('Closed without completing');
    }
  },
  onError: (error) => console.error(error)
};

const instance = new PayOSWalletOnboard(options);
instance.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.