API文档

概述

本文档介绍区块链收款系统的API接口，提供完整的加密货币收款解决方案。系统支持USDT和USDC多币种收款，支持创建订单、查询订单状态、取消订单以及回调通知等功能。

API基础地址

http://127.0.0.1:5000

API版本

1.2.0

认证方式

API Key

数据格式

JSON

认证

所有API请求都需要在请求头中包含API密钥：

X-API-Key: YOUR_API_KEY
Content-Type: application/json

请妥善保管您的API密钥，不要在客户端代码中暴露。

API密钥权限

create_order: 创建订单
query_order: 查询订单
cancel_order: 取消订单
view_statistics: 查看统计信息
test_callback: 测试回调

API状态检查

检查API服务状态。

请求

GET /api/status

响应示例

{
  "status": "ok",
  "version": "1.0.0",
  "message": "API服务正常运行"
}

获取支持的资产列表 ⭐ 推荐

获取系统支持的所有收款资产信息，包括不同区块链上的USDT和USDC。

请求

GET /api/payment/assets

请求示例

curl

curl -X GET "http://127.0.0.1:5000/api/payment/assets" \
  -H "X-API-Key: YOUR_API_KEY"

响应示例

{
  "status": "success",
  "data": {
    "assets": [
      {
        "blockchain": "BSC",
        "blockchain_name": "BNB Smart Chain",
        "currency": "USDT",
        "symbol": "USDT",
        "name": "Tether USD",
        "decimals": 18,
        "contract": "0x55d398326f99059fF775485246999027B3197955",
        "chain_id": 56,
        "explorer": "https://bscscan.com"
      },
      {
        "blockchain": "BSC",
        "blockchain_name": "BNB Smart Chain",
        "currency": "USDC",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 18,
        "contract": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
        "chain_id": 56,
        "explorer": "https://bscscan.com"
      },
      {
        "blockchain": "ARBITRUM",
        "blockchain_name": "Arbitrum One",
        "currency": "USDT",
        "symbol": "USDT",
        "name": "Tether USD",
        "decimals": 6,
        "contract": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
        "chain_id": 42161,
        "explorer": "https://arbiscan.io"
      },
      {
        "blockchain": "ARBITRUM",
        "blockchain_name": "Arbitrum One",
        "currency": "USDC",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "contract": "0xFF970A61A04b1cA14834A43f5dE4533eBDDB5CC8",
        "chain_id": 42161,
        "explorer": "https://arbiscan.io"
      }
    ],
    "assets_by_blockchain": [
      {
        "blockchain": "BSC",
        "blockchain_name": "BNB Smart Chain",
        "chain_id": 56,
        "explorer": "https://bscscan.com",
        "tokens": [
          {
            "currency": "USDT",
            "symbol": "USDT",
            "name": "Tether USD",
            "decimals": 18,
            "contract": "0x55d398326f99059fF775485246999027B3197955",
            "payment_address": "0xfab37eB65c2A019AbE86946a93642BE28DE95DdE"
          },
          {
            "currency": "USDC",
            "symbol": "USDC",
            "name": "USD Coin",
            "decimals": 18,
            "contract": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
            "payment_address": "0xfab37eB65c2A019AbE86946a93642BE28DE95DdE"
          }
        ]
      },
      {
        "blockchain": "ARBITRUM",
        "blockchain_name": "Arbitrum One",
        "chain_id": 42161,
        "explorer": "https://arbiscan.io",
        "tokens": [
          {
            "currency": "USDT",
            "symbol": "USDT",
            "name": "Tether USD",
            "decimals": 6,
            "contract": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
            "payment_address": "0x53234C0575e21acdE578E4527d9b6c50669F6ED1"
          },
          {
            "currency": "USDC",
            "symbol": "USDC",
            "name": "USD Coin",
            "decimals": 6,
            "contract": "0xFF970A61A04b1cA14834A43f5dE4533eBDDB5CC8",
            "payment_address": "0x53234C0575e21acdE578E4527d9b6c50669F6ED1"
          }
        ]
      }
    ],
    "total_count": 4,
    "confirmations_required": 0
  }
}

获取支持的网络 (向后兼容)

提示：此API仅返回USDT信息。推荐使用 /api/payment/assets 获取所有支持的资产（包括USDT和USDC）。

获取系统支持的所有区块链网络信息，包括收款地址、USDT合约地址、小数位数等。

请求

GET /api/payment/networks

请求示例

curl

curl -X GET "http://127.0.0.1:5000/api/payment/networks" \
  -H "X-API-Key: YOUR_API_KEY"

响应示例

{
  "status": "success",
  "data": {
    "networks": [
      {
        "id": "bsc",
        "name": "BNB Smart Chain",
        "symbol": "BSC",
        "currency": "USDT",
        "contract_address": "0x55d398326f99059fF775485246999027B3197955",
        "decimals": 18,
        "chain_id": 56,
        "confirmations_required": 0,
        "is_active": true,
        "payment_address": "0xfab37eB65c2A019AbE86946a93642BE28DE95DdE",
        "explorer": "https://bscscan.com"
      },
      {
        "id": "arbitrum",
        "name": "Arbitrum One",
        "symbol": "ARBITRUM",
        "currency": "USDT",
        "contract_address": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
        "decimals": 6,
        "chain_id": 42161,
        "confirmations_required": 0,
        "is_active": true,
        "payment_address": "0x53234C0575e21acdE578E4527d9b6c50669F6ED1",
        "explorer": "https://arbiscan.io"
      }
    ],
    "default_network": "bsc"
  }
}

字段说明

字段	说明
id	网络ID（小写）
name	网络全名
symbol	网络符号
currency	支持的货币
contract_address	USDT合约地址
decimals	USDT小数位数（BSC: 18, Arbitrum: 6）⚠️
chain_id	链ID
confirmations_required	所需确认数
is_active	是否激活
payment_address	收款地址
explorer	区块链浏览器地址

创建订单

创建新的收款订单，支持多区块链网络和多币种（USDT、USDC）。

请求

POST /api/orders

请求参数

参数	类型	必填	说明
amount	number	是	收款金额，范围：0.000001-1000000
blockchain	string	否	区块链网络（BSC/ARBITRUM），默认BSC
currency	string	否	收款币种（USDT/USDC），默认USDT
callback_url	string	否	支付成功回调URL
callback_data	object	否	回调时附加的数据
external_order_id	string	否	外部订单ID

请求示例（BSC网络）

curl

curl -X POST "http://127.0.0.1:5000/api/orders" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "amount": 10.5,
    "blockchain": "BSC",
    "currency": "USDT",
    "callback_url": "https://your-site.com/callback",
    "external_order_id": "your_order_123"
  }'

请求示例（BSC网络 - USDC）

curl

curl -X POST "http://127.0.0.1:5000/api/orders" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "amount": 10.5,
    "blockchain": "BSC",
    "currency": "USDC",
    "callback_url": "https://your-site.com/callback",
    "external_order_id": "your_order_123"
  }'

请求示例（Arbitrum网络 - USDC）

curl

curl -X POST "http://127.0.0.1:5000/api/orders" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "amount": 10.5,
    "blockchain": "ARBITRUM",
    "currency": "USDC",
    "callback_url": "https://your-site.com/callback",
    "external_order_id": "your_order_123"
  }'

响应示例

{
  "status": "success",
  "data": {
    "order_id": "8a373e14-f5b4-45a5-8b41-ac59eac84bd2",
    "order_no": "ORD202509211127142C11C4B2",
    "amount": 10.5,
    "unique_amount": 10.500123,
    "currency": "USDT",
    "blockchain": "ARBITRUM",
    "status": "pending",
    "payment_address": "0x53234C0575e21acdE578E4527d9b6c50669F6ED1",
    "contract_address": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
    "explorer": "https://arbiscan.io",
    "expires_at": "2025-01-17T11:37:14.569370",
    "created_at": "2025-01-17T03:27:14.570368"
  }
}

重要提示

支持的币种：USDT、USDC
不同区块链网络使用不同的收款地址
不同代币的小数位数可能不同：
- BSC网络：USDT和USDC都是18位小数
- Arbitrum网络：USDT和USDC都是6位小数
请向对应网络的收款地址转账对应的代币

查询订单

根据订单号查询订单详情。

请求

GET /api/orders/{order_no}

请求示例

curl -X GET "http://127.0.0.1:5000/api/orders/ORD202509211127142C11C4B2" \
  -H "X-API-Key: YOUR_API_KEY"

响应示例

{
  "status": "success",
  "data": {
    "order_id": "8a373e14-f5b4-45a5-8b41-ac59eac84bd2",
    "order_no": "ORD202509211127142C11C4B2",
    "external_order_id": null,
    "amount": 10.5,
    "unique_amount": 11.419746,
    "currency": "USDT",
    "status": "pending",
    "callback_url": null,
    "callback_data": {},
    "expires_at": "2025-09-21T11:37:14.569370",
    "paid_at": null,
    "confirmed_at": null,
    "created_at": "2025-09-21T03:27:14.570368",
    "payment": null
  }
}

查询订单列表

查询用户的订单列表。

请求

GET /api/orders

查询参数

参数	类型	说明
page	number	页码，默认1
per_page	number	每页数量，默认20，最大100
status	string	订单状态过滤

请求示例

curl -X GET "http://127.0.0.1:5000/api/orders?page=1&per_page=10&status=pending" \
  -H "X-API-Key: YOUR_API_KEY"

取消订单

取消待支付状态的订单。

请求

POST /api/orders/{order_no}/cancel

请求示例

curl -X POST "http://127.0.0.1:5000/api/orders/ORD202509211127142C11C4B2/cancel" \
  -H "X-API-Key: YOUR_API_KEY"

响应示例

{
  "status": "success",
  "message": "订单已取消"
}

测试回调

测试回调URL是否可以正常接收通知。

请求

POST /api/callback/test

请求参数

参数	类型	必填	说明
url	string	是	要测试的回调URL
payload	object	否	测试数据

请求示例

curl -X POST "http://127.0.0.1:5000/api/callback/test" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "url": "https://httpbin.org/post",
    "payload": {"test": "data"}
  }'

获取统计信息

获取用户的订单和支付统计信息。

请求

GET /api/statistics

请求示例

curl -X GET "http://127.0.0.1:5000/api/statistics" \
  -H "X-API-Key: YOUR_API_KEY"

订单状态

状态	说明
`pending`	待支付
`paid`	已支付（检测到支付交易）
`confirmed`	已确认（交易已确认）
`expired`	已过期
`cancelled`	已取消

支付流程

1

获取支持的资产

调用 /api/payment/assets API，查看支持的币种和网络

2

创建订单

调用创建订单API，指定币种（USDT/USDC）和网络，获得订单号和唯一金额

3

用户支付

用户向系统提供的地址转账唯一金额的对应代币（USDT或USDC）

4

交易检测

系统自动检测到交易，订单状态变为paid

5

交易确认

达到确认数后，订单状态变为confirmed

6

回调通知

如果设置了回调URL，系统会发送支付成功通知

回调通知

当订单支付确认后，系统会向callback_url发送POST请求：

回调数据格式

{
  "order_no": "ORD202509211127142C11C4B2",
  "order_id": "8a373e14-f5b4-45a5-8b41-ac59eac84bd2",
  "external_order_id": "your_order_123",
  "amount": 10.5,
  "unique_amount": 11.419746,
  "currency": "USDT",
  "status": "confirmed",
  "tx_hash": "0x...",
  "confirmed_at": "2025-09-21T03:45:00.000000",
  "callback_data": {...}
}

错误响应

所有错误响应格式一致：

{
  "status": "error",
  "error": "error_code",
  "message": "错误描述"
}

常见错误码

错误码	HTTP状态码	说明
missing_api_key	401	缺少API密钥
invalid_api_key	401	API密钥无效或已过期
insufficient_permissions	403	权限不足
validation_error	400	请求参数验证失败
order_not_found	404	订单不存在
internal_error	500	服务器内部错误

技术支持

如需要技术支持或有疑问，请联系系统管理员。

更新记录

v1.2.0 (2025-01-18): 新增USDC支持，新增 /api/payment/assets 接口，删除已废弃的 /api/payment/address 接口

v1.1.0 (2025-09-22): 新增获取收款地址和网络信息API

v1.0.0 (2025-09-21): 初始版本发布

用户注册

暂不支持注册

目录

概述

API基础地址

API版本

认证方式

数据格式

认证

API密钥权限

API状态检查

请求

响应示例

获取支持的资产列表 ⭐ 推荐

请求

请求示例

响应示例

获取支持的网络 (向后兼容)

请求

请求示例

响应示例

字段说明

创建订单

请求

请求参数

请求示例（BSC网络）

请求示例（BSC网络 - USDC）

请求示例（Arbitrum网络 - USDC）

响应示例

重要提示

查询订单

请求

请求示例

响应示例

查询订单列表

请求

查询参数

请求示例

取消订单

请求

请求示例

响应示例

测试回调

请求

请求参数

请求示例

获取统计信息

请求

请求示例

订单状态

支付流程

获取支持的资产

创建订单

用户支付

交易检测

交易确认

回调通知

回调通知

回调数据格式

错误响应

常见错误码

技术支持

更新记录