PAYGO · DEVELOPER GUIDE

PayGo 开发文档

选择适合你的接入方式,创建支付订单,并通过服务端通知确认支付结果。

接入概览

两种方式共用下单接口、签名规则和 Webhook。区别在于谁向 PayGo 发起下单请求,以及如何展示收银台。

两种方式都需要商户后端。SECRET 仅保存在后端;浏览器事件和返回页面均不能作为发货、充值或开通服务的依据。

准备工作

  1. 在商户后台获取 PID、SECRET,配置已启用的收款方式和 Webhook 地址。
  2. SDK 接入:登记付款页面的精确 Origin(协议、域名、端口,不含路径)。服务端 API:按需配置服务器 IP 白名单。
  3. 先在自己的后端创建业务订单,确定真实金额、币种和商户订单号,再签名。不要直接信任浏览器提交的金额。

SECRET 不可放入前端代码、移动端、公开仓库或日志。已签名参数和收银台链接也应作为订单访问凭证保护。

方式一:Browser SDK

适合在自己的网页中内嵌收银台。商户后端仅生成签名参数;由浏览器中的 SDK 向 PayGo 下单,并展示付款信息、倒计时和订单状态。

  1. 商户后端签名
  2. PayGo.mount()
  3. SDK 下单并展示收银台
  4. 商户后端接收 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,或使用返回的二维码、应付金额和地址展示付款信息。

POST
https://api.paygo2.uk/api/v1/orders

Content-Type: application/json

使用 PID 和 body.sign 认证。不需要 Bearer、签名请求头或 Client-Type。服务端请求不发送 Origin;如配置了服务端 IP 白名单,请使用允许的出口 IP。

  1. 后端签名并请求下单
  2. 保存 trade_id
  3. 打开收银台 / 展示付款信息
  4. 商户后端接收 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 / messagenumber / stringcode=0 表示成功;非 0 时按 message 和错误码处理。HTTP 200 不代表业务成功。
dataobject成功时的订单对象;失败时可能为空数组,先检查 code。
data.trade_id / merchant_order_nostring平台订单号 / 商户订单号;服务端下单后保存并关联。
data.statusstringpending / paid / cancelled / expired;创建成功不等于支付成功。
data.amount / currencystring商户原始计价金额(两位小数)和币种。
data.pricing_amountstring按创建订单时汇率换算的 CNY 计价金额。
data.actual_amount / actual_amount_textstring买家实际应付支付资产数量,可能有金额偏移;付款展示以此为准,勿用来核对商品原价。
data.token / network / environmentstring支付资产、网络和环境;扫码环境为空,链上为 nile/mainnet。
data.qr_code / receive_addressobject / string仅待支付时提供。二维码为 Base64 SVG 或图片 URL;链上提供收款地址。
data.checkout_urlstring | null待支付时用于打开独立收银台;终态为 null。
data.created_at / expires_atstring包含时区的 ISO 8601 时间;重试不续期。
data.return_urlstring订单保存的返回地址。
查看待支付响应示例
{
  "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、平台订单号、商户订单号,用于绑定并核对本地业务订单。
amountCNY 计价金额字符串,即使原始订单以 USDT 计价,此字段仍是 CNY。
order_amount / order_currency总是返回商户原始金额和币种;核对商品原价使用这两个字段。
type / status支付方式;当前成功通知固定 status=paid。
event_id同一订单的支付事件标识,重试和人工重发保持不变;以验签后的 body 为准。
signbody 参数 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 缩进和字段顺序不影响签名。

  1. 排除 sign;下单另排除 lang。Webhook 除 sign 外的全部字段都参与,不要只挑选部分字段。
  2. 按字段名字典序升序排列;每个原始 UTF-8 字符串值按 RFC 3986 编码,再以 key=value 用 & 连接。
  3. 空格编码为 %20,不是 +;JS encodeURIComponent 还需编码 !'()*。不添加末尾 &、路径、请求方法、换行或 SECRET。
  4. SECRET 原始字符串作为密钥,计算 HMAC-SHA256,输出小写 64 位十六进制。看似 hex 的 SECRET 也不能先解码。验签使用常量时间比较。
签名前后保持字符串原样:不要自动 trim、格式化金额、转换大小写或过滤空字符串。金额为 "10.00" 时,不能改成数字 10 再计算。

共用 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&currency=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 =
63a468bc5628f0bb508494fd9c0e6c646550a7c412da926b24bf56eb6b71cd78
Webhook 完整测试向量
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

支付方式

wechat

微信个人收款码,需已验证且启用。

alipay

支付宝个人收款码,需已验证且启用,并满足设备可用条件。

usdt.tron

TRON 网络 USDT,需对应网络已启用钱包。

trx.tron

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业务参数、币种、资产或金额不合法,检查精度和最低金额。
42203return_url 不是有效 HTTP(S) URL。
42204 / 42205body 不是 JSON object,或字段未知、缺失、非字符串、必填值为空。
50001 / 50302支付会话创建失败,或支付宝收款设备离线。