支付接口

Payve 支付接口允许您创建、查询和管理加密货币支付订单。

认证要求

所有支付接口都需要 JWT 认证。请在请求头中包含：

Authorization: Bearer your_jwt_token

创建支付订单

POST/api/v1/payments

请求参数

参数名	类型	必填	描述
amount	string	是	支付金额，使用字符串避免精度问题
currency	string	是	币种：BTC, ETH, USDT, USDC, BNB, SOL
callbackUrl	string	否	支付完成后的回调URL

请求示例

curl -X POST https://api.staging.payve.web3noah.com/api/v1/payments \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_jwt_token" \
  -d '{
    "amount": "100.50",
    "currency": "USDT",
    "callbackUrl": "https://yoursite.com/webhook"
  }'

响应示例

{
  "success": true,
  "data": {
    "orderId": "clrxxx",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5oNDMnt",
    "amount": "100.50",
    "currency": "USDT",
    "expiresAt": "2024-01-15T12:30:00.000Z"
  }
}

查询支付状态

GET/api/v1/payments/{orderId}

路径参数

参数名	类型	描述
orderId	string	支付订单ID

请求示例

curl -X GET https://api.staging.payve.web3noah.com/api/v1/payments/clrxxx \
  -H "Authorization: Bearer your_jwt_token"

响应示例

{
  "success": true,
  "data": {
    "orderId": "clrxxx",
    "status": "COMPLETED",
    "amount": "100.50",
    "currency": "USDT",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5oNDMnt",
    "txHash": "0xabcdef...",
    "confirmations": 12,
    "requiredConfirmations": 12,
    "createdAt": "2024-01-15T12:00:00.000Z",
    "paidAt": "2024-01-15T12:05:00.000Z"
  }
}

支付状态说明

状态	描述
PENDING	订单已创建，等待用户支付
CONFIRMING	已检测到支付，正在等待区块链确认
COMPLETED	支付成功，已达到要求的确认数
FAILED	支付失败
EXPIRED	订单已过期（默认30分钟）

常见错误码

错误码	描述	解决方案
INVALID_AMOUNT	无效的金额格式	确保金额大于0且格式正确
UNSUPPORTED_CURRENCY	不支持的币种	使用支持的币种：BTC, ETH, USDT, USDC, BNB, SOL
PAYMENT_NOT_FOUND	支付订单不存在	检查订单ID是否正确
UNAUTHORIZED	未授权访问	检查JWT令牌是否有效