JavaScript/TypeScript Browser SDK (Public Key)

Use Public Key to redirect customers to PolyPay hosted checkout. PolyPay owns payment method selection, and your site does not need to render a separate payment method page.

When to Use It

Public Key mode is designed for merchant checkout redirects. Your site builds a signed hosted checkout URL with a public_key. If currency and network are omitted, PolyPay first shows the hosted payment method selection page. If both are provided, PolyPay skips selection and opens the payment page directly. The same orderId reuses an unexpired order only for the same payment method, so customers can return to selection and choose a different chain or currency.

Integration Flow

1. Open Frontend Integration in the merchant dashboard and enable it.
2. Generate and copy your pub_xxx Public Key.
3. Configure allowed frontend domains. Enable localhost only for development.
4. Use the JavaScript SDK to redirect to hosted checkout.
5. Let PolyPay handle payment method selection, or pass currency and network to go directly to the payment page.
6. Process server-side Notify URL callbacks, including order.created and final payment status events, or query status after redirect.

Domain Whitelist

Public Keys only work from whitelisted domains. The backend validates the request origin using Origin or Referer. In production, keep only real domains. Wildcard subdomains such as *.example.com are supported.

Installation

npm install @polypay/sdk

Hosted Checkout

This is the recommended checkout integration. Generate the signature on your server and pass the signed parameters to the browser. By default, redirect to https://checkout.polypay.ai/checkout so the checkout can detect the customer's browser language. If detection is unavailable or unsupported, it falls back to English. Pass locale when you want to pin paths such as https://checkout.polypay.ai/zh/checkout.

Redirect to Hosted Checkout

import { PolyPayCheckout } from '@polypay/sdk/browser';

const checkout = new PolyPayCheckout();

checkout.redirectToHostedCheckout({
  publicKey: 'pub_your_public_key',
  amount: 100,
  timestamp: Date.now(),
  signature: 'server_generated_signature',
  orderId: 'ORDER_123456',
  notifyUrl: 'https://your-site.com/webhook',
  redirectUrl: 'https://your-site.com/success'
});

Skip Selection When Method Is Known

checkout.redirectToHostedCheckout({
  publicKey: 'pub_your_public_key',
  amount: 100,
  timestamp: Date.now(),
  signature: 'server_generated_signature',
  orderId: 'ORDER_123456',
  notifyUrl: 'https://your-site.com/webhook',
  redirectUrl: 'https://your-site.com/success',
  currency: 'USDT',
  network: 'Tron'
});

Build URL Without Redirecting

const checkoutUrl = checkout.buildHostedCheckoutUrl({
  publicKey: 'pub_your_public_key',
  amount: 100,
  timestamp: Date.now(),
  signature: 'server_generated_signature',
  orderId: 'ORDER_123456',
  notifyUrl: 'https://your-site.com/webhook',
  redirectUrl: 'https://your-site.com/success'
});

Manual API Calls

If you do not want to use the SDK yet, redirect to the hosted checkout URL manually. The checkout page validates the signed parameters before showing payment methods or creating the order. If order_id already maps to an unexpired order, the customer is sent directly to that payment page.

Hosted Checkout URL

const url = new URL('https://checkout.polypay.ai/checkout');
url.searchParams.set('public_key', 'pub_your_public_key');
url.searchParams.set('amount', '100.00');
url.searchParams.set('timestamp', String(Date.now()));
url.searchParams.set('order_id', 'ORDER_123456');
url.searchParams.set('notify_url', 'https://your-site.com/webhook');
url.searchParams.set('redirect_url', 'https://your-site.com/success');
url.searchParams.set('signature', 'server_generated_signature');

// Optional direct-to-payment fields:
// url.searchParams.set('currency', 'USDT');
// url.searchParams.set('network', 'Tron');

window.location.href = url.toString();

Browser Checkout UI

The Checkout SDK handles hosted checkout redirects. The hosted checkout page lets the customer choose an available network and currency before creating the payment.

Script Tag (host under your domain)

<script src="https://polypay.ai/sdk/polypay.min.js"></script>
<script>
  const checkout = new PolyPayCheckout();
  checkout.redirectToHostedCheckout({
    publicKey: 'pub_your_public_key',
    amount: 100,
    timestamp: Date.now(),
    signature: 'server_generated_signature',
    orderId: 'ORDER_123456'
  });
</script>

ES Modules

import { PolyPayCheckout } from '@polypay/sdk/browser';

const checkout = new PolyPayCheckout();

React Integration

import { PolyPayCheckout } from '@polypay/sdk/browser';

function PayButton() {
  const handlePay = () => {
    const checkout = new PolyPayCheckout();
    checkout.redirectToHostedCheckout({
      publicKey: 'pub_your_public_key',
      amount: 100,
      timestamp: Date.now(),
      signature: 'server_generated_signature',
      orderId: 'ORDER_123456',
      notifyUrl: 'https://your-site.com/webhook',
      redirectUrl: 'https://your-site.com/success'
    });
  };

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

Security Boundaries

• A Public Key can be public, but it only works from whitelisted domains.
• Hosted checkout validates signed parameters before payment methods are shown or an order is created.
• Reusing the same orderId before expiration only reuses the existing payment page for the same payment method; without a selected payment method, hosted checkout still shows payment method selection.
• Never put an API Key in frontend code.
• Always use HTTPS in production.