跳到主要内容

创建收款订单

创建一笔收款会话。返回一个托管支付页 payUrl，玩家在该页面选择金额和通道并用自己的手机完成支付。订单进入终态时，服务端通过 Webhook 通知你。

你不会看到收款代理号、交易号或 SMS。收款环节由托管页负责；你的职责是：开会话 → 收 webhook → 给玩家上分。

接口​

  • 端点: POST {API_BASE}/pay/order/create
  • API_BASE: https://api.168tonpay.xyz/api/v1/compat/godapay
  • 认证: 请求体 MD5 排序签名（见 认证）

请求体​

参数类型必需描述
merchantIdstring (UUID)✅你的商户 ID
orderNostring✅你系统的订单号，≤ 32 字符。(merchantId, orderNo) 唯一且幂等
returnUrlstring✅完成回调 webhook 的接收地址
playerPhonestring✅玩家已登记的 MSISDN（01[3-9]XXXXXXXX）。关键风控信号：付款 SMS 的发送号必须与之匹配才能自动放行。由你从自己的玩家资料中查出，玩家不手填
playerRefstring✅你的不透明玩家 ID，≤ 64 字符，会在 webhook 中回传
isTestboolean❌沙箱标志。仅对 demo 商户生效；正式商户传 true 会收到 400
signaturestring✅MD5 排序签名

请求示例​

cURL​

curl -X POST "${API_BASE}/pay/order/create" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "aef6025b-f435-443c-bb18-f10e65d9314c",
    "orderNo": "ORD-001",
    "returnUrl": "https://your-server.example/webhook",
    "playerPhone": "01711000000",
    "playerRef": "player_123",
    "signature": "d41d8cd98f00b204e9800998ecf8427e"
  }'

Node.js​

const crypto = require('crypto');

function sign(params, apiSecret) {
  const signStr = Object.keys(params)
    .filter((k) => k !== 'signature' && params[k] != null)
    .sort()
    .map((k) => `${k}=${params[k]}`)
    .join('&') + `&key=${apiSecret}`;
  return crypto.createHash('md5').update(signStr).digest('hex').toLowerCase();
}

async function createDeposit({ orderNo, playerPhone, playerRef }) {
  const body = {
    merchantId: process.env.MERCHANT_ID,
    orderNo,
    returnUrl: 'https://your-server.example/webhook',
    playerPhone,
    playerRef,
  };
  body.signature = sign(body, process.env.API_SECRET);

  const res = await fetch(`${process.env.API_BASE}/pay/order/create`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
  return res.json();
}

响应（200 OK）​

{
  "code": 0,
  "data": {
    "merchantId": "aef6025b-f435-443c-bb18-f10e65d9314c",
    "orderNo": "ORD-001",
    "platformOrderNo": "0b8a4f32-1c1e-4a1c-9b25-3a9c2e0f7d5b",
    "payCode": "PAY-5MKYIKXPU",
    "payUrl": "https://pay.168tonpay.xyz/pay/0b8a4f32-1c1e-4a1c-9b25-3a9c2e0f7d5b"
  }
}

字段说明​

字段类型描述
codenumber0 表示成功
merchantIdstring你的商户 ID
orderNostring你提交的订单号
platformOrderNostring平台订单 ID，用作去重键
payCodestring支付参考码（托管页内部使用）
payUrlstring托管支付页地址 —— 用 iframe 或新标签页打开给玩家

玩家支付流程​

1. 你调用 POST /pay/order/create（服务端、已签名）
   ↓
2. 平台返回 payUrl
   ↓
3. 你为玩家打开 payUrl（iframe 或新标签页）
   ↓
4. 玩家在托管页选择金额 + 通道，用自己的手机付款
   ↓
5. 平台匹配到付款 SMS，向你的 returnUrl 发送 webhook
   ↓
6. 你的服务端验签，用 webhook 里的 amount 给玩家上分

幂等性​

(merchantId, orderNo) 唯一，这就是幂等保证：

  • 创建请求若因网络抖动状态未知，用 同一个 orderNo 重试是安全的。
  • 首次成功创建订单；重复 orderNo 返回原订单的响应，绝不会创建第二笔。
  • 因此请把 orderNo 当幂等键设计，不要随机重生成。

沙箱 / 联调​

请我们把你的商户账户标记为 demo 商户后，创建订单时带 isTest: true：平台会注入一条匹配的合成 SMS，订单完成、webhook 照常触发，全程不涉及真实资金。详见 测试凭证。

下一步​