XcoinPay API 文档

欢迎使用 XcoinPay 支付接口，本文档描述了接入加密货币支付的完整流程。

接入流程

1. 在商户后台注册账号，获取 API Key 和 API Secret

2. 调用「创建订单」接口，获取 pay_url

3. 将用户重定向到 pay_url 完成支付

4. 收到系统的支付回调通知，完成业务处理

API 认证

所有 API 请求需要在 Header 中携带 API Key：

X-Api-Key: xcp_your_api_key_here

或通过请求体传入：

{ "api_key": "xcp_your_api_key_here" }

签名算法 (可选但推荐)

为确保请求安全，建议对请求参数进行签名验证：

1. 将所有非空参数按参数名 ASCII 升序排列，格式为 key=value&key2=value2

2. 使用 HMAC-SHA256 对上述字符串进行签名，密钥为 API Secret

3. 将签名结果（十六进制小写）作为 sign 参数传入

// Node.js 签名示例
const crypto = require('crypto');
function sign(params, secret) {
  const str = Object.keys(params)
    .filter(k => params[k] !== undefined && params[k] !== '')
    .sort()
    .map(k => `${k}=${params[k]}`)
    .join('&');
  return crypto.createHmac('sha256', secret).update(str).digest('hex');
}

创建支付订单

{
  "code": 0,
  "message": "订单创建成功",
  "data": {
    "order_id": "XCPA1B2C3D4E5",
    "merchant_order_id": "YOUR_ORDER_123",
    "currency": "USDT-TRC20",
    "amount": 100,
    "pay_address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "pending",
    "expire_time": "2024-01-01T12:30:00.000Z",
    "pay_url": "https://xcoinpay.net/pay/XCPA1B2C3D4E5",
    "qr_url": "https://xcoinpay.net/api/orders/XCPA1B2C3D4E5/qrcode"
  }
}

查询订单状态

{
  "code": 0,
  "data": {
    "order_id": "XCPA1B2C3D4E5",
    "currency": "USDT-TRC20",
    "amount": 100,
    "actual_amount": 100,
    "pay_address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "tx_hash": "abc123...",
    "status": "confirmed",  // pending | paid | confirmed | expired | failed
    "paid_at": "2024-01-01T12:10:00.000Z",
    "confirmed_at": "2024-01-01T12:11:00.000Z"
  }
}

支付成功回调

当订单状态变更为 confirmed，系统将向您配置的回调地址发送 POST 请求。

// 回调处理示例 (Node.js)
app.post('/xcoinpay/callback', (req, res) => {
  const { order_id, status, sign, ...params } = req.body;
  
  // 1. 验证签名
  const expectedSign = computeSign(params, YOUR_API_SECRET);
  if (sign !== expectedSign) return res.status(400).json({error: 'invalid sign'});
  
  // 2. 验证订单状态
  if (status !== 'confirmed') return res.json({status: 'ok'});
  
  // 3. 处理业务逻辑
  await db.updateOrder(order_id, 'paid');
  
  // 4. 必须返回 success
  res.json({status: 'success'});
});

PHP 接入示例

<?php
define('API_KEY', 'xcp_your_api_key');
define('API_SECRET', 'your_api_secret');
define('API_URL', 'https://xcoinpay.net/api');

function createOrder($merchantOrderId, $amount, $currency = 'USDT-TRC20') {
    $params = [
        'merchant_order_id' => $merchantOrderId,
        'currency' => $currency,
        'amount' => $amount,
        'return_url' => 'https://yoursite.com/success',
        'callback_url' => 'https://yoursite.com/xcoinpay/callback',
        'timestamp' => time()
    ];
    
    // Sign
    ksort($params);
    $signStr = http_build_query($params);
    $params['sign'] = hash_hmac('sha256', $signStr, API_SECRET);
    
    $ch = curl_init(API_URL . '/orders/create');
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'X-Api-Key: ' . API_KEY
    ]);
    $result = curl_exec($ch);
    curl_close($ch);
    return json_decode($result, true);
}

$order = createOrder('ORDER_001', 100, 'USDT-TRC20');
if ($order['code'] === 0) {
    header('Location: ' . $order['data']['pay_url']);
}
?>

Node.js 接入示例

const crypto = require('crypto');

const API_KEY = 'xcp_your_api_key';
const API_SECRET = 'your_api_secret';
const API_URL = 'https://xcoinpay.net/api';

function sign(params, secret) {
  const str = Object.keys(params)
    .filter(k => params[k] !== '')
    .sort()
    .map(k => `${k}=${params[k]}`)
    .join('&');
  return crypto.createHmac('sha256', secret).update(str).digest('hex');
}

async function createOrder(merchantOrderId, amount, currency = 'USDT-TRC20') {
  const params = {
    merchant_order_id: merchantOrderId,
    currency, amount,
    return_url: 'https://yoursite.com/success',
    callback_url: 'https://yoursite.com/xcoinpay/callback',
    timestamp: Math.floor(Date.now() / 1000)
  };
  params.sign = sign(params, API_SECRET);
  
  const resp = await fetch(`${API_URL}/orders/create`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'X-Api-Key': API_KEY },
    body: JSON.stringify(params)
  });
  const result = await resp.json();
  
  if (result.code === 0) {
    // 重定向到支付页
    return result.data.pay_url;
  }
  throw new Error(result.message);
}

Python 接入示例

import hmac, hashlib, requests, time

API_KEY = 'xcp_your_api_key'
API_SECRET = 'your_api_secret'
API_URL = 'https://xcoinpay.net/api'

def sign(params, secret):
    filtered = {k: v for k, v in params.items() if v != ''}
    sorted_str = '&'.join(f'{k}={v}' for k, v in sorted(filtered.items()))
    return hmac.new(secret.encode(), sorted_str.encode(), hashlib.sha256).hexdigest()

def create_order(merchant_order_id, amount, currency='USDT-TRC20'):
    params = {
        'merchant_order_id': merchant_order_id,
        'currency': currency,
        'amount': amount,
        'return_url': 'https://yoursite.com/success',
        'callback_url': 'https://yoursite.com/xcoinpay/callback',
        'timestamp': int(time.time())
    }
    params['sign'] = sign(params, API_SECRET)
    
    resp = requests.post(
        f'{API_URL}/orders/create',
        json=params,
        headers={'X-Api-Key': API_KEY}
    )
    result = resp.json()
    
    if result['code'] == 0:
        return result['data']['pay_url']
    raise Exception(result['message'])

XcoinPay API Documentation · 如有问题请联系 [email protected]