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 介面共享同一個固定額度，以響應頭為準。