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:
0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238Router:
0xf7F058f7d65a7C799cc2AF7A4d202B9A690fAeA9API:
https://beta.saga.onl/v1Production
Network: Ethereum Mainnet
Chain ID: 1
USDC:
0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48Router:
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
});Testing Your Integration
Get Testnet USDC
You'll need Sepolia USDC to test payments. Get test tokens from:
- • Sepolia Faucet - Get Sepolia ETH first
- • Uniswap - Swap ETH for USDC on Sepolia
- • Circle Faucet - Direct USDC faucet
Test Payment Flow
- 1. Connect your MetaMask to Sepolia testnet
- 2. Ensure you have USDC tokens in your wallet
- 3. Set up a test webhook endpoint (use webhook.site)
- 4. Try a small payment (e.g., $0.01 USDC)
- 5. Check your webhook endpoint for notifications
Next Steps
Learn More
- SDK Reference →
Complete SDK documentation
- API Reference →
Backend integration guide
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