JavaScript SDK

Payve JavaScript SDK 提供了简洁的 API 来集成加密货币支付功能，支持原生 JavaScript 以及所有现代前端框架。

特性概览

快速集成

几行代码即可集成支付功能

轻量级

核心包仅 12KB gzipped

实时更新

WebSocket 实时支付状态推送

安装

通过 npm

npm install @payve/sdk

通过 yarn

yarn add @payve/sdk

通过 CDN

<script src="https://cdn.payve.io/sdk/v1/payve.min.js"></script>

快速开始

1. 初始化 SDK

import Payve from '@payve/sdk';
 
// 初始化 SDK
const payve = new Payve({
  apiKey: 'pk_live_your_api_key_here',
  environment: 'production', // 或 'sandbox'
  currency: 'USDT',
  network: 'TRON'
});

2. 创建支付按钮

<button id="pay-button">使用加密货币支付 $100</button>
<div id="payment-container"></div>

document.getElementById('pay-button').addEventListener('click', async () => {
  try {
    const payment = await payve.createPayment({
      amount: '100.00',
      description: '测试订单',
      metadata: {
        orderId: 'ORDER_123'
      }
    });
    
    // 显示支付界面
    payve.mount('#payment-container', {
      payment: payment,
      onSuccess: (result) => {
        console.log('支付成功:', result);
        // 处理支付成功
      },
      onError: (error) => {
        console.error('支付失败:', error);
        // 处理支付失败
      }
    });
  } catch (error) {
    console.error('创建支付失败:', error);
  }
});

JAVASCRIPT

代码已折叠

共 26 行

API 参考

初始化选项

参数	类型	必填	默认值	说明
`apiKey`	string	✅	-	API 密钥
`environment`	string	❌	'production'	环境：'production' 或 'sandbox'
`currency`	string	❌	'USDT'	默认币种
`network`	string	❌	'TRON'	默认网络
`locale`	string	❌	'zh'	界面语言
`theme`	object	❌	-	主题配置

创建支付

`payve.createPayment(options)`

创建新的支付订单。

参数：

参数	类型	必填	说明
`amount`	string	✅	支付金额
`currency`	string	❌	币种，默认使用初始化设置
`network`	string	❌	网络，默认使用初始化设置
`description`	string	❌	订单描述
`metadata`	object	❌	自定义元数据
`expiresIn`	number	❌	过期时间（秒）

返回值：

{
  id: 'pay_abc123',
  amount: '100.00000000',
  currency: 'USDT',
  network: 'TRON',
  address: 'TRX9Q8ybY6kWBM5wPKRxDKur7nFaYwYrUE',
  qrCode: 'https://api.payve.io/qr/pay_abc123.png',
  status: 'pending',
  expiresAt: '2025-08-13T11:30:00Z'
}

挂载支付界面

`payve.mount(selector, options)`

将支付界面挂载到指定的 DOM 元素。

参数：

参数	类型	必填	说明
`selector`	string	✅	CSS 选择器
`options.payment`	object	✅	支付对象
`options.onSuccess`	function	❌	支付成功回调
`options.onError`	function	❌	支付失败回调
`options.onCancel`	function	❌	支付取消回调
`options.onExpire`	function	❌	支付过期回调

查询支付状态

`payve.getPayment(paymentId)`

查询支付状态。

const payment = await payve.getPayment('pay_abc123');
console.log(payment.status); // 'pending', 'paid', 'expired', 'failed'

事件监听

`payve.on(event, callback)`

监听 SDK 事件。

// 监听支付状态更新
payve.on('payment.updated', (payment) => {
  console.log('支付状态更新:', payment.status);
});
 
// 监听连接状态
payve.on('connection.status', (status) => {
  console.log('连接状态:', status); // 'connected', 'disconnected', 'reconnecting'
});
 
// 监听错误
payve.on('error', (error) => {
  console.error('SDK 错误:', error);
});

JAVASCRIPT

代码已折叠

共 14 行

完整示例

基础电商集成

<!DOCTYPE html>
<html lang="zh">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Payve 支付示例</title>
    <style>
        .product-card {
            max-width: 400px;
            margin: 50px auto;
            padding: 20px;
            border: 1px solid #ddd;
            border-radius: 8px;
        }
        .payment-container {
            margin-top: 20px;
            padding: 20px;
            background: #f9f9f9;
            border-radius: 8px;
        }
        .pay-button {
            width: 100%;
            padding: 12px;
            background: #007bff;
            color: white;
            border: none;
            border-radius: 4px;
            cursor: pointer;
            font-size: 16px;
        }
        .pay-button:hover {
            background: #0056b3;
        }
        .pay-button:disabled {
            background: #ccc;
            cursor: not-allowed;
        }
    </style>
</head>
<body>
    <div class="product-card">
        <h2>高级会员订阅</h2>
        <p>享受所有高级功能，包括：</p>
        <ul>
            <li>无限制 API 调用</li>
            <li>优先技术支持</li>
            <li>高级分析报表</li>
        </ul>
        <div class="price">
            <strong>价格: $99.99 USDT</strong>
        </div>
        
        <button class="pay-button" id="pay-button">
            立即购买
        </button>
        
        <div class="payment-container" id="payment-container" style="display: none;">
            <!-- 支付界面将挂载到这里 -->
        </div>
    </div>
 
    <script src="https://cdn.payve.io/sdk/v1/payve.min.js"></script>
    <script>
        // 初始化 Payve SDK
        const payve = new Payve({
            apiKey: 'pk_live_your_api_key_here',
            environment: 'production',
            currency: 'USDT',
            network: 'TRON',
            locale: 'zh'
        });
 
        const payButton = document.getElementById('pay-button');
        const paymentContainer = document.getElementById('payment-container');
 
        payButton.addEventListener('click', async () => {
            try {
                // 禁用按钮
                payButton.disabled = true;
                payButton.textContent = '创建订单中...';
 
                // 创建支付
                const payment = await payve.createPayment({
                    amount: '99.99',
                    description: '高级会员订阅',
                    metadata: {
                        productId: 'premium_subscription',
                        userId: 'user_123'
                    }
                });
 
                // 显示支付容器
                paymentContainer.style.display = 'block';
 
                // 挂载支付界面
                payve.mount('#payment-container', {
                    payment: payment,
                    onSuccess: (result) => {
                        console.log('支付成功:', result);
                        alert('支付成功！感谢您的购买！');
                        
                        // 重定向或刷新页面
                        window.location.href = '/success';
                    },
                    onError: (error) => {
                        console.error('支付失败:', error);
                        alert('支付失败: ' + error.message);
                        resetButton();
                    },
                    onCancel: () => {
                        console.log('用户取消支付');
                        resetButton();
                    },
                    onExpire: () => {
                        console.log('支付过期');
                        alert('支付已过期，请重新下单');
                        resetButton();
                    }
                });
 
            } catch (error) {
                console.error('创建支付失败:', error);
                alert('创建支付失败: ' + error.message);
                resetButton();
            }
        });
 
        function resetButton() {
            payButton.disabled = false;
            payButton.textContent = '立即购买';
            paymentContainer.style.display = 'none';
        }
 
        // 监听支付状态更新
        payve.on('payment.updated', (payment) => {
            console.log('支付状态更新:', payment);
            
            if (payment.status === 'paid') {
                // 支付成功的额外处理
                console.log('支付已确认');
            }
        });
 
        // 监听连接状态
        payve.on('connection.status', (status) => {
            if (status === 'disconnected') {
                console.warn('与服务器连接断开');
            } else if (status === 'connected') {
                console.log('已连接到服务器');
            }
        });
    </script>
</body>
</html>

HTML

代码已折叠

共 154 行

高级用法

自定义主题

const payve = new Payve({
    apiKey: 'pk_live_your_api_key_here',
    theme: {
        primaryColor: '#007bff',
        backgroundColor: '#ffffff',
        textColor: '#333333',
        borderRadius: '8px',
        fontFamily: 'Arial, sans-serif',
        qrCodeSize: 200
    }
});

JAVASCRIPT

代码已折叠

共 11 行

多币种支持

// 让用户选择币种
const supportedCurrencies = [
    { code: 'USDT', name: 'Tether USDT', networks: ['TRON', 'Ethereum', 'BSC'] },
    { code: 'BTC', name: 'Bitcoin', networks: ['Bitcoin'] },
    { code: 'ETH', name: 'Ethereum', networks: ['Ethereum'] }
];
 
async function createPaymentWithCurrency(currency, network) {
    const payment = await payve.createPayment({
        amount: '100.00',
        currency: currency,
        network: network,
        description: '商品购买'
    });
    
    return payment;
}

JAVASCRIPT

代码已折叠

共 17 行

批量订单处理

async function processBatchPayments(orders) {
    const payments = [];
    
    for (const order of orders) {
        try {
            const payment = await payve.createPayment({
                amount: order.amount,
                description: `订单 #${order.id}`,
                metadata: {
                    orderId: order.id,
                    customerId: order.customerId
                }
            });
            
            payments.push({
                orderId: order.id,
                payment: payment
            });
        } catch (error) {
            console.error(`创建支付失败 - 订单 ${order.id}:`, error);
        }
    }
    
    return payments;
}

JAVASCRIPT

代码已折叠

共 25 行

错误处理

常见错误类型

payve.createPayment({
    amount: '100.00'
}).catch(error => {
    switch (error.code) {
        case 'INVALID_API_KEY':
            console.error('API 密钥无效');
            break;
        case 'INVALID_AMOUNT':
            console.error('支付金额无效');
            break;
        case 'UNSUPPORTED_CURRENCY':
            console.error('不支持的币种');
            break;
        case 'RATE_LIMIT_EXCEEDED':
            console.error('请求频率超限');
            break;
        default:
            console.error('未知错误:', error.message);
    }
});

JAVASCRIPT

代码已折叠

共 20 行

网络错误处理

// 设置重试机制
async function createPaymentWithRetry(options, maxRetries = 3) {
    for (let i = 0; i < maxRetries; i++) {
        try {
            return await payve.createPayment(options);
        } catch (error) {
            if (error.code === 'NETWORK_ERROR' && i < maxRetries - 1) {
                console.log(`重试第 ${i + 1} 次...`);
                await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
                continue;
            }
            throw error;
        }
    }
}

JAVASCRIPT

代码已折叠

共 15 行

最佳实践

1. 安全考虑

始终使用 HTTPS
不要在前端代码中暴露 API Secret
验证支付结果时使用服务器端验证
实现 Webhook 接收支付通知

2. 用户体验

// 显示加载状态
function showLoading() {
    document.getElementById('loading').style.display = 'block';
}
 
function hideLoading() {
    document.getElementById('loading').style.display = 'none';
}
 
// 支付流程示例
async function handlePayment() {
    showLoading();
    
    try {
        const payment = await payve.createPayment(options);
        
        payve.mount('#payment-container', {
            payment: payment,
            onSuccess: (result) => {
                // 显示成功消息
                showSuccessMessage('支付成功！');
            },
            onError: (error) => {
                // 显示友好的错误消息
                showErrorMessage(getFriendlyErrorMessage(error));
            }
        });
        
    } catch (error) {
        showErrorMessage('创建支付失败，请稍后重试');
    } finally {
        hideLoading();
    }
}
 
function getFriendlyErrorMessage(error) {
    const messages = {
        'INVALID_AMOUNT': '支付金额格式不正确',
        'NETWORK_ERROR': '网络连接失败，请检查网络设置',
        'ORDER_EXPIRED': '订单已过期，请重新下单'
    };
    
    return messages[error.code] || '支付失败，请稍后重试';
}

JAVASCRIPT

代码已折叠

共 44 行

3. 性能优化

// 懒加载 SDK
async function loadPayveSDK() {
    if (window.Payve) {
        return window.Payve;
    }
    
    return new Promise((resolve, reject) => {
        const script = document.createElement('script');
        script.src = 'https://cdn.payve.io/sdk/v1/payve.min.js';
        script.onload = () => resolve(window.Payve);
        script.onerror = reject;
        document.head.appendChild(script);
    });
}
 
// 使用时才加载
async function initPayment() {
    const Payve = await loadPayveSDK();
    const payve = new Payve(config);
    // ... 其他逻辑
}

JAVASCRIPT

代码已折叠

共 21 行

环境配置

开发环境

const payve = new Payve({
    apiKey: 'pk_test_your_test_key_here',
    environment: 'sandbox',
    debug: true // 启用调试日志
});

生产环境

const payve = new Payve({
    apiKey: 'pk_live_your_live_key_here',
    environment: 'production',
    debug: false
});

浏览器兼容性

浏览器	最低版本
Chrome	60+
Firefox	55+
Safari	11+
Edge	79+
IE	不支持

特性概览

快速集成

轻量级

实时更新

安装

通过 npm

通过 yarn

通过 CDN

快速开始

1. 初始化 SDK

2. 创建支付按钮

API 参考

初始化选项

创建支付

payve.createPayment(options)

挂载支付界面

payve.mount(selector, options)

查询支付状态

payve.getPayment(paymentId)

事件监听

payve.on(event, callback)

完整示例

基础电商集成

高级用法

自定义主题

多币种支持

批量订单处理

错误处理

常见错误类型

网络错误处理

最佳实践

1. 安全考虑

2. 用户体验

3. 性能优化

环境配置

开发环境

生产环境

浏览器兼容性

相关文档

`payve.createPayment(options)`

`payve.mount(selector, options)`

`payve.getPayment(paymentId)`

`payve.on(event, callback)`