PAYGO · DEVELOPER GUIDE
PayGo 开发文档
选择适合你的接入方式,创建支付订单,并通过服务端通知确认支付结果。
接入概览
两种方式共用下单接口、签名规则和 Webhook。区别在于谁向 PayGo 发起下单请求,以及如何展示收银台。
Browser SDK
在你的网页内展示收银台。商户后端签名,浏览器通过 SDK 创建订单并展示二维码和状态。
查看 SDK 接入 →方式二服务端 API
由商户后端直接创建订单。跳转到 PayGo 独立收银台,或使用返回的支付信息展示自己的付款页。
查看 API 接入 →准备工作
- 在商户后台获取 PID、SECRET,配置已启用的收款方式和 Webhook 地址。
- SDK 接入:登记付款页面的精确 Origin(协议、域名、端口,不含路径)。服务端 API:按需配置服务器 IP 白名单。
- 先在自己的后端创建业务订单,确定真实金额、币种和商户订单号,再签名。不要直接信任浏览器提交的金额。
SECRET 不可放入前端代码、移动端、公开仓库或日志。已签名参数和收银台链接也应作为订单访问凭证保护。
方式一:Browser SDK
适合在自己的网页中内嵌收银台。商户后端仅生成签名参数;由浏览器中的 SDK 向 PayGo 下单,并展示付款信息、倒计时和订单状态。
- 商户后端签名
- PayGo.mount()
- SDK 下单并展示收银台
- 商户后端接收 Webhook
将订单参数和服务端生成的 sign 传入 PayGo.mount() 即可。以下为示例值,请替换为真实订单参数。
<div id="paygo-checkout"></div>
<script src="https://app.paygo2.uk/sdk/paygo.js"></script>
<script>
const checkout = PayGo.mount('#paygo-checkout', {
pid: '10001',
merchant_order_no: 'ORDER-10001',
amount: '10.00',
currency: 'CNY',
name: 'Order payment',
type: 'alipay',
return_url: 'https://merchant.example/pay/result',
sign: 'SERVER_GENERATED_HMAC_SHA256',
lang: 'zh',
onSuccess(data) { console.log('Payment UI: paid', data.status); },
onExpired(data) { console.log('Payment UI: expired', data.status); },
onCancelled(data) { console.log('Payment UI: cancelled', data.status); },
onError(error) { console.error(error.message || 'Payment error'); }
});
</script>挂载目标支持 CSS 选择器或 DOM 节点。除下单字段外,可传 api(默认 https://api.paygo2.uk)、lang 和四个 on* 回调;它们是 JavaScript 函数,不属于下单 JSON。不要传 SECRET、token、checkout_url 或 ws_token;旧 timestamp/nonce 也不再支持。
| 字段 | 说明 |
|---|---|
onSuccess(data) | 订单为 paid 时调用,仅更新界面;不代表商户已处理 Webhook。 |
onExpired(data) / onCancelled(data) | 订单过期或取消时调用,data 为订单快照。 |
onError(error) | 请求失败时接收错误;订单状态为 error 时可能收到订单快照。 |
checkout.data / checkout.error | 当前订单快照和错误状态。 |
checkout.refresh() / checkout.destroy() | 刷新会话 / 卸载前停止连接和定时器;终态初始响应可能没有可刷新的会话。 |
SDK 自动跟进订单状态,必要时轮询。支付成功后可能等待商户通知状态,再按现有收银台逻辑约 3 秒跳回 return_url。返回页面只用于展示。
方式二:服务端 API
商户后端直接向 PayGo 创建订单,不需要调用 PayGo.mount()。保存平台订单号后,引导买家打开 checkout_url,或使用返回的二维码、应付金额和地址展示付款信息。
Content-Type: application/json
使用 PID 和 body.sign 认证。不需要 Bearer、签名请求头或 Client-Type。服务端请求不发送 Origin;如配置了服务端 IP 白名单,请使用允许的出口 IP。
- 后端签名并请求下单
- 保存 trade_id
- 打开收银台 / 展示付款信息
- 商户后端接收 Webhook
本次没有公开的服务端签名查单 API。SDK 的会话查询属于收银台通信,不能当成通用商户查单接口。服务端创建的会话绑定官方收银台 Origin,不要把会话凭证用于任意域名查询。
下单参数
两种接入方式共用以下字段。请求必须是 JSON object,所有字段值均为字符串;不接受数字、布尔值、数组或 null。金额不要使用 JavaScript number。
| 字段 | 必填 | 说明 |
|---|---|---|
pid | 是 | 已启用商户的 PID。 |
merchant_order_no | 是 | 商户订单号,去首尾空白后非空,最多 64 个字符;同 PID 永久不可复用。 |
amount | 是 | 正数十进制字符串,整数部分 1–10 位,最多 2 位小数;建议固定两位。换算为 CNY 后至少 ¥1.00。 |
currency | 否 | CNY / USDT,传入时参与签名。微信/支付宝仅 CNY;链上支持 USDT 计价。省略时 USDT 支付使用商户默认币种,其余默认 CNY,建议显式传入。 |
name | 是 | 非空商品或订单名称;保存时去首尾空白,验签仍使用原始值。 |
type | 是 | wechat / alipay / usdt.tron / trx.tron。 |
return_url | 是 | 有效 HTTP(S) 返回地址,用于付款后返回商户页面;不是 Webhook 地址。 |
sign | 是 | 小写 64 位十六进制 HMAC-SHA256。 |
lang | 否 | zh / zh-TW / en,不参与签名;无效值按默认语言处理。 |
Webhook 地址在商户后台配置,请求中不传 notify_url。timestamp、nonce 及其他未知字段会被拒绝(42205)。
重复下单与订单状态
同 PID、同商户订单号、同业务参数,返回原订单当前状态;修改金额、币种、名称、支付方式或返回地址会产生冲突(40902)。金额按等值十进制比较,名称和返回地址按业务规则去首尾空白;lang 不影响幂等。
重复请求不延长到期时间,不重新分配支付金额或收款目标,不重开 paid/cancelled/expired 订单。再次付款请创建新的商户订单号;订单号永久保留。
带 Origin 的请求按该 PID 的浏览器白名单校验;无效 Origin(包括 null)被拒绝。不带 Origin 的请求仍需通过 PID、HMAC 和已配置的服务端 IP 规则。服务端 IP 白名单不用于浏览器请求。
返回参数
两种方式使用相同的订单响应。以下列出常用字段,SDK 内部会话和 WebSocket 凭证由 SDK 自行管理。业务异常通常也使用 HTTP 200 的 JSON 包络。
| 字段 | 类型 | 说明 |
|---|---|---|
code / message | number / string | code=0 表示成功;非 0 时按 message 和错误码处理。HTTP 200 不代表业务成功。 |
data | object | 成功时的订单对象;失败时可能为空数组,先检查 code。 |
data.trade_id / merchant_order_no | string | 平台订单号 / 商户订单号;服务端下单后保存并关联。 |
data.status | string | pending / paid / cancelled / expired;创建成功不等于支付成功。 |
data.amount / currency | string | 商户原始计价金额(两位小数)和币种。 |
data.pricing_amount | string | 按创建订单时汇率换算的 CNY 计价金额。 |
data.actual_amount / actual_amount_text | string | 买家实际应付支付资产数量,可能有金额偏移;付款展示以此为准,勿用来核对商品原价。 |
data.token / network / environment | string | 支付资产、网络和环境;扫码环境为空,链上为 nile/mainnet。 |
data.qr_code / receive_address | object / string | 仅待支付时提供。二维码为 Base64 SVG 或图片 URL;链上提供收款地址。 |
data.checkout_url | string | null | 待支付时用于打开独立收银台;终态为 null。 |
data.created_at / expires_at | string | 包含时区的 ISO 8601 时间;重试不续期。 |
data.return_url | string | 订单保存的返回地址。 |
查看待支付响应示例
{
"code": 0,
"message": "success",
"data": {
"trade_id": "PG20261026000000DEMO0001",
"merchant_order_no": "DEMO-20261026-001",
"status": "pending",
"amount": "10.00",
"currency": "CNY",
"pricing_amount": "10.00",
"actual_amount": "10.01",
"token": "CNY",
"network": "alipay",
"environment": "",
"checkout_url": "https://app.paygo2.uk/checkout/EXAMPLE_NOT_A_REAL_TOKEN",
"expires_at": "2026-10-26T12:30:00+08:00"
}
}仅展示核心字段;示例收银台 URL 为虚构值,不可用于付款。二维码 format=svg 时 data 为 Base64;format=image 时读取 url 和 mime。
已支付、已取消或已过期的重试响应不再发放支付入口:checkout_url、checkout_token、ws_token 为 null,二维码等待支付专用字段省略。相同订单重试不保证 JSON 完全相同,待支付时可能刷新短期会话凭证。
支付结果通知
两种方式都通过商户后端接收支付通知。PayGo 向商户后台配置的 Webhook 地址发送 POST application/json;所有 body 字段均为字符串,签名直接放在 body.sign。
| 字段 | 说明 |
|---|---|
pid / trade_id / merchant_order_no | 商户 PID、平台订单号、商户订单号,用于绑定并核对本地业务订单。 |
amount | CNY 计价金额字符串,即使原始订单以 USDT 计价,此字段仍是 CNY。 |
order_amount / order_currency | 总是返回商户原始金额和币种;核对商品原价使用这两个字段。 |
type / status | 支付方式;当前成功通知固定 status=paid。 |
event_id | 同一订单的支付事件标识,重试和人工重发保持不变;以验签后的 body 为准。 |
sign | body 参数 HMAC-SHA256 签名;排除 sign,其余字段全部参与。 |
{
"pid": "10001",
"trade_id": "PG20261026000000DEMO0001",
"merchant_order_no": "DEMO-20261026-001",
"amount": "10.00",
"type": "alipay",
"status": "paid",
"order_currency": "CNY",
"order_amount": "10.00",
"event_id": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"sign": "ab08e5ca3eb01e162140cdde97ef9b48404e70b9728dc473e9b21d03af0918ed"
}例如原始订单为 2.00 USDT,按创建时汇率折算为 14.00 CNY:Webhook 的 order_amount="2.00"、order_currency="USDT"、amount="14.00"。核对本地售价使用前两个字段,不使用实际付款偏移金额。
不再使用时间戳、nonce 或签名请求头。X-PayGo-Event-Id 仅作为追踪用冗余请求头;业务以已验签的 body.event_id 为准。
PHP Webhook 验签示例
获取 JSON 参数,计算并比对签名,通过后输出 success。业务处理由商户自行实现。
<?php
// 1. 获取参数
$params = json_decode(file_get_contents('php://input'), true);
$sign = $params['sign'] ?? '';
unset($params['sign']);
// 2. 计算并验证签名
ksort($params, SORT_STRING);
$pairs = [];
foreach ($params as $key => $value) {
$pairs[] = $key . '=' . rawurlencode($value);
}
$expected = hash_hmac('sha256', implode('&', $pairs), getenv('PAYGO_SECRET'));
if (!hash_equals($expected, $sign)) {
http_response_code(401); exit('fail');
}
// 3. 输出 success
echo 'success';确认、重试与重复通知
事务提交成功后返回 HTTP 200、纯文本 success。不是 JSON 字符串、JSON 对象或 HTML。已处理过的合法重复通知也返回 success;验签或业务核对失败时不要确认成功。
HTTP/1.1 200 OK Content-Type: text/plain; charset=utf-8 success
首次立即投递;失败后依次等待 60、300、1800、7200、43200 秒再尝试,最多共 6 次,每次超时 10 秒。实际调度可能延迟。非 2xx、网络错误或响应正文去首尾空白后不是 success 都会重试;失败耗尽后可由后台人工重发。
通知采用至少一次投递,重试和人工重发保持 event_id 不变;密钥轮换可能改变 sign,因此不能用 sign 去重。请持久保存订单履约状态和交易绑定,依靠唯一键与事务防止重复发货,不要只用短期缓存。外部发货或开通服务也需使用稳定幂等键。
签名规则
下单和 Webhook 使用同一套参数签名算法。它针对解析后的字符串参数,不针对原始 JSON 文本;JSON 缩进和字段顺序不影响签名。
- 排除 sign;下单另排除 lang。Webhook 除 sign 外的全部字段都参与,不要只挑选部分字段。
- 按字段名字典序升序排列;每个原始 UTF-8 字符串值按 RFC 3986 编码,再以 key=value 用 & 连接。
- 空格编码为 %20,不是 +;JS encodeURIComponent 还需编码 !'()*。不添加末尾 &、路径、请求方法、换行或 SECRET。
- SECRET 原始字符串作为密钥,计算 HMAC-SHA256,输出小写 64 位十六进制。看似 hex 的 SECRET 也不能先解码。验签使用常量时间比较。
共用 PHP 签名示例
<?php
function paygoSign(array $fields, string $secret, array $exclude = []): string
{
unset($fields['sign']);
foreach ($exclude as $key) unset($fields[$key]);
ksort($fields, SORT_STRING);
$pairs = [];
foreach ($fields as $key => $value) {
if (!is_string($value)) {
throw new InvalidArgumentException('Expected string: ' . $key);
}
$pairs[] = $key . '=' . rawurlencode($value);
}
return hash_hmac('sha256', implode('&', $pairs), $secret);
}
// 从服务端业务订单获取参数
$fields = [
'pid' => getenv('PAYGO_PID'),
'merchant_order_no' => $order->number,
'amount' => $order->amount, // 金额使用字符串,例如 '10.00'
'currency' => 'CNY',
'name' => $order->name,
'type' => 'alipay',
'return_url' => 'https://merchant.example/pay/result',
];
$fields['sign'] = paygoSign($fields, getenv('PAYGO_SECRET'), ['lang']);此签名没有时间窗或一次性随机数。已签名请求可重复提交;未曾成功建单的请求在密钥有效期间仍可首次建单。已存在订单按幂等规则返回原状态;重置 SECRET 或禁用凭据后,旧签名失效。
签名核对示例
以下使用虚构 SECRET 和固定参数,只用于核对算法,不可直接用于真实下单。商品名包含中文、空格、加号和斜线,可帮助排查编码差异。
下载 JSON 测试向量下单完整测试向量
SECRET = paygo_demo_secret_20261026_NOT_REAL
parameters =
{
"pid": "10001",
"merchant_order_no": "DEMO-20261026-001",
"amount": "10.00",
"currency": "CNY",
"name": "测试商品 A+B / ~",
"type": "alipay",
"return_url": "https://merchant.example/pay/result?order=001&from=sdk",
"lang": "zh"
}
canonical =
amount=10.00¤cy=CNY&merchant_order_no=DEMO-20261026-001&name=%E6%B5%8B%E8%AF%95%E5%95%86%E5%93%81%20A%2BB%20%2F%20~&pid=10001&return_url=https%3A%2F%2Fmerchant.example%2Fpay%2Fresult%3Forder%3D001%26from%3Dsdk&type=alipay
sign =
63a468bc5628f0bb508494fd9c0e6c646550a7c412da926b24bf56eb6b71cd78Webhook 完整测试向量
SECRET = paygo_demo_secret_20261026_NOT_REAL
parameters =
{
"pid": "10001",
"trade_id": "PG20261026000000DEMO0001",
"merchant_order_no": "DEMO-20261026-001",
"amount": "10.00",
"type": "alipay",
"status": "paid",
"order_currency": "CNY",
"order_amount": "10.00",
"event_id": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}
canonical =
amount=10.00&event_id=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef&merchant_order_no=DEMO-20261026-001&order_amount=10.00&order_currency=CNY&pid=10001&status=paid&trade_id=PG20261026000000DEMO0001&type=alipay
sign =
ab08e5ca3eb01e162140cdde97ef9b48404e70b9728dc473e9b21d03af0918ed支付方式
微信个人收款码,需已验证且启用。
支付宝个人收款码,需已验证且启用,并满足设备可用条件。
TRON 网络 USDT,需对应网络已启用钱包。
TRON 网络 TRX,需对应网络已启用钱包。
可用性取决于商户启用状态、订阅权益和收款配置。链上支付展示实际应付数量、资产、网络和环境,不能把 CNY 计价金额直接当作转账数量。
错误码
先检查 code,再读取 data。排查时结合 message 和 requestId;不要在错误日志中记录 SECRET、完整签名参数或会话凭证。
| Code | 说明 |
|---|---|
40001 | 必需收款、通知或汇率配置不可用,查看 message。 |
40101 | 商户凭据无效或会员未启用。 |
40104 | 签名格式错误或不匹配,检查原始字符串和编码。 |
40105 / 40305 | 收银台会话 token 无效,或查询来源不匹配。 |
40301 / 40320 | 支付方式未启用,或商户订阅未开通/已过期。 |
40302 / 40303 | 该 PID 的 Origin 未获准,或 Origin 无效。 |
40306 | 服务端出口 IP 不在允许范围。 |
40401 / 40402 | 订单、商户或会话不存在,或会话已撤销。 |
40901 | 资源或钱包状态冲突等,查看 message;不再表示 nonce 重放。 |
40902 | 同订单号业务参数不同,或订单号已保留但明细缺失。 |
40903 | 当前支付金额分配已满。 |
41001 | 收银台会话已过期;终态下单重试仍返回原订单。 |
42201 / 42202 | 业务参数、币种、资产或金额不合法,检查精度和最低金额。 |
42203 | return_url 不是有效 HTTP(S) URL。 |
42204 / 42205 | body 不是 JSON object,或字段未知、缺失、非字符串、必填值为空。 |
50001 / 50302 | 支付会话创建失败,或支付宝收款设备离线。 |