iPagos TS/JS SDK

SDK oficial para integración a través del ecosistema iPagos.

[!IMPORTANT] Este SDK está diseñado para ejecutarse exclusivamente en backend por motivos de seguridad.

📑 Tabla de Contenidos

• 🚀 Instalación
• 📌 Descripción General
• 🏗 Arquitectura Recomendada
• 🔑 Configuración
• 📘 Métodos Disponibles
  • 1️⃣ createSession()
  • 2️⃣ getPaymentDetails()
  • 3️⃣ createPaymentToken()
  • 4️⃣ createCharge()
  • 5️⃣ refundsPayment()
• 📦 Dependencias
• 🔐 Seguridad
• 📊 Buenas Prácticas
• 🏦 Casos de Uso
• 🚀 Puesta en Producción

🚀 Instalación

Instala el SDK utilizando tu gestor de paquetes favorito:

npm install ipagos-js-sdk

(O usa yarn add ipagos-js-sdk / pnpm add ipagos-js-sdk según tu entorno de trabajo).

📌 Descripción General

El SDK de iPagos permite a los desarrolladores integrar flujos de pago complejos de forma sencilla. Entre sus capacidades principales se encuentran:

• Crear sesiones seguras para Flex.
• Obtener transient tokens.
• Procesar pagos.
• Tokenizar tarjetas.
• Realizar cobros recurrentes.
• Ejecutar reembolsos.
• Consultar detalles de pago.

🏗 Arquitectura Recomendada

Flujo estándar de integración:

1. Backend → Llama a createSession().
2. Frontend → Inicializa Flex utilizando el sessionToken.
3. Frontend → Genera el transientToken del lado del cliente.
4. Backend → Ejecuta getPaymentDetails() (opcional, para validaciones previas).
5. Backend → Invoca createPaymentToken() o createCharge() para procesar la transacción.
6. Backend → Utiliza refundsPayment() (si aplica un reembolso posteriormente).

🔑 Configuración

Inicializa el cliente con tus credenciales. Asegúrate de mantener estas claves seguras mediante variables de entorno.

import { iPagosCSClient } from 'ipagos-js-sdk';

const client = new iPagosCSClient({
  environment: "sandbox", // o "production"
  merchantId: "your_merchant_id",
  keyId: "your_key_id",
  secretKey: "your_secret_key_base64"
});

📘 Métodos Disponibles

1️⃣ createSession()

Genera el contexto y la sesión necesarios para inicializar Flex en el frontend.

await client.createSession({
  targetOrigins: "https://micomercio.com"
});

• ✅ Genera una sesión temporal.
• ✅ Permite obtener el transientToken desde el frontend.
• ✅ No realiza ningún cobro en este paso.

2️⃣ getPaymentDetails()

Obtiene información detallada de la tarjeta asociada a un transientToken.

await client.getPaymentDetails(transientToken);

• ✅ No realiza ningún cobro.
• ✅ Permite ejecutar validaciones previas.
• ✅ Especialmente útil para reglas de negocio y sistemas antifraude.

3️⃣ createPaymentToken()

Procesa un pago utilizando el transientToken.

await client.createPaymentToken({
  transientToken,
  internalId: "ORDER_123",
  amountDetails: {
    totalAmount: 100.00,
    currency: "MXN"
  },
  billTo: { /* ... datos de facturación ... */ }
});

Modos de uso:

| Escenario | actionList | actionTokenTypes | | :--- | :--- | :--- | | Solo cobrar | [] | [] | | Cobrar + tokenizar | ["TOKEN_CREATE"] | ["customer", "paymentInstrument"] | | Solo tokenizar | capture = false | TOKEN_CREATE |

4️⃣ createCharge()

Realiza un cobro utilizando un token previamente generado (ideal para pagos almacenados).

await client.createCharge({
  internalId: "SUB_001",
  amountDetails: {
    totalAmount: 299.99,
    currency: "MXN"
  },
  customer_id: "customer_id",
  paymentInstrument_id: "instrument_id"
});

Ideal para:

• 🔄 Suscripciones
• 📅 Renovaciones
• ⚙️ Cobros automáticos
• 🔁 Reintentos de cobro

5️⃣ refundsPayment()

Realiza un reembolso total o parcial sobre una transacción previa.

await client.refundsPayment({
  paymentId: "payment_id",
  amountDetails: {
    totalAmount: "100.00",
    currency: "MXN"
  }
});

[!WARNING] Límites de Reembolso

• El monto del reembolso no puede exceder el monto capturado originalmente.
• La moneda (currency) debe coincidir obligatoriamente con la de la transacción original.

📦 Dependencias

El SDK está construido utilizando las siguientes dependencias clave:

• axios: ^1.13.5
• crypto: ^1.0.1

🔐 Seguridad

[!IMPORTANT] Consideraciones Críticas de Seguridad

• Nunca exponer key, secret ni merchantId (mid) en el entorno frontend.
• Ejecutar las llamadas de este SDK únicamente en tu backend.
• No almacenar el transientToken en tus bases de datos (es de un solo uso temporal).
• Implementar mecanismos de idempotencia en tu lado para evitar cargos duplicados.

📊 Buenas Prácticas

• 🆔 Usar UUID, o un número acompañado de un prefijo/sufijo como internalId.
• 📝 Registrar siempre todos los paymentId y refundId generados.
• 🗄️ Implementar logging estructurado en tu aplicación para facilitar la trazabilidad.
• ♻️ Manejar un sistema de retries controlados ante posibles fallas de red.

🏦 Casos de Uso

Este SDK se adapta perfectamente a diversas industrias y modelos de negocio:

• 🛒 Ecommerce
• 💻 SaaS (Software as a Service)
• 🔁 Suscripciones
• 🎟️ Membresías
• 🏪 Marketplaces
• 💸 Fintechs

🚀 Puesta en Producción

Antes de lanzar a producción, asegúrate de cumplir con la siguiente lista de verificación:

• [ ] Validar el flujo completo en el entorno sandbox.
• [ ] Confirmar que los dominios en targetOrigins sean los correctos para producción.
• [ ] Validar la correcta recepción y procesamiento de webhooks.
• [ ] Implementar monitoreo y alertas sobre las integraciones de pago.