Beginner10 min read

Public Key Mode

Public Key mode is designed for browser integrations. Your frontend uses a public_key to exchange a short-lived session token, then creates orders and queries order status without exposing an API Key in the browser.

Integration Flow

Generate a Public Key in the merchant dashboard and enable frontend integration.
Configure the domain whitelist for your frontend origins.
Use the browser to call /api/v1/sdk/token with the public key.
Use the returned session token to call /api/v1/sdk/orders.
Redirect users to the returned payment_url or poll order status.

The current Public Key mode does not require frontend parameter signing. The recommended path is to use the JavaScript SDK or manually call the token and order APIs shown below.

Get Your Public Key

Log in to the PonponPay merchant dashboard.
Open the "Frontend Integration" page.
Enable frontend integration.
Generate and copy your pub_xxx Public Key.

Domain Whitelist

Public Keys can only be used from whitelisted domains. The backend validates the request origin using Origin or Referer.

Enable localhost only for development.
Use real production domains in live environments.
Wildcard subdomains such as *.example.com are supported.

If your page runs inside an iframe, app WebView, or intermediate payment layer, standard Origin headers may not be sent consistently. Validate Referer and Origin behavior before production rollout.

Recommended: JavaScript SDK

npm install @ponponpay/sdk

Initialize Client

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

const client = new PonponPayClient({
  publicKey: 'pub_your_public_key',
  baseUrl: 'https://api.ponponpay.com'
});

Create Order

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

window.location.href = order.paymentUrl;

Query Order Status

const status = await client.getOrderStatus(order.tradeId);
console.log(status.status);

For the broader SDK material, see the JavaScript SDK section or the package repository README.

Manual API Integration

1. Exchange a Short-Lived Token

const tokenRes = await fetch('https://api.ponponpay.com/api/v1/sdk/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    public_key: 'pub_your_public_key',
    timestamp: Date.now()
  })
});

const tokenData = await tokenRes.json();
const token = tokenData.data.token;

2. Create an Order with the Token

const orderRes = await fetch('https://api.ponponpay.com/api/v1/sdk/orders', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${token}`
  },
  body: JSON.stringify({
    currency: 'USDT',
    network: 'tron',
    amount: 100,
    order_id: 'ORDER_123456',
    notify_url: 'https://your-site.com/webhook',
    redirect_url: 'https://your-site.com/success'
  })
});

const orderData = await orderRes.json();
window.location.href = orderData.data.payment_url;

3. Query Order Status

const statusRes = await fetch(
  'https://api.ponponpay.com/api/v1/sdk/orders/T20240101120000123456/status',
  {
    headers: {
      Authorization: `Bearer ${token}`
    }
  }
);

const statusData = await statusRes.json();
console.log(statusData.data.status);

Capability Boundaries

Capability	Supported	Description
Create order	✅	Supported through the SDK token order APIs.
Query order status	✅	Supported for orders that belong to the merchant associated with the Public Key.
Full merchant admin APIs	❌	Not exposed to browsers in Public Key mode.
Expose API Key in browser	❌	Never expose API Key to frontend code. Use Public Key only.

Security Notes

A Public Key can be public, but it only works on whitelisted domains.
Session tokens are short-lived and should be refreshed before expiry.
The backend validates timestamps, origin domains, and merchant frontend limits.
Always use HTTPS in production.

If you need server-side management APIs, use API Key mode.