加密货币支付网关 API 对接文档

API 基础地址: https://pay.zdinko.cn 协议: HTTPS 请求方式: POST（application/x-www-form-urlencoded） 响应格式: JSON

1. 接入准备

接入前需由管理员在后台创建商户账号，商户将获得以下信息：

参数	说明
`username`	商户用户名，API 调用时的身份标识
`private_key`	商户密钥，用于签名计算（请妥善保管，切勿泄露）

商户还需提供以下信息给管理员配置：

参数	说明
`notify_url`	充值成功回调通知地址，需可公网访问

2. 支持的币种

`recharge_type` 值	网络	币种	地址格式
`TRC20-USDT`	TRON	USDT	`T` 开头，34 位
`ERC20-USDT`	Ethereum	USDT	`0x` 开头，42 位
`ERC20-USDC`	Ethereum	USDC	`0x` 开头，42 位
`ETH`	Ethereum	ETH	`0x` 开头，42 位
`BTC`	Bitcoin	BTC	`bc1q` 开头，SegWit 格式

3. 签名机制

所有 API 请求均需携带 sign 参数。

签名算法

将所有请求参数（除 sign 外）按参数名 ASCII 码升序排列
拼接为 key1=value1&key2=value2&...&key=商户密钥 格式的字符串
对拼接后的字符串进行 MD5 哈希运算，得到 32 位小写签名值

签名示例

请求参数：

username=merchant001
user_id=10086
recharge_type=TRC20-USDT

商户密钥：abc123

步骤 1 — 按参数名 ASCII 升序排列：recharge_type, user_id, username

步骤 2 — 拼接字符串：

recharge_type=TRC20-USDT&user_id=10086&username=merchant001&key=abc123

步骤 3 — MD5 哈希得到 sign 值，附加到请求参数中一起提交。

4. 通用说明

请求方式

所有接口均为 POST，参数通过表单（application/x-www-form-urlencoded）提交。

通用响应格式

{
    "code": 0,
    "msg": "成功",
    "data": {}
}

code: 0 表示成功，1 表示失败
msg: 提示信息
data: 返回数据

5. API 接口

5.1 获取充值地址

为用户分配专属充值地址。同一用户同一币种会返回固定地址。

请求地址: POST /api/index/getAdress

请求参数：

参数名	类型	必填	说明
`username`	string	✅	商户用户名
`sign`	string	✅	签名
`user_id`	string	✅	用户唯一标识
`recharge_type`	string	✅	充值方式，见支持的币种

成功响应：

{
    "code": 0,
    "msg": "成功",
    "data": {
        "address": "TFmMeaxK1LaXMcCvoFkTxaSsymLLguqBS8"
    }
}

注意事项：

同一 user_id + recharge_type 组合只会分配一个固定地址
如果系统地址池不足，会返回"暂无地址，请联系管理员"

5.2 创建充值订单

为用户创建充值监听订单，创建后系统会自动监听链上交易。

请求地址: POST /api/index/initOrder

请求参数：

参数名	类型	必填	说明
`username`	string	✅	商户用户名
`sign`	string	✅	签名
`user_id`	string	✅	用户唯一标识
`recharge_type`	string	✅	充值方式
`order_no`	string	✅	商户订单号（必须唯一）
`address`	string	✅	充值地址（必须是通过 getAdress 获取到的地址）
`amount`	string	❌	预期充值金额
`order_type`	int	❌	订单类型：`1`=普通订单（默认），`2`=一次性订单

成功响应：

{
    "code": 0,
    "msg": "成功",
    "data": {}
}

订单类型说明：

类型	说明
普通订单（`order_type=1`）	系统持续监听约 30 分钟（BTC 为 60 分钟），超时未到账则订单失败
一次性订单（`order_type=2`）	系统短时间内查询一次，未到账则直接标记失败

注意事项：

同一地址同时只能有一个活跃订单，创建新订单时旧的待确认订单会被自动标记为失败
address 必须是该商户通过 getAdress 分配给该 user_id 的地址

5.3 手动确认订单

将订单手动标记为成功到账。

请求地址: POST /api/index/notifuSuccessOrder

请求参数：

参数名	类型	必填	说明
`username`	string	✅	商户用户名
`sign`	string	✅	签名
`order_no`	string	✅	商户订单号
`amount`	float	✅	实际到账金额

成功响应：

{
    "code": 0,
    "msg": "成功",
    "data": {}
}

5.4 手动触发归集

将已成功的订单重新设置为需要归集状态。

请求地址: POST /api/index/shoudongguiji

请求参数：

参数名	类型	必填	说明
`username`	string	✅	商户用户名
`sign`	string	✅	签名
`order_no`	string	✅	商户订单号

成功响应：

{
    "code": 0,
    "msg": "成功",
    "data": {}
}

5.5 获取已分配地址列表

获取该商户名下所有已分配给用户的充值地址。

请求地址: POST /api/index/getsuccesslist

请求参数：

参数名	类型	必填	说明
`username`	string	✅	商户用户名
`sign`	string	✅	签名
`timestamp`	int	✅	当前时间戳（秒级），与服务器时间偏差不超过 ±5 秒

成功响应：

{
    "code": 0,
    "msg": "成功",
    "data": {
        "10086": "TFmMeaxK1LaXMcCvoFkTxaSsymLLguqBS8",
        "10087": "TCWY8m5XVfaGzeXrehKhmhtCsV1eNB4VCV"
    }
}

返回格式为 user_id: address 的键值对。

注意事项：

timestamp 精度要求高，请确保服务器时间与标准时间同步（建议使用 NTP）

6. 回调通知

6.1 触发时机

系统检测到充值到账（链上交易确认）后，会自动向商户配置的 notify_url 发送回调通知。

6.2 回调请求

请求方式: POST
Content-Type: application/json
超时时间: 10 秒

6.3 回调参数

参数名	类型	说明
`username`	string	商户用户名
`merchant_order_no`	string	商户订单号
`to_address`	string	充值地址
`add_time`	int	订单创建时间（Unix 时间戳）
`actual_amount`	float	实际到账金额
`now`	int	回调发送时间（Unix 时间戳）
`sign`	string	签名（签名算法同上）

6.4 回调示例

{
    "username": "merchant001",
    "merchant_order_no": "ORD20260318001",
    "to_address": "TFmMeaxK1LaXMcCvoFkTxaSsymLLguqBS8",
    "add_time": 1710742568,
    "actual_amount": 100.5,
    "now": 1710742668,
    "sign": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

6.5 响应要求

商户收到回调后，必须返回纯文本 success（小写），表示已成功处理。返回其他任何内容，系统会认为回调失败并进行重试。

6.6 重试机制

项目	说明
最大重试次数	8 次
重试间隔	30 秒
超过次数后	不再重试，回调状态标记为失败

6.7 回调签名验证

商户收到回调时必须验证签名，防止伪造回调：

取出回调参数中的 sign 值并移除
将剩余参数按参数名 ASCII 升序排列
拼接字符串并加上 &key=商户密钥
MD5 哈希后与回调中的 sign 比对，一致则有效

7. 订单状态说明

状态值	状态	说明
1	待确认	订单创建后等待链上确认
2	成功	充值到账已确认
3	失败	超时未到账或查询未果

8. 错误码说明

code	含义
0	请求成功
1	请求失败，详见 `msg` 字段

常见错误消息

msg	说明
`签名错误`	签名校验失败，检查密钥和签名算法
`用户ID不能为空`	`user_id` 参数缺失
`充值方式不支持`	`recharge_type` 不在支持列表中
`暂无地址，请联系管理员`	系统地址池中没有空闲地址
`订单号不能为空`	`order_no` 参数缺失
`订单重复`	该商户订单号已存在
`地址不符`	传入的地址与该用户分配的不匹配
`订单不存在`	未找到对应的订单记录
`时间对不上`	`timestamp` 与服务器时间偏差超过 5 秒

9. 对接流程

sequenceDiagram
    participant M as 商户服务端
    participant G as 支付网关
    participant B as 区块链

    Note over M,G: 一、获取充值地址
    M->>G: POST /api/index/getAdress
    G-->>M: 返回充值地址

    Note over M,G: 二、创建充值订单
    M->>G: POST /api/index/initOrder
    G-->>M: 返回创建结果

    Note over M,B: 三、用户在链上完成转账
    Note right of M: 商户展示充值地址给用户

    Note over G,B: 四、系统自动监听链上交易
    G->>B: 查询链上交易记录

    Note over M,G: 五、充值到账回调
    G->>M: POST notify_url（回调通知）
    M-->>G: 返回 "success"

    Note over G,B: 六、系统自动归集资金

对接步骤

步骤 1：获取充值地址

调用 POST /api/index/getAdress，传入 user_id 和 recharge_type，获取该用户的专属充值地址。

步骤 2：创建充值订单

调用 POST /api/index/initOrder，使用步骤 1 获取到的地址创建订单。每个 order_no 只能使用一次。

步骤 3：展示地址给用户

将充值地址展示给终端用户，引导用户在链上完成转账。

步骤 4：等待回调

在 notify_url 上接收回调通知：

验证签名
处理业务逻辑（如给用户加余额）
返回纯文本 success
建议实现幂等处理，防止重复加款

10. 常见问题

Q: 调用接口返回"签名错误"？ A: 请检查 username 是否正确，确认签名算法中参数排序和拼接格式无误。

Q: 订单创建成功但一直没有回调？ A: 1) 确认用户确实在链上完成了转账；2) 确认充值的币种与订单 recharge_type 匹配；3) 普通订单超过 30 分钟（BTC 为 60 分钟）会自动失败。

Q: 回调一直收不到怎么办？ A: 系统最多重试 8 次，间隔 30 秒。请确保 notify_url 可公网访问，且返回纯文本 success（不是 JSON、不是 HTML）。

Q: 地址池用完了怎么办？ A: 请联系管理员补充地址池。

Q: 不同用户会获取到相同地址吗？ A: 不会。系统通过 商户 + user_id + 币种 组合唯一绑定地址。

文档版本: v2.0 最后更新: 2026-03-18

加密货币支付网关 API 对接文档

目录

1. 接入准备

2. 支持的币种

3. 签名机制

签名算法

签名示例

4. 通用说明

请求方式

通用响应格式

5. API 接口

5.1 获取充值地址

5.2 创建充值订单

5.3 手动确认订单

5.4 手动触发归集

5.5 获取已分配地址列表

6. 回调通知

6.1 触发时机

6.2 回调请求

6.3 回调参数

6.4 回调示例

6.5 响应要求

6.6 重试机制

6.7 回调签名验证

7. 订单状态说明

8. 错误码说明

常见错误消息

9. 对接流程

对接步骤

10. 常见问题