支付系统API集成文档

概述

本支付系统提供了一套完整的加密货币支付解决方案，允许外部系统发起支付请求并跟踪支付状态。系统支持以下加密货币：

TRX (波场原生代币)
USDT (泰达币-TRC20)

                    重要提示：本系统连接至TRX波场主网，所有交易涉及真实资产！
                

API基础信息

项目	说明
基础URL	https://uick.w20262026.com
协议	HTTPS
数据格式	JSON
字符编码	UTF-8
跨域策略	允许所有来源 (CORS: Access-Control-Allow-Origin: *)

可用API端点

功能	端点	方法	说明
发起支付请求	`/initiate_payment.php`	POST	创建待处理的支付订单
查询支付状态	`/check_payment_status.php`	GET/POST	检查订单支付情况

发起支付请求

创建一个新的支付订单，系统将返回订单ID和支付信息。

请求地址：POST /initiate_payment.php

请求头

Content-Type: application/json

请求参数

参数名	类型	必需	说明
to_address	string	否	接收资金的TRX地址（已弃用，系统将自动使用统一的监控地址）
amount	number	是	支付金额，必须大于0
currency	string	是	货币类型，支持: TRX, USDT
order_id	string	否	订单ID，如果不提供将自动生成
api_key	string	否	商户API密钥，用于标识请求来源并启用回调通知
description	string	否	订单描述信息

请求示例

{
  "amount": 0.1,
  "currency": "TRX",
  "api_key": "your_api_key_here",
  "order_id": "123456789",
  "description": "商品购买"
}

成功响应

{
  "status": "success",
  "message": "支付请求已创建",
  "data": {
    "order_id": "123456789",
    "payment_token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "to_address": "TAbcdef123456789abcdef123456789abcdef12",
    "amount": 0.1,
    "currency": "TRX"
    "description": "商品购买",
    "status": "pending",
    "created_at": "2023-12-01 10:30:00"
  }
}

失败响应

{
  "error": "错误信息"
}

可能的错误情况

400 Bad Request: 缺少必需字段、无效的TRX地址格式、金额小于等于0、不支持的货币类型
409 Conflict: 订单ID已存在
500 Internal Server Error: 数据库连接失败

查询支付状态

根据订单ID或支付令牌查询订单的支付状态。

请求地址：GET /check_payment_status.php?order_id=ORDER_ID
或
请求地址：POST /check_payment_status.php

请求参数

参数名	类型	必需	说明
order_id	string	是*	订单ID (order_id 和 payment_token 至少提供一个)
payment_token	string	是*	支付令牌 (order_id 和 payment_token 至少提供一个)

GET请求示例

GET /check_payment_status.php?order_id=123456789

POST请求示例

{
  "order_id": "123456789"
}

成功响应

{
  "status": "success",
  "data": {
    "order_id": "123456789",
    "transaction_hash": "0xabcdef123456789...",
    "from_address": "T123456789abcdef123456789abcdef123456789",,
    "to_address": "TAbcdef123456789abcdef123456789abcdef12",
    "amount": 0.1,
    "currency": "TRX"
    "status": "paid",
    "description": "商品购买",
    "created_at": "2023-12-01 10:30:00",
    "updated_at": "2023-12-01 10:35:00"
  }
}

订单状态说明

状态	说明
pending	待支付 - 用户尚未完成支付
paid	已支付 - 已收到支付款项，但未确认
confirmed	已确认 - 支付已确认
failed	支付失败 - 支付超时或未完成

失败响应

{
  "error": "错误信息"
}

Webhook回调

当支付状态发生变化时，系统会向预先配置的URL发送POST请求通知。

回调数据格式

{  
  "event": "payment_status_changed",  
  "order_id": "123456789",  
  "status": "paid",  
  "amount": 0.1,  
  "currency": "TRX",  
  "transaction_hash": "0xabcdef123456789...",  
  "timestamp": "2023-12-01 10:35:00",  
  "signature": "签名值"  
}

签名算法说明

为了确保回调数据的安全性，系统会对每个回调请求生成签名。商户可以通过以下算法验证签名的有效性：

将 order_id、status 和当天日期（格式为YYYYMMDD）按顺序拼接成一个字符串
使用 SHA256 算法计算该字符串的哈希值
将计算出的哈希值与回调数据中的 signature 字段进行比较

示例：

如果 order_id 是 "ORD-123456"，status 是 "paid"，当前日期是 2023年12月1日，则拼接字符串为："ORD-123456paid20231201"

使用 SHA256 计算该字符串的哈希值，即为签名值。

回调验证

系统使用签名验证确保回调的安全性，商户应在回调接口中实现签名验证逻辑以确保数据的完整性。

错误码

HTTP状态码	错误类型	说明
400	Bad Request	请求参数错误
404	Not Found	订单不存在
405	Method Not Allowed	请求方法错误
409	Conflict	资源冲突（如订单ID重复）
500	Internal Server Error	服务器内部错误

集成示例

JavaScript示例

// 发起支付请求
async function createPayment(orderData) {
  try {
    const response = await fetch('https://uick.w20262026.com/initiate_payment.php', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(orderData)
    });

    const result = await response.json();
    
    if (result.status === 'success') {
      console.log('支付订单创建成功:', result.data);
      // 保存订单ID用于后续查询
      localStorage.setItem('currentOrderId', result.data.order_id);
      return result.data;
    } else {
      console.error('支付订单创建失败:', result.error);
      return null;
    }
  } catch (error) {
    console.error('请求失败:', error);
    return null;
  }
}

// 查询支付状态
async function checkPaymentStatus(orderId) {
  try {
    const response = await fetch(`https://uick.w20262026.com/check_payment_status.php?order_id=${orderId}`, {
      method: 'GET',
    });

    const result = await response.json();
    
    if (result.status === 'success') {
      console.log('订单状态:', result.data.status);
      return result.data;
    } else {
      console.error('查询失败:', result.error);
      return null;
    }
  } catch (error) {
    console.error('请求失败:', error);
    return null;
  }
}

// 使用示例
const orderData = {
  amount: 0.1,
  currency: "TRX",
  description: "商品购买"
};

createPayment(orderData).then(paymentInfo => {
  if (paymentInfo) {
    console.log('支付信息:', paymentInfo);
    // 开始轮询支付状态
    pollPaymentStatus(paymentInfo.order_id);
  }
});

function pollPaymentStatus(orderId) {
  const interval = setInterval(async () => {
    const status = await checkPaymentStatus(orderId);
    if (status && (status.status === 'paid' || status.status === 'confirmed')) {
      console.log('支付成功!');
      clearInterval(interval);
      // 处理支付成功的逻辑
      handlePaymentSuccess(status);
    } else if (status && status.status === 'failed') {
      console.log('支付失败!');
      clearInterval(interval);
      // 处理支付失败的逻辑
      handlePaymentFailure();
    }
  }, 5000); // 每5秒查询一次
}

function handlePaymentSuccess(paymentInfo) {
  alert('支付成功!');
  // 处理支付成功后的业务逻辑
}

function handlePaymentFailure() {
  alert('支付失败，请重试!');
  // 处理支付失败的业务逻辑
}

PHP示例

<?php
/**
 * PHP集成示例
 */

class PaymentClient {
    private $baseUrl;
    
    public function __construct($baseUrl) {
        $this->baseUrl = rtrim($baseUrl, '/');
    }
    
    /**
     * 发起支付请求
     */
    public function initiatePayment($amount, $currency, $orderId = null, $description = '') {
        $data = [
            'amount' => $amount,
            'currency' => $currency,
            'description' => $description
        ];
        
        if ($orderId) {
            $data['order_id'] = $orderId;
        }
        
        $options = [
            'http' => [
                'header' => "Content-type: application/json\r\n",
                'method' => 'POST',
                'content' => json_encode($data)
            ]
        ];
        
        $context = stream_context_create($options);
        $result = file_get_contents($this->baseUrl . '/initiate_payment.php', false, $context);
        
        return json_decode($result, true);
    }
    
    /**
     * 查询支付状态
     */
    public function checkPaymentStatus($orderId) {
        $url = $this->baseUrl . '/check_payment_status.php?order_id=' . urlencode($orderId);
        $result = file_get_contents($url);
        
        return json_decode($result, true);
    }
}

// 使用示例
$client = new PaymentClient('https://uick.w20262026.com');

// 创建支付订单
$paymentResult = $client->initiatePayment(
    0.1, // 金额
    'TRX', // 货币类型
    'ORD-' . time(), // 订单ID
    '商品购买' // 描述
);

if (isset($paymentResult['status']) && $paymentResult['status'] === 'success') {
    $orderId = $paymentResult['data']['order_id'];
    echo "支付订单创建成功，订单ID: {$orderId}\n";
    
    // 轮询支付状态
    $attempts = 0;
    $maxAttempts = 24; // 最多等待2分钟 (24 * 5秒)
    
    while ($attempts < $maxAttempts) {
        sleep(5); // 等待5秒
        
        $statusResult = $client->checkPaymentStatus($orderId);
        
        if (isset($statusResult['data']['status'])) {
            $status = $statusResult['data']['status'];
            echo "当前订单状态: {$status}\n";
            
            if ($status === 'paid' || $status === 'confirmed') {
                echo "支付成功!\n";
                // 处理支付成功的业务逻辑
                break;
            } elseif ($status === 'failed') {
                echo "支付失败!\n";
                // 处理支付失败的业务逻辑
                break;
            }
        }
        
        $attempts++;
    }
    
    if ($attempts >= $maxAttempts) {
        echo "等待超时，支付状态未知\n";
    }
} else {
    echo "创建支付订单失败: " . ($paymentResult['error'] ?? '未知错误') . "\n";
}
?>

集成注意事项

安全性

保护好支付令牌，可用于查询订单状态
验证返回的交易哈希以确认支付的真实性
在生产环境中使用HTTPS保护数据传输

轮询策略

建议每5-10秒查询一次支付状态，避免过于频繁
设置合理的超时时间，防止无限轮询

错误处理

妥善处理各种错误情况
对于临时性错误，可以考虑重试机制

测试建议

先使用小额测试交易验证系统功能
确认一切正常后再用于正式交易

注意：由于系统连接到TRX波场主网，所有交易都涉及真实资产，请务必在测试阶段充分验证系统功能。

常见问题

Q: 如何知道支付是否成功？

A: 通过查询支付状态API，如果状态变为"paid"或"confirmed"，则支付成功。

Q: 订单状态有哪些？

A: pending(待支付), paid(已支付), confirmed(已确认), failed(支付失败)。

Q: 为什么订单状态没有更新？

A: 检查区块链监听器是否正在运行，以及Webhook URL是否可访问。

Q: 如何测试支付功能？

A: 可以先在测试网络上进行测试，或者使用小额真实资金进行验证。

Q: 支持哪些加密货币？

A: 目前支持TRX和USDT两种加密货币。

Q: 订单ID是如何生成的？

A: 如果不提供订单ID，系统会自动生成一个简短的纯数字订单号，使用时间戳的后6位+3位随机数。

支付系统API集成文档

目录

概述

API基础信息

可用API端点

发起支付请求

请求头

请求参数

请求示例

成功响应

失败响应

可能的错误情况

查询支付状态

请求参数

GET请求示例

POST请求示例

成功响应

订单状态说明

失败响应

Webhook回调

回调数据格式

签名算法说明

回调验证

错误码

集成示例

JavaScript示例

PHP示例

集成注意事项

安全性

轮询策略

错误处理

测试建议

常见问题

Q: 如何知道支付是否成功？

Q: 订单状态有哪些？

Q: 为什么订单状态没有更新？

Q: 如何测试支付功能？

Q: 支持哪些加密货币？

Q: 订单ID是如何生成的？