API文档

我们提供简单易用的RESTful API，帮助您将加密货币支付功能集成到您的应用程序中。

获取API凭证

在使用API之前，您需要先注册并获取API密钥。

获取API密钥

API端点

所有API请求都应发送到基本URL:

https://api.cryptopay.example.com/v1

创建钱包

POST /wallets

创建一个新的托管钱包。

请求参数

{
  "user_id": "用户唯一标识",
  "currency": ["ETH", "BNB", "USDT", "USDC"],  // 支持的货币类型
  "callback_url": "https://your-app.com/callback"  // 可选
}

响应

{
  "wallet_id": "w_123456789",
  "addresses": {
    "ETH": "0x1234567890abcdef1234567890abcdef12345678",
    "BNB": "bnb1234567890abcdef1234567890abcdef1234567",
    "USDT": "0x1234567890abcdef1234567890abcdef12345678",
    "USDC": "0x1234567890abcdef1234567890abcdef12345678"
  },
  "created_at": "2025-02-28T12:00:00Z"
}

获取钱包余额

GET /wallets/{wallet_id}/balance

获取指定钱包的余额。

路径参数

  • wallet_id - 钱包ID

响应

{
  "balances": {
    "ETH": {
      "available": "0.5",
      "pending": "0.0",
      "usd_value": "1500.00"
    },
    "BNB": {
      "available": "2.0",
      "pending": "0.0",
      "usd_value": "600.00"
    },
    "USDT": {
      "available": "1000.0",
      "pending": "0.0",
      "usd_value": "1000.00"
    },
    "USDC": {
      "available": "500.0",
      "pending": "0.0",
      "usd_value": "500.00"
    }
  },
  "total_usd_value": "3600.00"
}

创建支付请求

POST /payments

创建一个新的支付请求。

请求参数

{
  "amount": "100.00",
  "currency": "USDT",
  "description": "订单#12345的支付",
  "callback_url": "https://your-app.com/payment/callback",
  "success_url": "https://your-app.com/payment/success",
  "cancel_url": "https://your-app.com/payment/cancel",
  "metadata": {
    "order_id": "12345",
    "customer_id": "cust_987654"
  },
  "expires_in": 3600  // 过期时间（秒）
}

响应

{
  "payment_id": "pay_123456789",
  "status": "pending",
  "amount": "100.00",
  "currency": "USDT",
  "payment_url": "https://pay.cryptopay.example.com/p/123456789",
  "expires_at": "2025-02-28T13:00:00Z",
  "created_at": "2025-02-28T12:00:00Z"
}

获取支付状态

GET /payments/{payment_id}

获取指定支付请求的状态。

路径参数

  • payment_id - 支付ID

响应

{
  "payment_id": "pay_123456789",
  "status": "completed",
  "amount": "100.00",
  "currency": "USDT",
  "transaction_id": "tx_987654321",
  "paid_at": "2025-02-28T12:15:00Z",
  "created_at": "2025-02-28T12:00:00Z"
}

获取交易历史

GET /wallets/{wallet_id}/transactions

获取指定钱包的交易历史。

路径参数

  • wallet_id - 钱包ID

查询参数

  • currency - 货币类型（可选）
  • type - 交易类型：deposit, withdrawal, payment（可选）
  • start_date - 开始日期（可选）
  • end_date - 结束日期（可选）
  • limit - 每页记录数，默认20（可选）
  • page - 页码，默认1（可选）

响应

{
  "transactions": [
    {
      "id": "tx_123456789",
      "type": "deposit",
      "status": "completed",
      "currency": "ETH",
      "amount": "0.5",
      "fee": "0.001",
      "blockchain_txid": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
      "created_at": "2025-02-28T10:00:00Z",
      "completed_at": "2025-02-28T10:05:00Z"
    },
    {
      "id": "tx_987654321",
      "type": "payment",
      "status": "completed",
      "currency": "USDT",
      "amount": "100.00",
      "fee": "1.00",
      "blockchain_txid": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "created_at": "2025-02-28T12:00:00Z",
      "completed_at": "2025-02-28T12:05:00Z"
    }
  ],
  "pagination": {
    "total": 24,
    "page": 1,
    "limit": 20,
    "pages": 2
  }
}

认证

所有API请求都需要使用API密钥进行认证。您可以通过以下两种方式之一提供API密钥：

HTTP头认证（推荐）

Authorization: Bearer YOUR_API_KEY

查询参数认证

https://api.cryptopay.example.com/v1/wallets?api_key=YOUR_API_KEY

错误处理

当API请求失败时，您将收到相应的HTTP状态码和JSON格式的错误响应。

{
  "error": {
    "code": "invalid_request",
    "message": "请求参数无效",
    "details": {
      "amount": "金额必须大于0"
    }
  }
}

常见错误代码

HTTP状态码 错误代码 描述
400 invalid_request 请求参数无效
401 unauthorized API密钥无效或已过期
403 forbidden 没有权限执行此操作
404 not_found 请求的资源不存在
429 rate_limit_exceeded 超出API请求频率限制
500 server_error 服务器内部错误

客户端库

为了简化API集成，我们提供了多种编程语言的客户端库。

JavaScript

// 安装
npm install cryptopay-js-sdk

// 使用
const CryptoPay = require('cryptopay-js-sdk');
const client = new CryptoPay('YOUR_API_KEY');

// 创建支付请求
client.createPayment({
  amount: '100.00',
  currency: 'USDT',
  description: '订单#12345的支付'
})
.then(payment => console.log(payment))
.catch(error => console.error(error));

Python

# 安装
pip install cryptopay-python

# 使用
from cryptopay import CryptoPay

client = CryptoPay('YOUR_API_KEY')

# 创建支付请求
payment = client.create_payment(
    amount='100.00',
    currency='USDT',
    description='订单#12345的支付'
)
print(payment)

PHP

// 安装
composer require cryptopay/cryptopay-php

// 使用
require 'vendor/autoload.php';

$client = new \CryptoPay\Client('YOUR_API_KEY');

// 创建支付请求
$payment = $client->payments->create([
    'amount' => '100.00',
    'currency' => 'USDT',
    'description' => '订单#12345的支付'
]);
print_r($payment);

Webhooks

通过Webhooks，您可以实时接收支付和交易状态的更新。

配置Webhook

在创建钱包或支付请求时，您可以提供一个callback_url参数，我们将向该URL发送事件通知。

Webhook事件类型

Webhook请求格式

{
  "event": "payment.completed",
  "data": {
    "payment_id": "pay_123456789",
    "status": "completed",
    "amount": "100.00",
    "currency": "USDT",
    "transaction_id": "tx_987654321",
    "paid_at": "2025-02-28T12:15:00Z",
    "created_at": "2025-02-28T12:00:00Z"
  }
}

验证Webhook请求

为了确保Webhook请求的真实性，我们会在每个请求中包含一个签名头：

X-CryptoPay-Signature: t=1614513600,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

您可以使用以下代码验证签名：

// JavaScript示例
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const [timestamp, signatureHash] = signature.split(',');
  const [, timeValue] = timestamp.split('=');
  const [, hashValue] = signatureHash.split('=');
  
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(`${timeValue}.${payload}`)
    .digest('hex');
  
  return hashValue === expectedSignature;
}