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&timestamp=1677123456789&uid=user123"

2. 附加密钥：
"amount=100.00&nonce=abc123&timestamp=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);
}

Map<String, Object> params = new TreeMap<>();
params.addAll(allParameters);
String base = MapUtil.join(params, "&", "=", true);
String _sign = DigestUtil.sha256Hex(base + System.getenv("PAYMENT_NOTIFY_SECRET"));

package main

import (
	"crypto/sha256"
	"encoding/hex"
	"sort"
	"strings"
)

func sign(data map[string]string, appSecret string) string {
	keys := make([]string, 0, len(data))
	for key := range data {
		keys = append(keys, key)
	}
	sort.Strings(keys)

	var sb strings.Builder
	for _, key := range keys {
		sb.WriteString(key)
		sb.WriteString("=")
		sb.WriteString(data[key])
		sb.WriteString("&")
	}

	str := sb.String()
	if len(str) > 0 {
		str = str[:len(str)-1]
	}

	str += appSecret

	hash := sha256.Sum256([]byte(str))
	return hex.EncodeToString(hash[:])
}

import hashlib

def sign(data, app_secret):
    sorted_keys = sorted(data.keys())

    str_to_sign = "&".join(f"{key}={data[key]}" for key in sorted_keys)
    str_to_sign += app_secret
    
    sha256_hash = hashlib.sha256(str_to_sign.encode('utf-8')).hexdigest()
    
    return sha256_hash

const crypto = require('crypto');

function sign(data, appSecret) {
    const sortedKeys = Object.keys(data).sort();
    let str = '';

    sortedKeys.forEach((key) => {
        str += `${key}=${data[key]}&`;
    });


    str = str.slice(0, -1);

    str += appSecret;

    return crypto.createHash('sha256').update(str).digest('hex');
}

// example
const data = {
    b: 'value2',
    a: 'value1',
    c: 'value3',
};
const appSecret = 'my_app_secret';

console.log(sign(data, appSecret));

import * as crypto from 'crypto';

function sign(data: Record<string, string | number>, appSecret: string): string {
    const sortedKeys = Object.keys(data).sort();
    let str = '';

    for (const key of sortedKeys) {
        str += `${key}=${data[key]}&`;
    }

    str = str.slice(0, -1);
    str += appSecret;
    return crypto.createHash('sha256').update(str).digest('hex');
}

// 示例用法
const data: Record<string, string | number> = {
    b: 'value2',
    a: 'value1',
    c: 123, // 支持 string 或 number 类型
};

const appSecret = 'my_app_secret';

console.log(sign(data, appSecret));

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: 用户ID
- amount: 提现金额
- to: 目标钱包地址
- chainId: 区块链网络ID
- chainType: 链类型（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: 提现记录ID
- txHash: 区块链上的交易哈希
- 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: 提现记录ID
- timestamp: 当前时间戳（毫秒）
- nonce: 随机字符串
- sign: 请求签名

返回示例:

{
  "code": 1,
  "msg": "success",
  "data": {
    "id": 12345,
    "status": "REJECTED",
    "rejectTime": 1678234567890
  },
  "systemTime": 1678234567890
}

Previous使用API创建第一个支付订单 Next接收支付结果通知 - notifyUrl

Last updated 4 months ago