JavaScript/TypeScript 浏览器 SDK（Hosted Checkout）

浏览器 Public Key Token 模式已停用。商户服务端使用 API Key 创建 Hosted Checkout，浏览器只打开不透明 checkout_url。

为什么需要迁移

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. 商户服务端创建 Checkout

// 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. 浏览器跳转

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

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

new PolyPayCheckout().redirect(checkoutUrl);

迁移检查

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.

限流与安全重试

请求超过当前策略额度时，PolyPay 返回真实 HTTP 429。应用响应使用错误码 40001；CDN/WAF 也可能返回 HTML 或纯文本，因此客户端应先检查 HTTP 状态，再按 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}}

优先读取 Retry-After（可能是秒数或 HTTP-date）；缺失时使用带抖动的指数退避。只自动重试可安全重放或具备幂等保护的请求，并设置最大重试次数。

Hosted Checkout 与支付方式查询使用独立策略。不要假设所有 SDK 接口共享同一个固定额度，以响应头为准。