收单快速入门

流程概览

1. 概述

收单（Payment Order）：Pay Protocol 的收单是商户在平台系统中生成的支付请求，用户可通过支付链接或指定钱包地址完成付款，系统会自动确认支付并回调商户。

流程： 👉 商户调用 createPaymentOrder → 获取支付链接/子合约地址 → 用户支付 → Pay Protocol 回调 → 商户确认。

注意：接口调用环节需要签名

2. 前提条件

开通商户账号：沙盒注册地址
获取 API Key / Secret：获取 API Key / Secret
需要配置 回调地址 (notifyUrl) 和 跳转地址 (redirectionUrl)
确认使用的网络：
- 沙盒环境：https://api-sandbox.payprotocol.network/api/mer
- 生产环境：https://api.payprotocol.network/api/mer

3. API 签名认证

所有请求需要在 Header 中添加：

Header	说明
`X-PAY-KEY`	商户 API Key
`X-PAY-TIMESTAMP`	当前 Unix 时间戳（单位秒，误差 ≤ 60 秒）
`X-PAY-SIGN`	签名，规则请看下面「签名生成规则」

🔹 签名生成规则

参考官方文档：签名规则

拼接字符串

signString = timestamp + method + requestPath + body

timestamp：请求的 Unix 时间戳（秒）
method：HTTP 方法，例如 GET、POST
requestPath：接口路径，不含域名，例如 /api/mer/payment/createPaymentOrder
body：POST 请求的 JSON 字符串，GET 请求为空字符串

使用 HMAC-SHA256 算法

HMAC_SHA256(apiSecret, signString)

Base64 编码

将上一步得到的哈希值进行 Base64 编码，得到最终的 X-PAY-SIGN

🔹 请求头示例（HTTPS）

POST /api/mer/payment/createPaymentOrder
Host: api-sandbox.payprotocol.network
Content-Type: application/json
X-PAY-KEY: <your_api_key>
X-PAY-TIMESTAMP: 1723971200
X-PAY-SIGN: <生成的签名>

🔹 注意事项

所有 POST 请求需带 Content-Type: application/json
timestamp 与服务器时间差值不能超过 60 秒，防止重放攻击
body 必须是有效 JSON，否则签名验证会失败

4. 创建收单订单（createPaymentOrder）

createPaymentOrder 接口文档

请求体参数说明

参数	类型	必填	说明
`chainId`	int32	是	平台内部链 ID，可从查询链列表接口获取
`description`	string	是	订单描述
`outTradeNo`	string	是	商户订单号，必须唯一
`isLegalTender`	int	是	报价币种是否为法币，0=否，1=是
`quoteCurrencySymbol`	string	是	报价币种符号，法币用国际标准符号（USD/CNY），数字货币用币符号（USDT/ETH/TRX）
`quoteAmount`	string	是	报价金额，正数，可带小数
`notifyUrl`	uri	是	商户回调地址，必须为公网可访问 HTTPS 地址
`redirectionUrl`	uri	是	用户支付成功后的跳转地址

请求示例

POST /api/mer/payment/createPaymentOrder
Host: api-sandbox.payprotocol.network
Content-Type: application/json
X-PAY-KEY: your_api_key
X-PAY-TIMESTAMP: 1723971200
X-PAY-SIGN: RlpTCwGT7lECP7achGM4oqT+Y5fXYjOqTRAJ9VPdY2U=

请求体示例

{
  "chainId": 136,
  "description": "购买会员服务 - 月卡",
  "outTradeNo": "ORDER20250818001",
  "isLegalTender": 0,
  "quoteCurrencySymbol": "USDT",
  "quoteAmount": "9.99",
  "notifyUrl": "https://merchant.com/api/pay-callback",
  "redirectionUrl": "https://merchant.com/pay-success"
}

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "userWalletAddress": "TX85iLNzPsKYpreiwFmhuKiq1J2ZP7umfG",
    "saltHash": "0x6895cea1a486b4ee4353964321151eae18e74e42409c9ddfab05b654c65aa80b",
    "outPaymentNo": "202508191519455758358",
    "paymentUrl": "/payment?apiSign=Ktb%2BYciiHTb4si7SAYesIuPbzjnwGBwMcJAyZJjy2s0%3D"
  }
}

说明：

paymentUrl → 直接跳转到支付页面（推荐）
userWalletAddress → 用户可直接转账到该地址
outPaymentNo → Pay Protocol 收单订单号（保存以便查询）

注意

💡 在沙盒环境中，您可以领取测试代币用于模拟支付交易：

参考测试币领取教程。
根据当前选择的链（Tron nile 或者 Ethereum Sepolia），打开对应的官方水龙头网站。
输入您的测试钱包地址，领取测试代币（USDT、ETH、TRX 等）。
使用领取的测试代币，通过生成的 paymentUrl 进行支付，完成收单流程的测试。

提示：所有测试网代币仅可用于沙盒测试环境，不具备实际价值。

提示：测试网和主网是完全独立的区块链网络，切勿将主网资产发送到测试网地址，反之亦然。

5. 支付回调（paymentCallback）

Pay Protocol 会异步 POST 到 notifyUrl，商户收到后需：

校验 sign 签名是否合法
更新订单状态
返回 HTTP 200 确认

回调示例

paymentCallback 接口文档

{
  "orgId": 2313,
  "outTradeNo": "ORDER20250818001",
  "outPaymentNo": "202508191519455758358",
  "description": "A sample order",
  "paymentStatus": 0,
  "paymentType": 1,
  "isLegalTender": 0,
  "chainId": 136,
  "quoteCurrencySymbol": "USDT",
  "quoteAmount": "9.99",
  "expectedAmount": "999746",
  "settlementCurrencySymbol": "USDT",
  "settlementAmount": "9900000",
  "fromAddress": "TDPxB717Jowzj5qh7jAqBi88HTRYPmZ5tE",
  "userWalletAddress": "TX85iLNzPsKYpreiwFmhuKiq1J2ZP7umfG",
  "transferHash": "928b3243c230f490f336bbb83b7089a7fd3d01cc5fd051b1d72a6e227a4a5064",
  "blockTime": 1712122830,
  "createTime": "2025-08-19 15:19:45"
}

6. 查询订单（queryPaymentOrder）

GET /api/mer/payment/detail?outTradeNo=ORDER20250818001
Host: api-sandbox.payprotocol.network

queryPaymentOrder 接口文档参数说明：outTradeNo 必填，为商户订单号，用于查询订单状态。

✅ 至此，你就完成了 收单完整流程：

流程概览​

1. 概述​

2. 前提条件​

3. API 签名认证​

🔹 签名生成规则​

🔹 请求头示例（HTTPS）​

🔹 注意事项​

4. 创建收单订单（createPaymentOrder）​

请求体参数说明​

请求示例​

请求体示例​

响应示例​

5. 支付回调（paymentCallback）​

回调示例​

6. 查询订单（queryPaymentOrder）​