皇冠pay (CrownPay) - 商户开放平台 API 对接开发文档

SECTION 01

业务接入时序与核心说明

皇冠pay 为企业商户提供高可用、多链整合的虚拟货币（USDT-TRC20 / TON / ERC20 等）即时收单服务。支持商户通过标准 HTTP RESTful 协议创建支付订单、获取收银台支付链接、通过 JS SDK 嵌入前端网页，并在用户到账后接收自动化 Webhook 回调通知进行上分结算。

1

商户系统发起下单

调用 /order/create 传入金额与订单号

2

唤起收银台付款

跳转收银链接或使用 SDK 弹窗注入展示

3

链上极速确认

系统全自动监听入金并触发结算

4

异步 Webhook 回调

POST 回调通知商户服务器自动上分

API 网关基准地址 (Base URL): https://hgdb.app/api/v1

通信协议: HTTPS POST / GET (Content-Type: application/json)

测试商户号 (mch_id): mch_crownpay_001

测试密钥 (secret_key): cp_sec_888888889999abcd

SECTION 02

安全签名算法规则 (Sign Generation)

为保障资金通信安全，商户在发起请求及接收异步回调通知时，均须采用标准 MD5 摘要算法进行签名校验：

第一步：筛选所有非空请求参数（剔除参数值为空的字段以及 sign 字段本身）；

第二步：将剩余参数按照参数名的 ASCII 码从小到大排序（字典序）；

第三步：使用 URL 键值对格式拼接成字符串：k1=v1&k2=v2&k3=v3；

第四步：在拼接字符串末尾追加商户密钥：&key=YOUR_SECRET_KEY；

第五步：对上述完整字符串进行 MD5 运算，并将计算得到的 32 位哈希值转为小写字母，即为最终 sign。

SECTION 03

统一下单接口 (Create Order)

POST /api/v1/order/create

请求参数 (Request Body)

参数名	类型	必填	说明
mch_id	String	是	皇冠pay 分配的商户唯一识别码
out_trade_no	String	是	商户系统内部订单号（须保证全局唯一）
amount	Number/Str	是	订单金额，单位 USDT，保留2位小数，如 "100.00"
currency	String	否	收款网络协议，默认 "USDT-TRC20"，支持 USDT-TON / USDT-ERC20
subject	String	否	商品标题或充值描述，如 "VIP 会员充值"
notify_url	String	推荐	支付成功后的异步 Webhook 回调推送地址
return_url	String	否	用户支付完成后收银台前端自动跳转地址
sign	String	是	请求签名，按标准签名算法生成

响应示例 (Response JSON)

{
  "code": 0,
  "message": "success",
  "data": {
    "order_id": "CP202610041530229871",
    "out_trade_no": "2026100412345678",
    "amount": "100.00",
    "currency": "USDT-TRC20",
    "pay_url": "https://hgdb.app/pay.html?order_id=CP202610041530229871",
    "pay_address": "TX8mK89gR2Y29kLpMn4QWjVkN6611CrownPay",
    "expire_at": 1728045900,
    "status": "PENDING"
  }
}

SECTION 04

订单状态查询接口 (Query Order)

GET /api/v1/order/query?order_id=CP...

商户系统可主动轮询查询某笔订单的实时支付状态（参数支持 order_id 或 out_trade_no）。

{
  "code": 0,
  "message": "success",
  "data": {
    "order_id": "CP202610041530229871",
    "out_trade_no": "2026100412345678",
    "amount": "100.00",
    "currency": "USDT-TRC20",
    "status": "PAID",
    "created_at": 1728045000,
    "paid_at": 1728045042,
    "tx_hash": "0x98fbc127d4289ea61a29f8c09211c47395ba..."
  }
}

SECTION 05

异步回调通知 (Webhook Notification)

当用户在收银台付款成功且链上确认后，皇冠pay 服务器会主动向商户下单时提供的 notify_url 发起 HTTP POST 请求，推送支付结果：

{
  "mch_id": "mch_crownpay_001",
  "order_id": "CP202610041530229871",
  "out_trade_no": "2026100412345678",
  "amount": "100.00",
  "currency": "USDT-TRC20",
  "status": "PAID",
  "tx_hash": "0x98fbc127d4289ea61a29f8c09211c47395ba...",
  "timestamp": 1728045045,
  "sign": "3f9824c08e5c12019b84b..."
}

商户响应要求：

商户服务器在接收到通知并使用商户密钥校验签名无误后，应当给会员账号执行上分发货操作，并在 HTTP 响应中直接输出纯文本字符串：SUCCESS。

SECTION 06

网页端 JS SDK 一键注入方案

如果商户希望在自己的网页平台内部“无跳转、无缝弹出收银台”，只需在网站 HTML 中引入一行皇冠pay 注入脚本：

<!-- 1. 在客户网页中引入皇冠pay注入SDK -->
<script src="https://hgdb.app/sdk/crownpay.js"></script>

<!-- 2. 点击充值按钮时唤起弹窗 -->
<script>
  function handleRecharge(orderId) {
    CrownPay.open({
      orderId: orderId, // 下单接口返回的 order_id
      onSuccess: function(order) {
        alert('支付成功！已收到款项');
        window.location.reload();
      },
      onClose: function() {
        console.log('用户关闭了收银台');
      }
    });
  }
</script>

SECTION 07

多语言签名生成示例代码

PHP 示例:

function makeSign($params, $secret) {
    ksort($params);
    $arr = [];
    foreach ($params as $k => $v) {
        if ($k !== 'sign' && $v !== '' && $v !== null) {
            $arr[] = "$k=$v";
        }
    }
    return strtolower(md5(implode('&', $arr) . '&key=' . $secret));
}

Python 示例:

import hashlib

def make_sign(params: dict, secret: str) -> str:
    sorted_items = sorted([f"{k}={v}" for k, v in params.items() if k != 'sign' and v is not None and v != ''])
    raw_str = "&".join(sorted_items) + f"&key={secret}"
    return hashlib.md5(raw_str.encode('utf-8')).hexdigest().lower()

Node.js (JavaScript) 示例:

const crypto = require('crypto');

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

SECTION 08 · 开发者工具

在线沙箱测试控制台 (Sandbox Playground)

商户技术人员可在此直接生成签名、发起真实 HTTP 订单请求，并一键呼出收银台检验：

商户号 (mch_id):

商户密钥 (secret_key):

商户订单号 (out_trade_no):

充值金额 (amount USDT):

付款币种 (currency):

商品名称 (subject):

请求与响应 JSON 报文:

// 点击上方按钮发起联调测试