快速开始
在几分钟内启动并运行 Saga
快速开始指南
只需几行代码即可在您的应用程序中接受 USDC 支付。无需 API 密钥,无需复杂设置 - 只需安装并开始接受支付。
先决条件
•
Node.js 18+ - 用于运行您的应用程序
•
MetaMask 或兼容钱包 - 用于测试支付
•
USDC 代币 - 用于测试(从水龙头获取测试网 USDC)
•
Webhook 端点 - 用于接收支付通知(可选但推荐)
安装
$ npm install @saga-pay/sdk ethers
# Install the Saga SDK and ethers.js for wallet integration•
注意: SDK 需要 ethers.js v6+ 用于钱包提供者集成。请确保您使用的是兼容版本。
📚
SDK 文档: 有关完整的 SDK 参考、配置选项和高级用法示例,请访问SDK Reference →
基本集成
以下是在 React 应用程序中集成 Saga 支付的完整示例:
import { Saga } from '@saga-pay/sdk';
import { ethers } from 'ethers';
import { useState } from 'react';
function PaymentButton() {
const [loading, setLoading] = useState(false);
const [status, setStatus] = useState('');
const handlePayment = async () => {
try {
setLoading(true);
setStatus('Connecting wallet...');
// Get wallet provider (MetaMask, Coinbase Wallet, etc.)
const provider = new ethers.BrowserProvider(window.ethereum);
// Initialize Saga SDK
const saga = new Saga({
environment: 'sandbox', // or 'production'
walletProvider: provider
});
setStatus('Processing payment...');
// Single payment call - handles everything
const result = await saga.pay({
merchantAddress: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
amount: '10.00',
callbackUrl: 'https://myapp.com/webhook', // Your backend webhook
metadata: {
orderId: 'order-123',
customerEmail: 'customer@example.com'
}
});
setStatus(`Payment initiated: ${result.paymentId}`);
// Optional: Poll for status updates
const pollStatus = async () => {
const status = await saga.getPaymentStatus(result.paymentId);
setStatus(`Status: ${status.status}`);
};
} catch (error) {
setStatus(`Error: ${error.message}`);
} finally {
setLoading(false);
}
};
return (
<div className="p-6 border rounded-lg">
<button
onClick={handlePayment}
disabled={loading}
className="bg-blue-600 text-white px-6 py-3 rounded-lg font-semibold hover:bg-blue-700 disabled:opacity-50"
>
{loading ? 'Processing...' : 'Pay $10.00 USDC'}
</button>
{status && <p className="mt-4 text-gray-600">{status}</p>}
</div>
);
}•
就是这样! 这个单一的 saga.pay() 调用处理:
- • 网络验证
- • 自动 USDC 授权批准
- • 交易创建和签名
- • 使用 Saga 处理支付
- • 错误处理和用户反馈
后端集成
设置 webhook 端点以接收支付通知并处理业务逻辑:
// Express.js webhook handler
app.post('/webhook', async (req, res) => {
const { paymentId, status, amount, metadata } = req.body;
console.log(`Payment ${paymentId}: ${status}`);
if (status === 'COMPLETED') {
// 🔒 SECURITY: Always validate with GET request
const actualPayment = await fetch(`https://api.saga.onl/v1/pay/${paymentId}`);
const actualStatus = actualPayment.status;
if (actualStatus === 'COMPLETED') {
// Handle successful payment
await updateOrderStatus(metadata.orderId, 'paid');
await sendConfirmationEmail(metadata.customerEmail);
await fulfillOrder(metadata.orderId);
}
}
res.status(200).json({ received: true });
});•
安全最佳实践: 始终使用 GET 请求验证 webhook 数据到
/pay/{paymentId} 以确保您正在处理最新的支付状态。环境配置
沙盒(测试)
网络: Sepolia Testnet
链 ID: 11155111
USDC:
0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238路由器:
0xf7F058f7d65a7C799cc2AF7A4d202B9A690fAeA9API:
https://beta.saga.onl/v1生产
网络: Ethereum Mainnet
链 ID: 1
USDC:
0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48路由器:
0x88849eE1DABB713D240c34A365D71F0AEF50c218API:
https://api.saga.onl/v1// Environment configuration
const saga = new Saga({
environment: 'sandbox', // 'sandbox' or 'production'
walletProvider: provider
});
// For production
const saga = new Saga({
environment: 'production',
walletProvider: provider
});测试您的集成
获取测试网 USDC
您需要 Sepolia USDC 来测试支付。从以下位置获取测试代币:
- • Sepolia Faucet - Get Sepolia ETH first
- • Uniswap - Swap ETH for USDC on Sepolia
- • Circle Faucet - Direct USDC faucet
测试支付流程
- 1. 将您的 MetaMask 连接到 Sepolia 测试网
- 2. 确保您的钱包中有 USDC 代币
- 3. 设置测试 webhook 端点(使用 webhook.site)
- 4. 尝试小额支付(例如,$0.01 USDC)
- 5. 检查您的 webhook 端点以获取通知
下一步
Found a bug or have a question?
Report an Issue