API 接入文档

用最少的接口，把支付链路接完整

当前版本提供创建订单、查询订单、异步回调三块核心能力。商户接入后，可把用户直接引导到独立支付页完成付款。

签名校验订单查询异步回调多支付方式返回

1. 接入前准备

商户侧只需要准备固定的商户标识、签名密钥和回调地址。

merchant_id平台分配的商户编号，用于识别调用方。

api_key用于请求签名和回调验签，请仅保存在服务端。

notify_url支付成功后的服务端回调地址，用于更新业务订单状态。

return_url用户在支付页完成操作后返回的商户查询页或结果页。

2. 签名规则

所有请求和回调都使用相同的签名规则，方便商户统一处理。

1) 去掉 sign 字段
2) 按参数名升序排序
3) 跳过空值、数组、对象
4) 拼接成 key=value&key=value 字符串
5) 使用 HMAC-SHA256(api_key) 计算签名
6) 输出十六进制小写字符串

3. 创建订单

商户下单后，服务端调用创建订单接口，获取支付页地址和可用支付方式。

POST https://pay-coinex.com/api/order/create.php

请求参数

merchant_id商户编号，必填

order_no商户订单号，必填，需唯一

amount法币金额，必填，最低 1

title订单标题，可选

notify_url覆盖默认回调地址，可选

return_url覆盖默认返回地址，可选

contact买家联系方式，可选

sign请求签名，必填

请求示例

merchant_id=qqshop-main
order_no=OD202604260001
amount=29.90
title=Premium Account
notify_url=https://merchant.example/callback
return_url=https://merchant.example/query
contact=buyer_10001
sign=xxxxxxxx

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "gateway_order_no": "PAY202604260001ABCD",
    "order_no": "OD202604260001",
    "status": "pending",
    "pay_url": "https://pay-coinex.com/checkout.php?order_no=PAY202604260001ABCD",
    "query_url": "https://pay-coinex.com/api/order/query.php?merchant_id=qqshop-main&order_no=OD202604260001",
    "pay_amount": "29.900",
    "amount": "29.90",
    "network": "Tron",
    "token": "USDT",
    "wallet_address": "T...",
    "method_code": "trc20_usdt",
    "payment_options": []
  }
}

4. 查询订单

商户可按商户订单号查询当前状态，适合补查、轮询或后台手动核对。

GET / POST https://pay-coinex.com/api/order/query.php

请求参数

merchant_id商户编号，必填

order_no商户订单号，必填

sign请求签名，必填

返回重点字段

statuspending / paid / expired

status_label状态中文说明

pay_amount订单当前应付金额

paid_amount实际到账金额

token / network到账币种与网络

txid链上交易哈希

5. 支付成功回调

系统确认到账后，会把支付结果推送到商户 `notify_url`。商户应在服务端验签并更新业务订单。

merchant_id商户编号

gateway_order_no平台支付订单号

order_no商户订单号

status当前订单状态，支付成功时为 paid

amount法币金额

pay_amount / paid_amount应付金额 / 实付金额

network / token / method_code支付方式信息

txid / paid_at链上交易哈希与支付时间

timestamp / sign时间戳与签名

6. 推荐接入顺序

先跑通最短路径，再逐步补管理能力。

本地生成签名并调用创建单

先确保商户系统能拿到支付页地址。

跳转支付页进行真实测试

至少完成一笔小额支付，确认到账状态更新。

校验回调并落业务状态

收到 paid 回调后，再发货或开通服务。

补查单与售后查询页

用于异常订单补查和客服协助处理。