API 概览

Uapi 为全球商户提供高性能、非托管的加密货币支付接入方案。我们的 API 旨在让复杂的区块链交互变得像传统支付一样简单。

Base URL

https://uapi.io/api/v1

1 鉴权认证

所有请求必须在 HTTP Header 中携带您的 API Key。密钥分为 Test Key (测试环境) 和 Live Key (生产环境)。

HTTP Header

X-API-KEY: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

域名安全校验

为了防止 API 滥用，您的请求域名必须在商户后台 > 网站管理中进行绑定。如果是后端服务器直连（无 Origin 头），请在请求体中显式包含 domain 参数。未绑定域名的请求将被拒绝。

对接流程

1

创建订单

商户调用接口，传入金额和网络，获取支付链接 (payment_url)。

2

用户支付

重定向用户至收银台，用户通过扫码或转账完成支付。

3

确认与回调

链上确认后，系统自动发送 Webhook 通知并更新订单状态。

免代码集成 (No-Code)

如果您不想编写代码，可以使用我们的“收款链接”功能：

在商户后台一键生成专属收款页面。
支持设置固定金额或允许用户自定义输入金额。
直接分享链接给客户，通过社交媒体、Telegram 或 WhatsApp 进行收款。
支付成功后，您依然可以在后台查看到账明细。

创建订单

POST

创建一个全新的支付订单并获取收银台链接。

Endpoint

/order/create.php

参数名	类型	必填	描述
amount	Float	YES	订单金额 (USDT)
chain	String	YES	网络: trc20, erc20, bsc, solana, polygon, etc.
merchant_order_id	String	YES	您的系统订单号 (唯一)
notify_url	String	NO	异步回调地址，支付成功后系统将向该地址发送 POST 请求
domain	String	YES*	服务端直连调用时必填（如 curl / 后端 SDK）。值为您已绑定的网站域名，例如 yoursite.com。若请求自带 Origin/Referer，则可不传。

{
  "status": "success",
  "data": {
    "order_no": "PAY2024...",      // 系统生成的支付订单号    "amount": "100.001234",        // 包含防冲突随机数后的支付金额    "payment_url": "https://...",  // 收银台链接    "expire_in": 600               // 订单有效期 (秒)  }
}

查询状态

GET

轮询或按需查询订单的最新支付状态。

Endpoint

/order/status.php?order_no=PAY...

// 已支付响应{
  "status": "paid",
  "tx_hash": "0x123abc...",  // 链上交易哈希  "amount_paid": "100.001234"
}

回调通知 (Webhook)

当链上交易确认后，系统会立即向您的 notify_url 发送 POST 回调。

若创建订单时未传 notify_url，系统会自动使用商户后台「API 设置」中的默认 Webhook 地址。

签名验证支持

// 推荐：HMAC-SHA256
X-UAPI-Signature: hmac_sha256(order_no + amount + merchant_order_id + timestamp, api_key)

// 传统：MD5 (兼容旧系统)
sign: md5(order_no + amount + merchant_order_id + api_key)

响应要求：接收端必须返回 HTTP 200 状态码，或者包含字符串 success，否则系统将进行最多 3 次重试（约 1 秒、2 秒回退）。

订单状态机

状态	描述
pending	已创建，等待用户按指定金额转账。
paid	链上到账金额和地址匹配，已记录交易哈希并回调。
expired	超过有效期 (通常为 10-20 分钟) 未支付，系统自动标记过期。

限流与幂等

API 限流：免费套餐限制为每日 100 次调用。专业版与企业版提供更高并发配额。
幂等性控制：请确保 merchant_order_id 在您系统内唯一。重复提交相同的商户订单号将返回已存在的订单信息，而不会创建新订单。
并发处理：建议商户系统在接收 Webhook 时使用分布式锁，防止并发回调导致的数据重复处理。

支持网络与精度

网络 (Slug)	精度	代币	备注
trc20	6	USDT	Tron 网络，到账极速且费用极低。
bsc	18	USDT/BNB	币安智能链。
erc20	18	USDT/ETH	以太坊主网 (Gas 较高)。
polygon	6/18	USDT/MATIC	Layer 2 扩容网络。
solana	6/9	USDT/USDC	高性能非 EVM 链。
arbitrum	18	USDT	以太坊 L2 卷叠网络。

工具与版本

TLS 要求

出于安全考虑，我们的 API 强制要求使用 TLS 1.2 或更高版本。旧版本的 SSL/TLS 将无法建立连接。

数据编码

所有请求和响应体必须使用 UTF-8 编码。请确保您的 Content-Type 设置为 application/json。

开发者 FAQ

订单有效期可以自定义吗？

默认有效期为 10-20 分钟。如果需要更长的有效期，请联系技术支持或在商户后台的 API 设置中进行配置。过长的有效期可能会增加订单金额冲突的概率。

为什么实际支付金额会有随机小数？

这是为了在非托管钱包中实现精确的订单匹配。由于区块链上可能存在多笔相同整数金额的转账，通过增加微小的随机数（例如 100.001234），我们可以确保每笔订单在您的钱包地址下是全网唯一的。

多语言接入示例

PHP

$apiKey = 'sk_live_xxx';
$data = [
    'amount' => 100.0,
    'chain' => 'trc20',
    'merchant_order_id' => 'MY_ORDER_001',
    'notify_url' => 'https://yoursite.com/callback',
    'domain' => 'yoursite.com'
];

$ch = curl_init('https://www.uapi.io/api/v1/order/create.php');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-KEY: ' . $apiKey,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$result = json_decode($response, true);
echo $result['data']['payment_url'] ?? 'Create order failed';

Node.js (Axios)

const axios = require('axios');

const createOrder = async () => {
  const { data } = await axios.post('https://www.uapi.io/api/v1/order/create.php', {
    amount: 100.0,
    chain: 'trc20',
    merchant_order_id: 'MY_ORDER_001',
    notify_url: 'https://yoursite.com/callback',
    domain: 'yoursite.com'
  }, {
    headers: {
      'X-API-KEY': 'sk_live_xxx',
      'Content-Type': 'application/json'
    }
  });
  console.log(data.data.payment_url);
};