@payos-inc/payos-js/README.md

PayOS JavaScript SDK for browser-based checkout and wallet onboarding

# @payos-inc/payos-js

JavaScript SDK for PayOS integration, providing checkout and wallet onboarding functionality.

## Installation

```bash
npm install @payos-inc/payos-js
```

CDN:
```html
<script src="https://unpkg.com/@payos-inc/payos-js@latest/dist/payos-js.min.js"></script>
```

## Quick Start

```javascript
import { PayOS } from '@payos-inc/payos-js';

const payos = new PayOS();

// Wallet Onboarding - Add payment methods
payos.walletOnboard.open({
  token: 'YOUR_TOKEN',      // Get from your backend
  mode: 'popup',            // or 'redirect'
  environment: 'sandbox',   // or 'production'
  onComplete: (result) => {
    console.log('Wallet User ID:', result.walletUserId);
    console.log('Cards added:', result.linkedCardIds);
  },
  onError: (error) => {
    console.error('Error:', error);
  }
});

// Checkout - Process payments
payos.checkout.open({
  token: 'YOUR_TOKEN',      // Get from your backend
  mode: 'popup',            // or 'redirect'
  environment: 'sandbox',   // or 'production'
  onComplete: (result) => {
    console.log('Payment Intent ID:', result.paymentIntentId);
    console.log('Auth completed:', result.authCompleted);
    console.log('Credentials generated:', result.credentialsGenerated);
  },
  onError: (error) => {
    console.error('Error:', error);
  }
});
```

## API Reference

### Constructor

```javascript
const payos = new PayOS();
```

### Methods
#### `payos.walletOnboard.open(options)`
Opens the wallet onboarding flow to add payment methods.

#### `payos.walletOnboard.close()`
Closes the current wallet onboarding session.

#### `payos.walletOnboard.isActive()`
Returns `true` if wallet onboarding is currently active.

#### `payos.checkout.open(options)`
Opens the checkout flow to process payments.

#### `payos.checkout.close()`
Closes the current checkout session.

#### `payos.checkout.isActive()`
Returns `true` if checkout is currently active.

## Options

### Wallet Onboarding Options

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `token` | string | Yes | Session token from your backend |
| `mode` | string | No | 'popup' or 'redirect' (default: 'popup') |
| `environment` | string | No | 'sandbox' or 'production' (default: 'sandbox') |
| `merchantName` | string | No | Your merchant name to display |
| `returnUrl` | string | No | URL for redirect mode |
| `onComplete` | function | No | Called with `{walletUserId, linkedCardIds}` |
| `onError` | function | No | Called on error |
| `onCancel` | function | No | Called when user cancels |
| `onReady` | function | No | Called when UI is ready |

### Checkout Options

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `token` | string | Yes | Checkout token from your backend |
| `mode` | string | No | 'popup' or 'redirect' (default: 'popup') |
| `environment` | string | No | 'sandbox' or 'production' (default: 'sandbox') |
| `returnUrl` | string | No | URL for redirect mode |
| `onComplete` | function | No | Called when checkout completes |
| `onError` | function | No | Called on error |
| `onCancel` | function | No | Called when user cancels |
| `onReady` | function | No | Called when UI is ready |

## Display Modes

### Popup Mode (Default)
Opens in a new window:
```javascript
payos.walletOnboard.open({
  token: 'token',
  mode: 'popup',
  environment: 'sandbox'
});
```

### Redirect Mode
Redirects the current page:
```javascript
payos.walletOnboard.open({
  token: 'token',
  mode: 'redirect',
  environment: 'sandbox',
  returnUrl: 'https://yourapp.com/complete'
});
```

### Handling Redirect Returns
PayOS returns parameters prefixed with `payos_`:
```javascript
// In your return URL handler
const params = new URLSearchParams(window.location.search);
const status = params.get('payos_status'); // 'success', 'cancel', or 'error'
const encodedData = params.get('payos_data'); // URL-encoded JSON
const timestamp = params.get('payos_timestamp');

if (status === 'success' && encodedData) {
  // Decode the data
  const data = JSON.parse(decodeURIComponent(encodedData));
  // For wallet onboarding:
  if (data.walletUserId) {
    console.log('Wallet User ID:', data.walletUserId);
    console.log('Cards Added:', data.linkedCardIds);
  }
  
  // For checkout:
  if (data.paymentIntentId) {
    console.log('Payment Intent ID:', data.paymentIntentId);
    console.log('Auth Completed:', data.authCompleted);
  }
}
```

## TypeScript

```typescript
import { PayOS } from '@payos-inc/payos-js';

const payos = new PayOS();

payos.walletOnboard.open({
  token: 'token',
  mode: 'popup',
  environment: 'sandbox',
  onComplete: (result) => {
    // TypeScript support included
    console.log(result.walletUserId); // string
    console.log(result.linkedCardIds); // string[]
  }
});
```

## Browser Support

- Chrome 89+
- Firefox 87+
- Safari 14+
- Edge 89+

## License

MIT

## Support

Contact: support@payos.ai  
Documentation: https://docs.payos.ai