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:
0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238
Router:
0xf7F058f7d65a7C799cc2AF7A4d202B9A690fAeA9
API:
https://beta.saga.onl/v1

Producción

Red: 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
});

Probar tu Integración

Obtener USDC de Testnet

Necesitarás USDC de Sepolia para probar pagos. Obtén tokens de prueba desde:

Flujo de Pago de Prueba

  1. 1. Conecta tu MetaMask a la testnet de Sepolia
  2. 2. Asegúrate de tener tokens USDC en tu billetera
  3. 3. Configura un endpoint de webhook de prueba (usa webhook.site)
  4. 4. Prueba un pago pequeño (ej., $0.01 USDC)
  5. 5. Verifica tu endpoint de webhook para notificaciones

Próximos Pasos

Aprende Más

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