快速开始

在几分钟内启动并运行 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
路由器:
0xf7F058f7d65a7C799cc2AF7A4d202B9A690fAeA9
API:
https://beta.saga.onl/v1

生产

网络: Ethereum Mainnet
链 ID: 1
USDC:
0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
路由器:
0x88849eE1DABB713D240c34A365D71F0AEF50c218
API:
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 来测试支付。从以下位置获取测试代币:

测试支付流程

  1. 1. 将您的 MetaMask 连接到 Sepolia 测试网
  2. 2. 确保您的钱包中有 USDC 代币
  3. 3. 设置测试 webhook 端点(使用 webhook.site)
  4. 4. 尝试小额支付(例如,$0.01 USDC)
  5. 5. 检查您的 webhook 端点以获取通知

下一步

了解更多

上线

  • 切换到生产:

    只需更改 environment: 'production' 在您的 SDK 配置中

  • 就是这样!

    Saga 处理所有复杂性 - 合约地址、网络验证和支付处理

Found a bug or have a question?

Report an Issue