支付 API

支付 API 是 Payve 平台的核心功能，提供创建支付订单、查询支付状态、取消订单等完整的支付生命周期管理功能。

概述

基础 URL

https://api.payve.io/api/v1

认证方式

Bearer Token (JWT)

请求格式

application/json

响应格式

application/json

创建支付订单

创建一个新的加密货币支付订单。系统会自动生成收款地址并计算实际应付金额。

POST/payments

请求头

Authorization: Bearer <your-jwt-token>
Content-Type: application/json
Idempotency-Key: <unique-key> (可选)

请求参数

参数	类型	必填	说明
`amount`	string	✅	支付金额，支持小数点后 8 位，需满足最小金额要求
`currency`	string	✅	币种代码（BTC, ETH, USDT, USDC, BNB, SOL, TRX, POL）
`network`	string	✅	指定区块链网络（BITCOIN, ETHEREUM, TRON, BSC, POLYGON, SOLANA）
`merchantOrderId`	string	✅	商户自定义订单号，用于对账，必须唯一
`productName`	string	❌	产品名称，用于支付页面显示
`callbackUrl`	string	❌	支付成功后的回调 URL
`metadata`	object	❌	自定义元数据，最多 10 个键值对

最小金额限制

不同币种和网络有强制的最小金额限制。低于最小金额的交易请求将被拒绝并返回 AMOUNT_TOO_SMALL 错误：

原生代币最小金额

币种	最小金额
BTC	0.0001 BTC
ETH	0.005 ETH
BNB	0.01 BNB
SOL	0.01 SOL
TRX	2 TRX
POL	10 POL

稳定币最小金额

币种	网络	最小金额
USDT	Ethereum	10 USDT
USDT	TRON	5 USDT
USDT	BNB Chain	2 USDT
USDT	Polygon	2 USDT
USDT	Solana	1 USDT
USDC	Ethereum	10 USDC
USDC	BNB Chain	2 USDC
USDC	Polygon	2 USDC
USDC	Solana	1 USDC

请求示例

{
  "amount": "100.00",
  "currency": "USDT",
  "network": "TRON",
  "merchantOrderId": "ORDER_2024011501",
  "description": "购买商品 #12345",
  "callbackUrl": "https://merchant.com/webhook/payment",
  "redirectUrl": "https://merchant.com/order/success",
  "metadata": {
    "userId": "user_123",
    "productId": "prod_456"
  },
  "expiresIn": 3600
}

JSON

代码已折叠

共 14 行

响应参数

参数	类型	说明
`orderId`	string	Payve 订单 ID
`merchantOrderId`	string	商户订单号
`status`	string	订单状态（PENDING, PAID, EXPIRED, FAILED）
`amount`	string	应付金额
`currency`	string	币种
`network`	string	区块链网络
`address`	string	收款地址
`qrCode`	string	支付二维码图片 URL
`paymentUrl`	string	支付页面 URL
`expiresAt`	string	过期时间（ISO 8601）
`createdAt`	string	创建时间（ISO 8601）
`fee`	object	手续费信息

响应示例

{
  "orderId": "pay_xGh8Kl9mNpQr",
  "merchantOrderId": "ORDER_2024011501",
  "status": "PENDING",
  "amount": "100.00000000",
  "currency": "USDT",
  "network": "TRON",
  "address": "TRX9Q8ybY6kWBM5wPKRxDKur7nFaYwYrUE",
  "qrCode": "https://api.payve.io/qr/pay_xGh8Kl9mNpQr.png",
  "paymentUrl": "https://pay.payve.io/checkout/pay_xGh8Kl9mNpQr",
  "expiresAt": "2024-01-15T11:30:00Z",
  "createdAt": "2024-01-15T10:30:00Z",
  "fee": {
    "amount": "1.00",
    "currency": "USDT",
    "rate": "1%"
  }
}

JSON

代码已折叠

共 18 行

查询支付订单

获取支付订单的详细信息和当前状态。

GET/payments/{orderId}

路径参数

参数	类型	说明
`orderId`	string	Payve 订单 ID 或商户订单号

响应示例

{
  "orderId": "pay_xGh8Kl9mNpQr",
  "merchantOrderId": "ORDER_2024011501",
  "status": "PAID",
  "amount": "100.00000000",
  "actualAmount": "100.00000000",
  "currency": "USDT",
  "network": "TRON",
  "address": "TRX9Q8ybY6kWBM5wPKRxDKur7nFaYwYrUE",
  "txHash": "0x742d35cc6634c0532925a3b844bc9e7595f0b0d0",
  "confirmations": 20,
  "requiredConfirmations": 20,
  "paidAt": "2024-01-15T10:45:00Z",
  "confirmedAt": "2024-01-15T10:46:00Z",
  "expiresAt": "2024-01-15T11:30:00Z",
  "createdAt": "2024-01-15T10:30:00Z",
  "fee": {
    "amount": "1.00",
    "currency": "USDT",
    "rate": "1%"
  },
  "metadata": {
    "userId": "user_123",
    "productId": "prod_456"
  }
}

JSON

代码已折叠

共 26 行

查询支付订单列表

获取商户的支付订单列表，支持分页和筛选。

GET/payments

查询参数

参数	类型	说明
`status`	string	订单状态筛选
`currency`	string	币种筛选
`network`	string	网络筛选
`startDate`	string	开始日期（ISO 8601）
`endDate`	string	结束日期（ISO 8601）
`page`	integer	页码，从 1 开始
`limit`	integer	每页数量，最大 100
`sort`	string	排序字段（createdAt, amount）
`order`	string	排序方向（asc, desc）

请求示例

GET /payments?status=PAID&currency=USDT&page=1&limit=20&sort=createdAt&order=desc

响应示例

{
  "data": [
    {
      "orderId": "pay_xGh8Kl9mNpQr",
      "merchantOrderId": "ORDER_2024011501",
      "status": "PAID",
      "amount": "100.00000000",
      "currency": "USDT",
      "network": "TRON",
      "paidAt": "2024-01-15T10:45:00Z",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": false
  }
}

JSON

代码已折叠

共 22 行

取消支付订单

取消一个待支付的订单。只有状态为 PENDING 的订单可以取消。

POST/payments/{orderId}/cancel

请求示例

{
  "reason": "用户取消订单"
}

响应示例

{
  "orderId": "pay_xGh8Kl9mNpQr",
  "status": "CANCELLED",
  "cancelledAt": "2024-01-15T10:35:00Z",
  "reason": "用户取消订单"
}

支付状态说明

状态	说明
`PENDING`	待支付 - 订单已创建，等待用户支付
`DETECTING`	检测中 - 检测到链上交易，等待确认
`CONFIRMING`	确认中 - 交易已广播，等待区块确认
`PAID`	已支付 - 支付成功，达到所需确认数
`EXPIRED`	已过期 - 订单超时未支付
`CANCELLED`	已取消 - 订单被商户取消
`FAILED`	失败 - 支付失败（如金额不足）
`REFUNDING`	退款中 - 正在处理退款
`REFUNDED`	已退款 - 退款完成

支付流程图

graph TD
    A[创建订单] --> B{用户支付}
    B -->|支付| C[检测交易]
    B -->|超时| D[订单过期]
    C --> E[等待确认]
    E -->|确认完成| F[支付成功]
    E -->|确认失败| G[支付失败]
    F --> H[发送Webhook]
    H --> I[商户处理]

幂等性

支付 API 支持幂等请求，通过在请求头中提供 Idempotency-Key 来避免重复创建订单：

POST /payments
Idempotency-Key: unique-request-id-123

在 24 小时内，使用相同的幂等键重复请求将返回第一次请求的结果。

错误处理

参见错误处理文档了解所有可能的错误码和处理建议。

最佳实践

1. 设置合理的过期时间

根据业务场景设置订单过期时间：

实物商品：30-60 分钟
虚拟商品：15-30 分钟
大额交易：60-120 分钟

2. 实现支付状态轮询

虽然我们提供 Webhook 通知，但建议同时实现轮询作为备份：

async function pollPaymentStatus(orderId, maxAttempts = 60) {
  for (let i = 0; i < maxAttempts; i++) {
    const payment = await getPayment(orderId);
    
    if (payment.status === 'PAID') {
      return payment;
    }
    
    if (['EXPIRED', 'FAILED', 'CANCELLED'].includes(payment.status)) {
      throw new Error(`Payment ${payment.status}`);
    }
    
    await sleep(5000); // 等待 5 秒
  }
  throw new Error('Payment timeout');
}

JAVASCRIPT

代码已折叠

共 16 行

3. 保存关键信息

创建订单后，务必保存以下信息：

订单 ID
收款地址
应付金额
过期时间

4. 处理支付异常

正确处理各种支付异常情况：

用户支付金额不足
用户支付金额过多
重复支付
网络异常

示例代码

Node.js 示例

const axios = require('axios');
 
const API_BASE = 'https://api.payve.io/api/v1';
const API_TOKEN = 'your-jwt-token';
 
// 创建支付订单
async function createPayment(amount, currency) {
  try {
    const response = await axios.post(
      `${API_BASE}/payments`,
      {
        amount: amount.toString(),
        currency: currency,
        merchantOrderId: `ORDER_${Date.now()}`,
        description: '测试订单',
        expiresIn: 1800
      },
      {
        headers: {
          'Authorization': `Bearer ${API_TOKEN}`,
          'Content-Type': 'application/json'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('创建订单失败:', error.response?.data);
    throw error;
  }
}
 
// 查询支付状态
async function getPaymentStatus(orderId) {
  try {
    const response = await axios.get(
      `${API_BASE}/payments/${orderId}`,
      {
        headers: {
          'Authorization': `Bearer ${API_TOKEN}`
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('查询订单失败:', error.response?.data);
    throw error;
  }
}

JAVASCRIPT

代码已折叠

共 50 行

Python 示例

import requests
import json
 
API_BASE = 'https://api.payve.io/api/v1'
API_TOKEN = 'your-jwt-token'
 
def create_payment(amount, currency):
    """创建支付订单"""
    headers = {
        'Authorization': f'Bearer {API_TOKEN}',
        'Content-Type': 'application/json'
    }
    
    data = {
        'amount': str(amount),
        'currency': currency,
        'description': '测试订单',
        'expiresIn': 1800
    }
    
    response = requests.post(
        f'{API_BASE}/payments',
        headers=headers,
        json=data
    )
    
    if response.status_code == 201:
        return response.json()
    else:
        raise Exception(f'创建订单失败: {response.text}')
 
def get_payment_status(order_id):
    """查询支付状态"""
    headers = {
        'Authorization': f'Bearer {API_TOKEN}'
    }
    
    response = requests.get(
        f'{API_BASE}/payments/{order_id}',
        headers=headers
    )
    
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f'查询订单失败: {response.text}')

PYTHON

代码已折叠

共 46 行

概述

创建支付订单

请求头

请求参数

最小金额限制

原生代币最小金额

稳定币最小金额

请求示例

响应参数

响应示例

查询支付订单

路径参数

响应示例

查询支付订单列表

查询参数

请求示例

响应示例

取消支付订单

请求示例

响应示例

支付状态说明

支付流程图

幂等性

错误处理

最佳实践

1. 设置合理的过期时间

2. 实现支付状态轮询

3. 保存关键信息

4. 处理支付异常

示例代码

Node.js 示例

Python 示例

相关文档