CHAINNETPAY OPEN API

用一套清晰接口，接入 USDT 收款

面向网站、移动应用和平台系统提供统一支付订单能力。支付页可展示 TRON、Ethereum、Polygon 等已启用网络，商户订单固定直达商户钱包，回调地址由商户管理平台统一配置。

2%标准支付手续费

3TRON / Ethereum / Polygon

Whitelist可选服务端 IP 白名单

快速开始

支付链路始终由商户后端创建订单。前端只负责打开支付页、唤起钱包或展示二维码，不应保存商户 Key、Secret，也不应自行判定链上到账。

1完成商户认证

提交应用名称、应用地址和邮箱，并完成邮箱验证码校验。

2配置应用与收款链

启用商户自有收款网络和地址，配置回调地址，并按需限制服务端 IP。

3服务端创建订单

携带商户凭证与商品 ID，提交金额和业务订单号。

4接收到账通知

用户钱包支付后，商户后端验签并幂等更新订单。

商户与订单

每次创建或查询订单，都必须使用商户 Secret 对请求方法、路径、原始查询串、身份头和原始请求体摘要进行 HMAC-SHA256 签名。Secret 只在创建或轮换时展示一次，仅限商户服务端保存和使用，绝不能作为请求头明文传输，也不能写入网页、移动 App、日志或公开仓库。

REQUEST HEADERSHTTPS ONLY

X-Merchant-Key: YOUR_MERCHANT_KEY
X-Product-Id: YOUR_PRODUCT_ID
X-Timestamp: 1786262400
X-Request-Id: REQUEST-20260809-0001
X-Signature: HMAC_SHA256_HEX
Content-Type: application/json
Accept: application/json

请求头	必填	说明
`X-Merchant-Key`	是	商户身份标识，由平台在认证通过后分配。
`X-Product-Id`	是	应用标识，决定可选支付网络、回调地址和可选 IP 白名单。
`X-Timestamp`	是	当前 Unix 时间戳，用于限制请求有效期。
`X-Request-Id`	是	每次请求的唯一标识，便于幂等控制与问题排查。
`X-Signature`	是	使用商户 Secret 计算的 HMAC-SHA256 小写十六进制签名。

CANONICAL REQUEST字段之间使用 \n

HTTP_METHOD
REQUEST_PATH
RAW_QUERY_STRING
X-Merchant-Key
X-Product-Id
X-Timestamp
X-Request-Id
SHA256_HEX(RAW_REQUEST_BODY)

X-Signature = hex(HMAC-SHA256(MERCHANT_SECRET, canonical_request))

签名必须基于原始字节

请求路径不包含域名；没有查询参数时第三行保留为空行。查询串使用实际发送的原始顺序与编码，请求体摘要使用实际发送的 UTF-8 原始字节。签名输出为小写十六进制。

创建支付订单

POSThttps://api.chainnetpay.com/openapi/order/create/v1

支付手续费率：2%

支付手续费按订单金额的当前有效费率计算并保留两位小数，单笔最低0.01 USDT。

Bash + cURLCREATE ORDER

merchant_key='YOUR_MERCHANT_KEY'
merchant_secret='YOUR_MERCHANT_SECRET'
product_id='YOUR_PRODUCT_ID'
timestamp="$(date +%s)"
request_id='REQUEST-20260809-0001'
path='/openapi/order/create/v1'
body='{"order_id":"CNP-20260809-001","amount":"1280.00"}'
body_hash="$(printf '%s' "$body" | openssl dgst -sha256 -hex | awk '{print $2}')"
canonical="$(printf '%s\n%s\n%s\n%s\n%s\n%s\n%s\n%s' \
  'POST' "$path" '' "$merchant_key" "$product_id" "$timestamp" "$request_id" "$body_hash")"
signature="$(printf '%s' "$canonical" | openssl dgst -sha256 -hmac "$merchant_secret" -hex | awk '{print $2}')"

curl --request POST \
  --url https://api.chainnetpay.com/openapi/order/create/v1 \
  --header "X-Merchant-Key: $merchant_key" \
  --header "X-Product-Id: $product_id" \
  --header "X-Timestamp: $timestamp" \
  --header "X-Request-Id: $request_id" \
  --header "X-Signature: $signature" \
  --header 'Content-Type: application/json' \
  --data-raw "$body"

字段	类型	必填	说明
`order_id`	String	是	商户侧唯一业务订单号，用于幂等和对账。
`amount`	String	是	USDT 订单金额，建议使用字符串避免精度问题。

网络与回调地址无需随订单提交

币种固定为 USDT。创建订单后，用户在支付页选择网络分配商户收款地址。

响应示例

200 OKJSON

{
  "order_id": "CNP-20260809-001",
  "payment_order_id": "CNP178626240012345",
  "status": "PENDING",
  "payment_url": "https://www.chainnetpay.com/pay/...",
  "expire_time": "2026-09-05T15:30:00"
}

主动查询订单

GEThttps://api.chainnetpay.com/openapi/order/query/v1?order_id=YOUR_ORDER_ID

查询接口同样需要 Merchant Key、Product ID、Timestamp、Request ID 和 HMAC 签名；规范字符串中的方法为 GET、请求体 SHA-256 使用空字节摘要，第三行必须是实际发送的原始查询串。该接口可用于回调补偿、人工核验与定时对账。支付页显示倒计时，未检测到转账的订单到期后进入 EXPIRED，不能继续付款。

商户收款方式

DIRECT ONLY

直接收款到商户地址

用户支付的 USDT 直接进入商户预先配置的链上地址，资金路径更直接。

商户需提前充值手续费余额。
创建订单时先校验手续费余额；余额不足直接返回错误，不创建支付订单。
用户选定支付网络并成功分配收款地址时，按当前有效收款费率预扣手续费，最低0.01 USDT。
订单最终关闭或正常过期时自动退回预扣手续费；支付成功则完成扣费。
应持续保持手续费余额充足，避免影响后续收款服务。

WALLET SAFETY

收款地址必须专用于平台订单

录入 ChainNetPay 的商户收款地址会参与自动订单匹配，不得绕过平台私自使用。

禁止私自使用已录入地址收取相同金额的款项。
私自收款可能被系统匹配到有效订单，造成错单、重复入账或资金损失。
由此产生的损失及争议由商户自行承担。
需要独立收款时，请使用未录入平台的其他钱包地址。

收款与 IP 白名单

商户认证通过后，可在商户管理平台维护接入配置。

01回调地址

配置接收支付结果的 HTTPS 服务端地址，变更前应先完成连通性和验签测试。

02IP 白名单（可选）

留空时依赖 API 签名鉴权；配置后只允许指定的商户服务端公网出口 IP 调用 Open API。

03支付网络

启用商户可收款的具体网络。Polygon 虽使用 ERC20 代币标准，但属于独立网络，必须单独配置 RPC、USDT 合约和收款地址。

04收款方式

商户订单固定使用商户自有钱包地址直收；创建订单前检查手续费余额和可用收款地址。

白名单配置要点

需要额外限制来源时，请填写真实公网出口 IP。配置白名单后，多台服务端或多出口网络应逐一加入；未在白名单内的请求将被拒绝。

异步通知

WEBHOOK SIGNATUREHMAC-SHA256

signed_content = X-ChainNetPay-Timestamp + "." + raw_request_body
signature = hex(HMAC-SHA256(MERCHANT_SECRET, signed_content))

X-ChainNetPay-Event: payment.success
X-ChainNetPay-Event-Id: evt_payment_123456
X-ChainNetPay-Delivery-Id: 8db27f89-...
X-ChainNetPay-Timestamp: 1786262400
X-ChainNetPay-Signature: 8c35...

✓仅配置 HTTPS 回调地址，并限制允许的请求方法。
✓验签成功后再读取支付状态、交易哈希和确认数。
✓使用 order_id 或平台订单号建立唯一约束，保证幂等。
✓成功处理后返回 2xx；失败时记录原因并允许安全重试。

状态与错误处理

PENDING

等待用户支付。

SUBMITTED

钱包已返回交易哈希，后端正在独立复核。

CONFIRMING

兼容历史订单的确认中状态；新订单检测到真实上链交易后直接成功。

MANUAL_REVIEW

兼容确认异常的历史订单，订单及地址金额占用被冻结并等待人工复核。

SUCCESS / EXPIRED / FAILED

已检测到有效上链交易、未付款超时或人工确认付款失败。

字段命名、签名算法、时间戳容差、确认数、结算规则和完整错误码，最终以生产环境分配的接口规范为准。