Inicio Rápido
Pon en marcha Saga en minutos
Guía de Inicio Rápido
Acepta pagos USDC en tu aplicación con solo unas pocas líneas de código. Sin claves API, sin configuración compleja - solo instala y comienza a aceptar pagos.
Prerrequisitos
•
Node.js 18+ - Para ejecutar tu aplicación
•
MetaMask o billetera compatible - Para probar pagos
•
Tokens USDC - Para pruebas (obtén USDC de testnet desde faucets)
•
Endpoint de webhook - Para recibir notificaciones de pago (opcional pero recomendado)
Instalación
$ npm install @saga-pay/sdk ethers
# Install the Saga SDK and ethers.js for wallet integration•
Nota: El SDK requiere ethers.js v6+ para la integración del proveedor de billetera. Asegúrate de usar una versión compatible.
📚
Documentación del SDK: Para la referencia completa del SDK, opciones de configuración y ejemplos de uso avanzado, visitaSDK Reference →
Integración Básica
Aquí tienes un ejemplo completo de integración de pagos Saga en tu aplicación React:
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>
);
}•
¡Eso es todo! Esta única llamada saga.pay() maneja:
- • Validación de red
- • Aprobación automática de asignación USDC
- • Creación y firma de transacciones
- • Procesamiento de pagos con Saga
- • Manejo de errores y retroalimentación del usuario
Integración Backend
Configura un endpoint de webhook para recibir notificaciones de pago y manejar la lógica de negocio:
// 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 });
});•
Mejor Práctica de Seguridad: Siempre valida los datos del webhook con una solicitud GET a
/pay/{paymentId} para asegurarte de procesar el estado de pago más actualizado.Configuración del Entorno
Sandbox (Pruebas)
Red: Sepolia Testnet
Chain ID: 11155111
USDC:
0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238Router:
0xf7F058f7d65a7C799cc2AF7A4d202B9A690fAeA9API:
https://beta.saga.onl/v1Producción
Red: 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
});Probar tu Integración
Obtener USDC de Testnet
Necesitarás USDC de Sepolia para probar pagos. Obtén tokens de prueba desde:
- • Sepolia Faucet - Get Sepolia ETH first
- • Uniswap - Swap ETH for USDC on Sepolia
- • Circle Faucet - Direct USDC faucet
Flujo de Pago de Prueba
- 1. Conecta tu MetaMask a la testnet de Sepolia
- 2. Asegúrate de tener tokens USDC en tu billetera
- 3. Configura un endpoint de webhook de prueba (usa webhook.site)
- 4. Prueba un pago pequeño (ej., $0.01 USDC)
- 5. Verifica tu endpoint de webhook para notificaciones
Próximos Pasos
Aprende Más
- Referencia del SDK →
Documentación completa del SDK
- Referencia de API →
Guía de integración backend
Poner en Producción
- Cambiar a Producción:
Simplemente cambia
environment: 'production'en la configuración de tu SDK - ¡Eso es todo!
Saga maneja toda la complejidad - direcciones de contratos, validación de red y procesamiento de pagos
Found a bug or have a question?
Report an Issue