REST API文档
通用响应结构
所有API接口返回统一的响应结构:
{
"code": "整数",
"msg": "字符串",
"data": "对象",
"systemTime": "长整数,系统时间戳"
}
响应字段
code: 响应状态码
1: 成功
0: 一般错误
msg: 响应消息
data: 响应数据对象
systemTime: 服务器时间戳(毫秒)
签名计算方法
所有需要签名的请求遵循以下规则:
将所有参数按键名字母顺序排序
将参数以"键=值"格式用"&"连接
在字符串末尾附加密钥
计算最终字符串的SHA-256哈希值
示例:
参数:
{
"amount": "100.00",
"nonce": "abc123",
"timestamp": "1677123456789",
"uid": "user123"
}
1. 排序并连接:
"amount=100.00&nonce=abc123×tamp=1677123456789&uid=user123"
2. 附加密钥:
"amount=100.00&nonce=abc123×tamp=1677123456789&uid=user123您的密钥"
3. 计算SHA-256:
sign = SHA-256(连接后的字符串)
部分sign计算的示例代码
# php version
public function sign($data, $app_secret) {
ksort($data);
$str = '';
// join $data with $key=$value&$key=$value
foreach ($data as $key => $value) {
$str .= $key . '=' . $value . '&';
}
//remove the last &
$str = substr($str, 0, -1);
$str .= $app_secret;
// sha256
return hash('sha256', $str);
}
1. 获取支付地址(如果不需要Payment UI,只是展示支付二维码)
接口: GET
/api/v1/address/{id}
描述: 获取指定订单的支付地址
参数:
id
: 订单ID (路径变量)
返回值:
成功: 链类型到钱包地址的映射
失败: "Not found" (未找到订单)
返回示例:
{ "code": 1, "msg": "success", "data": { "EVM": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F", "TRON": "TRWBqiqoFZysoAeyR1J35ibuyc8EvhUAoY" }, "systemTime": 1678234567890 }
2. 创建支付订单
接口: POST
/api/v1/order
访问限制: 每分钟60次
请求体: PaymentDTO
{ "oid": "商户订单号", "uid": "用户ID", "amount": "金额", "memo": "备注", "expiredAt": "过期时间", "timestamp": "时间戳", "nonce": "随机字符串", "sign": "签名", "mchId": "商户ID", "notifyUrl": "回调地址,接收后端支付结果通知", "redirectUrl": "跳转地址,用户支付完成后,前端页面跳回到哪里", "logo": "logo地址,会显示在支付页面上" }
验证:
时间戳必须在5分钟内
签名必须有效
nonce不能重复
返回值:
成功: 支付订单详情及钱包地址
失败: 错误信息及原因
返回示例:
{ "code": 1, "msg": "success", "data": { "id": "202403151234567890", "oid": "merchant_order_123", "uid": "user123", "amount": "100.00", "status": "PENDING_PAY", "expiredAt": 1678234567890, "addresses": { "EVM": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F", "TRON": "TRWBqiqoFZysoAeyR1J35ibuyc8EvhUAoY" } }, "systemTime": 1678234567890 }
3. 查询订单状态
接口: GET
/api/v1/order/{id}/status
描述: 获取支付订单当前状态
参数:
id
: 订单ID (路径变量)
返回值:
成功: 订单状态 (待支付、已支付、已过期等)
失败: "Order not found" (订单未找到)
返回示例:
{ "code": 1, "msg": "success", "data": "PAID", "systemTime": 1678234567890 }
4. 退款接口
接口: POST
/api/v1/refund
描述: 对已支付订单进行全额或部分退款
请求体: RefundDTO
{ "id": "string", "oid": "string", "amount": "decimal", "remark": "string", "timestamp": "long", "nonce": "string", "sign": "string" }
字段说明:
id
: 支付系统订单ID(如提供oid则可选)oid
: 商户订单号(如提供id则可选)amount
: 退款金额(必须小于等于原支付金额)remark
: 退款原因或备注timestamp
: 当前时间戳(毫秒)nonce
: 随机字符串,防止重放攻击sign
: 请求签名
验证要求:
id
和oid
必须提供其中之一退款金额必须为正数且不超过原支付金额
订单状态必须为已支付
签名必须有效
返回示例:
{ "code": 1, "msg": "success", "data": { "id": "202403151234567890", "oid": "merchant_order_123", "amount": "50.00", "status": "REFUNDED", "remark": "客户要求退款", "refundTime": 1678234567890 }, "systemTime": 1678234567890 }
错误返回示例:
{ "code": 0, "msg": "订单状态不是已支付状态", "data": null, "systemTime": 1678234567890 }
以下接口为提现功能相关接口。 注意, 考虑到保存热钱包的不安全性,Beaver Payment支付系统暂时不支持向用户发送资金。以下接口仅用于集成到用户现有的资金发放系统,用于记账使用。
提现资金请使用专业的现金发放系统。
5. 提现申请
接口: POST
/api/v1/withdraw/apply
描述: 提交提现申请
请求体: WithdrawApplication
{ "uid": "string", "amount": "decimal", "to": "string", "chainId": "integer", "chainType": "string", "token": "string", "notifyUrl": "string", "timestamp": "long", "nonce": "string", "sign": "string" }
字段说明:
uid
: 用户IDamount
: 提现金额to
: 目标钱包地址chainId
: 区块链网络IDchainType
: 链类型(EVM/TRON)token
: 代币合约地址notifyUrl
: 提现状态更新回调地址timestamp
: 当前时间戳(毫秒)nonce
: 随机字符串,防止重放攻击sign
: 请求签名
验证要求:
金额必须为正数
有效的区块链地址
用户余额必须足够
签名必须有效
返回示例:
{ "code": 1, "msg": "success", "data": { "id": 12345, "uid": "user123", "amount": "1000.00", "to": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F", "status": "PENDING", "chainType": "EVM", "chainId": 1, "createTime": 1678234567890 }, "systemTime": 1678234567890 }
6. 确认提现
接口: POST
/api/v1/withdraw/confirm
描述: 使用交易哈希确认待处理的提现
请求体: WithdrawConfirmDTO
{ "logId": "long", "txHash": "string", "blockNumber": "bigint", "timestamp": "long", "nonce": "string", "sign": "string" }
字段说明:
logId
: 提现记录IDtxHash
: 区块链上的交易哈希blockNumber
: 交易的区块号timestamp
: 当前时间戳(毫秒)nonce
: 随机字符串sign
: 请求签名
返回示例:
{ "code": 1, "msg": "success", "data": { "id": 12345, "status": "CONFIRMED", "txHash": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F...", "confirmTime": 1678234567890 }, "systemTime": 1678234567890 }
7. 拒绝提现
接口: POST
/api/v1/withdraw/reject
描述: 拒绝待处理的提现申请
请求体: WithdrawReject
{ "id": "long", "timestamp": "long", "nonce": "string", "sign": "string" }
字段说明:
id
: 提现记录IDtimestamp
: 当前时间戳(毫秒)nonce
: 随机字符串sign
: 请求签名
返回示例:
{ "code": 1, "msg": "success", "data": { "id": 12345, "status": "REJECTED", "rejectTime": 1678234567890 }, "systemTime": 1678234567890 }
Last updated