跳到主要内容

收单快速入门

流程概览​

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签名，规则请看下面「签名生成规则」

🔹 签名生成规则​

参考官方文档：签名规则

  1. 拼接字符串
signString = timestamp + method + requestPath + body
  • timestamp：请求的 Unix 时间戳（秒）
  • method：HTTP 方法，例如 GET、POST
  • requestPath：接口路径，不含域名，例如 /api/mer/payment/createPaymentOrder
  • body：POST 请求的 JSON 字符串，GET 请求为空字符串
  1. 使用 HMAC-SHA256 算法
HMAC_SHA256(apiSecret, signString)

  1. 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: <生成的签名>

🔹 注意事项​

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

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

createPaymentOrder 接口文档

请求体参数说明​

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

请求示例​

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 收单订单号（保存以便查询）

5. 支付回调（paymentCallback）​

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

  1. 校验 sign 签名是否合法
  2. 更新订单状态
  3. 返回 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 必填，为商户订单号，用于查询订单状态。

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

最后于 更新