npm package: @ponponpay/sdk
Description: Official PonponPay SDK for JavaScript/TypeScript
Author: PonponPay
Latest version: 1.0.0

# @ponponpay/sdk

Official PonponPay SDK for JavaScript/TypeScript.

## Installation

```bash
npm install @ponponpay/sdk
# or
pnpm add @ponponpay/sdk
# or
yarn add @ponponpay/sdk
```

## Usage

### Server SDK (Node.js)

Use the Server SDK on your backend to create orders and manage payments.

```typescript
import { PonponPay } from '@ponponpay/sdk/server';

const ponponpay = new PonponPay({
  apiKey: process.env.PONPONPAY_API_KEY!,
});

// Create order
const order = await ponponpay.createOrder({
  currency: 'USDT',
  network: 'tron',
  amount: 100.0,
  notifyUrl: 'https://your-site.com/webhook',
  redirectUrl: 'https://your-site.com/success',
});

console.log(order.paymentUrl); // Redirect user to this URL
```

### Browser SDK

Use the Browser SDK in the browser to handle payment UI. **No API Key required.**

```html
<script src="https://cdn.ponponpay.com/sdk/ponponpay.min.js"></script>
<script>
  const checkout = new PonponPayCheckout();

  // Redirect to payment page
  checkout.redirect(paymentUrl);

  // Or open in modal
  checkout.openModal(paymentUrl, {
    onClose: () => console.log('Modal closed'),
  });

  // Poll for payment status
  checkout.pollStatus(tradeId);
  checkout.on('paid', (data) => {
    console.log('Payment successful!', data);
    // Redirect to success page or update UI
  });
</script>
```

Or with ES modules:

```typescript
import { PonponPayCheckout } from '@ponponpay/sdk/browser';

const checkout = new PonponPayCheckout();
checkout.redirect(paymentUrl);
```

## API Reference

### Server SDK

#### `new PonponPay(config)`

Create a new PonponPay instance.

| Option       | Type                          | Required | Default                                        |
| ------------ | ----------------------------- | -------- | ---------------------------------------------- |
| `apiKey`     | `string`                      | Yes      | -                                              |
| `baseUrl`    | `string`                      | No       | `https://api.ponponpay.com/api/v1/pay/sdk`     |
| `timeout`    | `number`                      | No       | `30000`                                        |
| `retries`    | `number`                      | No       | `3`                                            |
| `retryDelay` | `(attempt: number) => number` | No       | Exponential backoff                            |

#### `createOrder(params)`

Create a new payment order.

| Parameter     | Type     | Required | Description                    |
| ------------- | -------- | -------- | ------------------------------ |
| `currency`    | `string` | Yes      | `'USDT'` or `'USDC'`           |
| `network`     | `string` | Yes      | `'tron'`, `'ethereum'`, etc.   |
| `amount`      | `number` | Yes      | Order amount                   |
| `mchOrderId`  | `string` | No       | Your order ID                  |
| `notifyUrl`   | `string` | No       | Webhook URL                    |
| `redirectUrl` | `string` | No       | Redirect URL after payment     |

#### `getPaymentMethods()`

Get available payment methods.

#### `queryOrder(tradeId)`

Query order by PonponPay trade ID.

#### `queryOrderByMchId(mchOrderId)`

Query order by your merchant order ID.

#### `cancelOrder(tradeId)`

Cancel order by trade ID.

### Browser SDK

#### `new PonponPayCheckout(config?)`

Create a new checkout instance.

| Option       | Type     | Required | Default                       |
| ------------ | -------- | -------- | ----------------------------- |
| `paymentUrl` | `string` | No       | `https://pay.ponponpay.com`   |

#### `redirect(paymentUrl, options?)`

Redirect to payment page.

| Option   | Type                    | Default    |
| -------- | ----------------------- | ---------- |
| `target` | `'_self'` \| `'_blank'` | `'_self'`  |

#### `openModal(paymentUrl, options?)`

Open payment page in a modal.

| Option    | Type         | Default   |
| --------- | ------------ | --------- |
| `width`   | `string`     | `'450px'` |
| `height`  | `string`     | `'650px'` |
| `onClose` | `() => void` | -         |

#### `pollStatus(tradeId, options?)`

Start polling for order status.

| Option     | Type     | Default     |
| ---------- | -------- | ----------- |
| `interval` | `number` | `3000`      |
| `timeout`  | `number` | `1800000`   |

#### `on(event, callback)`

Listen for events: `'paid'`, `'expired'`, `'cancelled'`, `'error'`, `'close'`

## License

MIT