Quick Start

Get up and running with Saga payments in minutes

Quick Start Guide

Accept USDC payments in your application with just a few lines of code. No API keys, no complex setup - just install and start accepting payments.

Prerequisites

Node.js 18+ - For running your application
MetaMask or compatible wallet - For testing payments
USDC tokens - For testing (get testnet USDC from faucets)
Webhook endpoint - For receiving payment notifications (optional but recommended)

Installation

$ npm install @saga-pay/sdk ethers
# Install the Saga SDK and ethers.js for wallet integration
Note: The SDK requires ethers.js v6+ for wallet provider integration. Make sure you're using a compatible version.
📚
SDK Documentation: For complete SDK reference, configuration options, and advanced usage examples, visit theSDK Reference →

Basic Integration

Here's a complete example of integrating Saga payments into your React application:

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>
  );
}
That's it! This single saga.pay() call handles:
  • • Network validation
  • • Automatic USDC allowance approval
  • • Transaction creation and signing
  • • Payment processing with Saga
  • • Error handling and user feedback

Backend Integration

Set up a webhook endpoint to receive payment notifications and handle business logic:

// 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 });
});
Security Best Practice: Always validate webhook data with a GET request to/pay/{paymentId} to ensure you're processing the most current payment status.

Environment Configuration

Sandbox (Testing)

Network: Sepolia Testnet
Chain ID: 11155111
USDC:
0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238
Router:
0xf7F058f7d65a7C799cc2AF7A4d202B9A690fAeA9
API:
https://beta.saga.onl/v1

Production

Network: Ethereum Mainnet
Chain ID: 1
USDC:
0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
Router:
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
});

Testing Your Integration

Get Testnet USDC

You'll need Sepolia USDC to test payments. Get test tokens from:

Test Payment Flow

  1. 1. Connect your MetaMask to Sepolia testnet
  2. 2. Ensure you have USDC tokens in your wallet
  3. 3. Set up a test webhook endpoint (use webhook.site)
  4. 4. Try a small payment (e.g., $0.01 USDC)
  5. 5. Check your webhook endpoint for notifications

Next Steps

Learn More

Go Live

  • Switch to Production:

    Simply change environment: 'production' in your SDK config

  • That's it!

    Saga handles all the complexity - contract addresses, network validation, and payment processing

Found a bug or have a question?

Report an Issue