JavaScript/TypeScript SDK

Official PonponPay SDK for JavaScript and TypeScript. Works with Node.js, browsers, and modern frameworks.

Installation

npm install @ponponpay/sdk

Server SDK (Node.js)

Use the Server SDK on your backend to create orders and manage payments. The API Key must be kept secure on the server side.

Initialize Client

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

const ponponpay = new PonponPay({
  apiKey: process.env.PONPONPAY_API_KEY!,
  // Optional configurations
  baseUrl: 'https://api.ponponpay.com/api/v1/pay/sdk',
  timeout: 30000,
  retries: 3,
});

Create Order

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

console.log(order.tradeId);      // PonponPay transaction ID
console.log(order.paymentUrl);   // Redirect user to this URL
console.log(order.address);      // Receiving wallet address
console.log(order.actualAmount); // Actual payment amount

Query Order

// Query by PonponPay trade ID
const order = await ponponpay.queryOrder('PP202412110001');

// Query by your merchant order ID
const order = await ponponpay.queryOrderByMchId('ORDER_123456');

console.log(order.status);  // 'pending', 'paid', 'expired', 'cancelled'
console.log(order.txHash);  // Blockchain transaction hash (if paid)

Cancel Order

// Cancel by trade ID
await ponponpay.cancelOrder('PP202412110001');

// Cancel by merchant order ID
await ponponpay.cancelOrderByMchId('ORDER_123456');

Get Payment Methods

const methods = await ponponpay.getPaymentMethods();

// Returns array of available currencies and networks
// [{ currency: 'USDT', network: 'tron' }, { currency: 'USDC', network: 'ethereum' }, ...]

Webhook Verification

// Express.js example
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-ponponpay-signature'];
  
  // Verify the webhook signature
  const isValid = ponponpay.verifyWebhook(req.body, signature);
  
  if (isValid) {
    const data = ponponpay.parseWebhook(req.body);
    
    if (data.status === 'paid') {
      // Update your order status
      console.log('Payment received:', data.tradeId);
    }
  }
  
  res.send('OK');
});

Browser SDK

Use the Browser SDK in the browser to handle payment UI. No API Key required - it only handles UI interactions.

CDN Usage

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

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

ES Modules

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

const checkout = new PonponPayCheckout();

Redirect to Payment Page

// Redirect in same window (default)
checkout.redirect(paymentUrl);

// Open in new tab
checkout.redirect(paymentUrl, { target: '_blank' });

// Redirect by trade ID
checkout.redirectByTradeId('PP202412110001');

Open Payment Modal

checkout.openModal(paymentUrl, {
  width: '450px',
  height: '650px',
  onClose: () => {
    console.log('Modal closed');
  }
});

// Close modal programmatically
checkout.closeModal();

Poll Payment Status

// Start polling for payment status
checkout.pollStatus('PP202412110001', {
  interval: 3000,   // Poll every 3 seconds
  timeout: 1800000  // Timeout after 30 minutes
});

// Listen for events
checkout.on('paid', (data) => {
  console.log('Payment successful!', data);
  window.location.href = '/success';
});

checkout.on('expired', () => {
  console.log('Payment expired');
});

checkout.on('cancelled', () => {
  console.log('Payment cancelled');
});

checkout.on('error', (error) => {
  console.error('Error:', error);
});

// Stop polling
checkout.stopPolling();

React Integration

// hooks/usePonponPay.ts
import { useEffect, useRef } from 'react';
import { PonponPayCheckout } from '@ponponpay/sdk/browser';

export function usePonponPay() {
  const checkoutRef = useRef<PonponPayCheckout | null>(null);

  useEffect(() => {
    checkoutRef.current = new PonponPayCheckout();
    return () => {
      checkoutRef.current?.stopPolling();
    };
  }, []);

  return checkoutRef.current;
}

// components/PayButton.tsx
function PayButton({ paymentUrl }: { paymentUrl: string }) {
  const checkout = usePonponPay();

  const handlePay = () => {
    checkout?.openModal(paymentUrl, {
      onClose: () => console.log('closed')
    });
  };

  return <button onClick={handlePay}>Pay Now</button>;
}

Next.js API Route

// app/api/payment/route.ts
import { PonponPay } from '@ponponpay/sdk/server';
import { NextResponse } from 'next/server';

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

export async function POST(request: Request) {
  const { amount, currency, network } = await request.json();

  const order = await ponponpay.createOrder({
    currency,
    network,
    amount,
    notifyUrl: `${process.env.NEXT_PUBLIC_URL}/api/webhook`,
    redirectUrl: `${process.env.NEXT_PUBLIC_URL}/success`,
  });

  return NextResponse.json({
    tradeId: order.tradeId,
    paymentUrl: order.paymentUrl,
  });
}

Error Handling

import { 
  PonponPayError, 
  AuthenticationError, 
  ValidationError,
  NetworkError 
} from '@ponponpay/sdk';

try {
  const order = await ponponpay.createOrder({...});
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API Key');
  } else if (error instanceof ValidationError) {
    console.error('Invalid parameters:', error.message);
  } else if (error instanceof NetworkError) {
    console.error('Network error, please retry');
  } else if (error instanceof PonponPayError) {
    console.error('API error:', error.code, error.message);
  }
}

TypeScript Types

import type {
  PonponPayConfig,
  CreateOrderParams,
  OrderResult,
  OrderDetail,
  PaymentMethod,
  WebhookPayload
} from '@ponponpay/sdk';