初级10 分钟阅读

Public Key 模式

Public Key 模式用于浏览器端集成。前端使用公开的 public_key 换取短期 Session Token，再通过 Token 创建订单和查询订单状态，不需要在浏览器中暴露 API Key。

集成流程

商户后台生成 Public Key，并开启前端集成。
配置允许访问的域名白名单。
浏览器通过 public_key 请求 /api/v1/sdk/token，换取短期 Session Token。
浏览器携带 Session Token 调用 /api/v1/sdk/orders 创建订单。
使用 payment_url 跳转支付页，或轮询 /api/v1/sdk/orders/{trade_id}/status 查询结果。

当前 Public Key 模式不再要求你在前端自行生成参数签名。推荐直接使用 JS SDK，或者按下方“手动调用接口”的方式接入。

获取 Public Key

登录 PonponPay 商户后台。
进入“前端集成”页面。
启用前端集成。
生成并复制 pub_xxx 格式的 Public Key。

域名白名单

Public Key 只能在白名单中的域名下使用。后端会根据 Origin 或 Referer 校验请求来源。

开发环境可以开启 localhost。
生产环境请只保留真实域名。
支持通配符子域名，例如 *.example.com。

如果你的页面在 iframe、App WebView 或某些支付中间页中打开，可能不会稳定带上标准 Origin 头，这种场景要先确认 Referer/Origin 行为是否符合白名单校验。

推荐方式：使用 JavaScript SDK

npm install @ponponpay/sdk

创建客户端

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

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

创建订单

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;

查询订单状态

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

更完整的 SDK 说明请看 JavaScript SDK 章节，或者直接参考仓库 README。

手动调用接口

1. 换取短期 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. 使用 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. 查询订单状态

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);

能力边界

能力	是否支持	说明
创建订单	✅	前端可直接调用 SDK Token 订单接口。
查询订单状态	✅	可查询当前 Public Key 关联商户自己的订单。
完整后台管理接口	❌	浏览器端不支持使用 Public Key 访问商户管理接口。
浏览器暴露 API Key	❌	绝对不要这样做。浏览器端只允许使用 Public Key。

安全说明

Public Key 可以公开，但它只能在白名单域名内换取短期 Token。
短期 Token 有有效期，SDK 会在过期前自动刷新。
后端会校验时间戳、来源域名和商户前端额度限制。
生产环境请始终使用 HTTPS。

如果你需要服务端管理接口，请使用 API Key 模式.