跳到主要内容

充值快速入门

流程概览​

1. 概述​

充值（Recharge）：商户通过调用接口为用户生成一个专属充值地址。 生成地址分两步：先创建子合约地址（uuid），再调用查询接口获取真实充值地址。 用户将资金转入该地址后，Pay Protocol 系统会自动确认到账并回调商户，最后商户可通过查询接口获取充值明细。

流程：

👉 商户调用 createUserWallet → 获取 uuid → 调用 getUserWalletDetail → 获取充值地址 → 用户转账 → Pay Protocol 回调 rechargeCallback → 商户确认 → 调用 getRechargeDetail 查询充值详情。

2. 前提条件​

  • 开通商户账号：沙盒注册地址

  • 获取 API Key / Secret：获取 API Key / Secret

  • 确认使用的网络：

    • 沙盒环境：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
sign = Base64( HMAC_SHA256(apiSecret, signString) )

4. 创建子合约地址（createUserWallet）​

createUserWallet 接口文档

请求示例​

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

请求体示例​

{
  "uuid": "USER10001"
}

响应示例​

{
  "code": 200,
  "msg": "操作成功",
  "data": 7046
}

5. 查询子合约地址（getUserWalletDetail）​

getUserWalletDetail 接口文档

请求示例​

GET /api/mer/user/detail?uuid=USER10001
Host: api-sandbox.payprotocol.network

响应示例​

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "userId": 7046,
    "createTime": "2025-06-23 14:18:58",
    "userWallet": [
      {
        "walletId": 65953,
        "chainId": 136,
        "walletAddress": "THwGn3FcboiwbaJmLqXTkXapWryegchc3v"
      }
    ],
    "userType": 0,
    "uuid": "USER10001"
  }
}

此时 walletAddress 即为用户的专属充值地址。

6. 用户充值​

商户将生成的 walletAddress 提供给用户，用户将资金充值到该地址。

  • 用户可使用交易所钱包或去中心化钱包（如 TronLink、MetaMask）转账
  • 系统检测到账后会自动触发回调

7. 充值回调（rechargeCallback）​

当用户充值到账后，Pay Protocol 会自动调用商户配置的回调地址（POST 请求）。

rechargeCallback 接口文档

回调示例​

{
  "rechargeId": 1017,
  "chainId": 136,
  "currencyId": 107,
  "userId": 5923,
  "walletId": 62928,
  "walletAddress": "THwGn3FcboiwbaJmLqXTkXapWryegchc3v",
  "rechargeStatus": 0,
  "rechargeAmount": "10000000",
  "transferHash": "35e5e3dab41b43e9727a21b69f07a330af34c86673fb931e2f7a61ca871b7d27",
  "fromAddress": "TGrw6GPAPrtRR7ivdzJR8WyqdA3dy6XnqJ",
  "blockTime": "2025-06-24 07:06:30",
  "createTime": "2025-06-24 15:06:41",
  "uuid": "10"
}

商户需：

  1. 验签 sign
  2. 更新订单状态
  3. 返回 HTTP 200 表示成功

8. 配置充值回调地址​

商户需要在 Pay Protocol 管理后台 → 机构信息 页面中配置充值回调地址。 该地址需为公网可访问的 HTTPS 协议，否则将无法正常接收到回调通知。

操作步骤：

  1. 登录商户后台
  2. 进入顶部导航栏的 机构信息
  3. 点击 编辑
  4. 在“回调地址”处填写商户的回调 URL（必须是 HTTPS）

示意图：

配置充值回调地址

9. 查询充值订单（getRechargeDetail）​

getRechargeDetail 接口文档

请求示例​

GET /api/mer/recharge/detail?rechargeId=1017
Host: api-sandbox.payprotocol.network

响应示例​

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "rechargeId": 1017,
    "chainId": 136,
    "currencyId": 107,
    "userId": 5923,
    "walletId": 62928,
    "walletAddress": "THwGn3FcboiwbaJmLqXTkXapWryegchc3v",
    "rechargeStatus": 0,
    "rechargeAmount": "10000000",
    "transferHash": "35e5e3dab41b43e9727a21b69f07a330af34c86673fb931e2f7a61ca871b7d27",
    "fromAddress": "TGrw6GPAPrtRR7ivdzJR8WyqdA3dy6XnqJ",
    "blockTime": "2025-06-24 07:06:30",
    "createTime": "2025-06-24 15:06:41",
    "uuid": "10"
  }
}

✅ 至此，你就完成了 充值完整流程：

最后于 更新