JavaScript/TypeScript Browser SDK (Hosted Checkout)

Browser Public Key Token mode is disabled. Create Hosted Checkout on the merchant server with an API Key; the browser only opens the opaque checkout_url.

Why this migration is required

Public Key, Origin and Referer are visible or spoofable and cannot authenticate order creation. The server now rejects /api/v1/sdk/token and public_key checkout mode with PUBLIC_KEY_BROWSER_FLOW_DISABLED.

Install

pnpm add @polypay/sdk

1. Create Checkout on the merchant server

// Merchant server only. Never expose the API Key to browser code.
const response = await fetch('https://api.polypay.ai/api/v1/pay/order/checkout', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.POLYPAY_API_KEY!
  },
  body: JSON.stringify({
    amount: 100,
    mch_order_id: 'ORDER_123456',
    notify_url: 'https://your-site.com/webhook',
    redirect_url: 'https://your-site.com/success'
  })
});
const { data } = await response.json();
return { checkoutUrl: data.checkout_url };

2. Redirect in the browser

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

const { checkoutUrl } = await fetch('/api/create-polypay-checkout', {
  method: 'POST'
}).then((response) => response.json());

new PolyPayCheckout().redirect(checkoutUrl);

Migration checklist

Remove browser-side public_key, timestamp and signature URL generation.
Remove PolyPayClient Session Token and order calls.
Keep the API Key only in private merchant-server configuration.
Set amount, order ID and callback URLs on the merchant server.

Rate limits and safe retries

When a request exceeds its current policy, PolyPay returns a real HTTP 429. Application responses use error code 40001; a CDN or WAF may instead return HTML or plain text, so clients must check HTTP status before parsing by Content-Type.

HTTP/1.1 429 Too Many Requests
Retry-After: 10
RateLimit-Limit: 60
RateLimit-Remaining: 0
RateLimit-Reset: 10

{"code":40001,"message":"RateLimitExceeded","data":{"retry_after":10}}

Honor Retry-After first; it may be seconds or an HTTP-date. If absent, use jittered exponential backoff. Automatically retry only replay-safe or idempotency-protected requests, with a bounded retry count.

Hosted Checkout and payment-method queries use separate policies. Do not assume one fixed quota for every SDK operation; treat response headers as authoritative.