ipagos-js-sdk 1.0.0

package/README.md

@@ -0,0 +1,150 @@
+# iPagos SDK
+
+Bienvenido al ecosistema de **iPagos**.
+
+iPagos provee librerías oficiales que permiten integrar tu afiliación
+mediante tu **MID** y **API Keys**, habilitando la aceptación de pagos
+en línea, tokenización de tarjetas y cobros automáticos de forma segura
+y escalable.
+
+------------------------------------------------------------------------
+
+## 🌎 ¿Qué es iPagos?
+
+**iPagos** es una plataforma de procesamiento de pagos que te permite:
+
+- 💳 Realizar cobros en línea mediante formulario eCommerce.
+- 🔐 Tokenizar tarjetas de crédito de tus clientes.
+- 🔁 Implementar cobros automáticos (recurrencias).
+- ⚡ Ejecutar cobros manuales o directos.
+- 🧾 Realizar cobros directos sin tokenización cuando el flujo lo requiera.
+
+------------------------------------------------------------------------
+
+## 🔑 Requisitos de Integración  
+
+Para comenzar necesitas:
+
+-  **MID (Merchant ID)** asignado por iPagos.
+-  **API Keys** (key y secret).
+- Acceso al entorno sandbox o producción.
+
+Si aún no cuentas con tus credenciales, contacta a tu ejecutivo de iPagos.
+
+------------------------------------------------------------------------
+
+## 📦 SDKs Oficiales
+
+Actualmente contamos con librerías oficiales para:
+
+- 🟦 **TypeScript / JavaScript (Node.js y Frontend)**
+
+  [Guía de uso](./docs/ts.md)
+
+Si necesitas integración en otro lenguaje (Java, PHP, Python, C#, etc.), puedes solicitarlo y:
+
+- Creamos la librería oficial.
+- Brindamos capacitación técnica.
+- Acompañamos el proceso de integración.
+------------------------------------------------------------------------
+
+## 🛠 Funcionalidades Principales  
+
+### 1️⃣ Pagos en línea (eCommerce)
+Permite integrar un formulario seguro para:
+
+- Capturar datos de tarjeta.
+- Procesar pagos en tiempo real.
+- Obtener respuesta inmediata de autorización.
+
+Ideal para:
+- Tiendas en línea
+- Servicios digitales
+- Plataformas SaaS
+
+------------------------------------------------------------------------
+
+### 2️⃣ Tokenización de Tarjetas
+
+La tokenización permite:
+
+- Guardar un identificador seguro del método de pago.
+- Evitar almacenar datos sensibles en tu servidor.
+- Cumplir mejores prácticas de seguridad.
+
+Casos de uso:
+- Suscripciones
+- Membresías
+- Cobros recurrentes
+- Pagos rápidos con tarjeta guardada
+
+------------------------------------------------------------------------
+
+### 3️⃣ Cobros Automáticos (Recurrencia)
+
+Puedes implementar:
+
+- ⏰ Un programador de cobros estilo **cronjob**
+- 🔄 Ejecuciones automáticas programadas
+- 💳 Cobros directos usando token
+- ⚡ Cobros directos sin tokenización (cuando aplique)
+
+Ejemplo de escenarios:
+
+- Suscripciones mensuales
+- Planes anuales
+- Membresías premium
+- Financiamientos
+
+------------------------------------------------------------------------
+
+### 4️⃣ Cobros Manuales
+
+Permite:
+
+- Ejecutar un cobro bajo demanda.
+- Procesar pagos administrativos.
+- Realizar cargos únicos fuera del flujo automático.
+
+------------------------------------------------------------------------
+
+## 🔒 Seguridad
+  
+El ecosistema iPagos está diseñado bajo principios de:
+
+- Tokenización segura
+- Separación de llaves públicas y privadas
+- Buenas prácticas de protección de datos
+- Cumplimiento de estándares de la industria
+
+------------------------------------------------------------------------
+## 🏗 Arquitectura Recomendada
+
+Flujo típico de integración:
+
+1. Frontend obtiene token de transición  seguro.
+2. Backend utiliza API privada para:
+- Crear cargos
+- Programar recurrencias
+- Consultar transacciones
+
+
+------------------------------------------------------------------------
+
+## 🤝 Soporte e Integraciones Especiales
+
+Si requieres:
+
+- SDK en otro lenguaje
+- Integraciones empresariales
+- Capacitación técnica
+- Acompañamiento en implementación
+
+Contáctanos y diseñamos la solución adecuada para tu proyecto.
+integraciones@ipagos.lat
+
+------------------------------------------------------------------------
+
+# 💡 iPagos
+
+Procesamiento inteligente de pagos para tu ecosistema digital.

package/dist/client.d.ts

@@ -0,0 +1,531 @@
+import { BillTo, CSClientConfig, iPagosCSClientResponse } from './types';
+export declare class iPagosCSClient {
+    private readonly config;
+    private client;
+    constructor(config: CSClientConfig);
+    private handleError;
+    /**
+     * Firma CyberSource
+     */
+    private sign;
+    /**
+     * POST CyberSource
+     */
+    post<T = any>(path: string, body: unknown): Promise<iPagosCSClientResponse<T>>;
+    /**
+     * GET CyberSource
+     */
+    get<T = any>(path: string): Promise<iPagosCSClientResponse<T>>;
+    /**
+     * getPaymentDetails
+     * -------------------------------------------------------
+     * Obtiene los detalles del pago asociados a un
+     * transientToken generado por Flex (Microform).
+     *
+     * ⚠️ Este método NO realiza ningún cobro.
+     * Solo recupera información contenida en el token
+     * de transición.
+     *
+     * -------------------------------------------------------
+     * ¿Para qué sirve?
+     *
+     * - Validar información antes de procesar el pago.
+     * - Obtener últimos 4 dígitos de tarjeta.
+     * - Verificar marca (VISA, MASTERCARD, etc.).
+     * - Aplicar reglas antifraude previas al cobro.
+     * - Mostrar resumen de pago al usuario.
+     *
+     * -------------------------------------------------------
+     * FLUJO TÍPICO:
+     *
+     * 1️⃣ Backend genera sesión (createSession).
+     * 2️⃣ Frontend usa Flex para capturar tarjeta.
+     * 3️⃣ Flex genera transientToken.
+     * 4️⃣ Backend recibe transientToken.
+     * 5️⃣ Se llama getPaymentDetails() para inspección.
+     * 6️⃣ Luego se decide si ejecutar createPaymentToken().
+     *
+     * -------------------------------------------------------
+     * @param transientToken
+     * Token de transición (JWT) generado por Flex.
+     *
+     * ⚠️ Es de un solo uso.
+     * ⚠️ Tiene vigencia limitada.
+     * ⚠️ No representa un pago aún.
+     *
+     * -------------------------------------------------------
+     * @returns Promise<iPagosCSClientResponse<T>>
+     *
+     * Respuesta exitosa:
+     *
+     * {
+     *   success: true,
+     *   data: {
+     *     paymentInformation: {
+     *       card: {
+     *         type: string,
+     *         expirationMonth: string,
+     *         expirationYear: string,
+     *         bin: string,
+     *         last4: string
+     *       }
+     *     }
+     *   }
+     * }
+     *
+     * Respuesta de error:
+     *
+     * {
+     *   success: false,
+     *   status?: number,
+     *   error: any
+     * }
+     *
+     * -------------------------------------------------------
+     * 🔐 SEGURIDAD
+     *
+     * Este método debe ejecutarse únicamente en backend.
+     *
+     * Aunque no realiza cobro, el transientToken es sensible
+     * y no debe exponerse innecesariamente.
+     *
+     * -------------------------------------------------------
+     * 🧠 Buenas Prácticas
+     *
+     * - No almacenar transientToken en base de datos.
+     * - Usarlo inmediatamente y descartarlo.
+     * - Validar coherencia antes de ejecutar el cobro.
+     *
+     * -------------------------------------------------------
+     */
+    getPaymentDetails<T = any>(transientToken: string): Promise<iPagosCSClientResponse<any>>;
+    /**
+   * refundsPayment
+   * -------------------------------------------------------
+   * Realiza un reembolso (refund) utilizando el paymentId
+   * de una transacción previamente capturada.
+   *
+   * ⚠️ Solo puede ejecutarse sobre pagos ya autorizados
+   * y capturados.
+   *
+   * -------------------------------------------------------
+   * ¿Qué hace este método?
+   *
+   * - Genera una transacción de tipo REFUND.
+   * - Devuelve el monto especificado al método de pago original.
+   * - Se asocia directamente al paymentId original.
+   *
+   * -------------------------------------------------------
+   * CONSIDERACIONES IMPORTANTES
+   *
+   * - amountDetails.totalAmount debe coincidir con:
+   *   • El monto total original (para refund completo), o
+   *   • Un monto menor (para refund parcial).
+   *
+   * - currency debe ser la misma moneda del cobro original.
+   *
+   * ⚠️ No se puede reembolsar más del monto capturado.
+   * ⚠️ No se puede cambiar la moneda.
+   *
+   * -------------------------------------------------------
+   * @param paymentId
+   * Identificador del pago original generado por CyberSource.
+   *
+   * Ejemplo:
+   *   "7123456789012345678901"
+   *
+   * Este ID se obtiene al ejecutar createPaymentToken()
+   * o createCharge().
+   *
+   * -------------------------------------------------------
+   * @param amountDetails
+   * Información del monto a reembolsar.
+   *
+   * - totalAmount: string con 2 decimales.
+   *   Ejemplo: "100.00"
+   *
+   * - currency: Código ISO 4217 en mayúsculas.
+   *   Ejemplo: "MXN", "USD"
+   *
+   * ⚠️ Debe coincidir con la moneda del pago original.
+   *
+   * -------------------------------------------------------
+   * @returns Promise<iPagosCSClientResponse<T>>
+   *
+   * Respuesta exitosa:
+   *
+   * {
+   *   success: true,
+   *   data: {
+   *     id: string,
+   *     status: string,
+   *     ...
+   *   }
+   * }
+   *
+   * Respuesta de error:
+   *
+   * {
+   *   success: false,
+   *   status?: number,
+   *   error: any
+   * }
+   *
+   * -------------------------------------------------------
+   * 🧠 CASOS DE USO COMUNES
+   *
+   * - Cancelación de pedido.
+   * - Devolución parcial.
+   * - Ajuste administrativo.
+   * - Reversión por error operativo.
+   *
+   * -------------------------------------------------------
+   * 🔐 SEGURIDAD Y CONTABILIDAD
+   *
+   * - Registrar internamente cada refund.
+   * - Asociar refund con orden interna.
+   * - No ejecutar reembolsos duplicados.
+   *
+   * Recomendado:
+   * Implementar control interno de idempotencia.
+   *
+   * -------------------------------------------------------
+   */
+    refundsPayment<T = any>({ paymentId, amountDetails }: {
+        paymentId: string;
+        amountDetails: {
+            totalAmount: string;
+            currency: string;
+        };
+    }): Promise<iPagosCSClientResponse<T>>;
+    /**
+     * createPaymentToken
+     * -------------------------------------------------------
+     * Procesa un pago utilizando un transientToken generado
+     * desde el SDK de Flex (Microform).
+     *
+     * Este método permite:
+     *
+     * 1️⃣ Realizar únicamente el cobro (sin tokenización).
+     * 2️⃣ Realizar cobro y crear token permanente.
+     * 3️⃣ Solo tokenizar sin capturar fondos (capture = false).
+     *
+     * 🔹 COMPORTAMIENTO SEGÚN CONFIGURACIÓN:
+     *
+     * • Cobro sin tokenizar:
+     *    actionList = []
+     *    actionTokenTypes = []
+     *
+     * • Cobro + tokenización (por defecto):
+     *    actionList = ["TOKEN_CREATE"]
+     *    actionTokenTypes = ["customer", "paymentInstrument"]
+     *
+     * • Solo tokenización (sin captura):
+     *    capture = false
+     *
+     * -------------------------------------------------------
+     * @param transientToken
+     * Token de transición (JWT) generado desde el SDK de Flex.
+     * Este token representa la tarjeta del cliente de forma segura.
+     *
+     * ⚠️ Es de un solo uso y expira rápidamente.
+     *
+     * @param internalId
+     * Identificador interno único del comercio.
+     * Se envía como clientReferenceInformation.code.
+     *
+     * ⚠️ Debe ser único por transacción (recomendado usar UUID).
+     *
+     * @param amountDetails
+     * Información del monto del pago.
+     *
+     * - totalAmount: Número con máximo 2 decimales.
+     *   Ejemplo válido: 100.00
+     *
+     * - currency: Código de moneda ISO 4217 en mayúsculas.
+     *   Ejemplo: "MXN", "USD"
+     *
+     * ⚠️ Currency debe ser de 3 caracteres.
+     *
+     * @param billTo
+     * Información de facturación del cliente.
+     * Debe cumplir con la estructura requerida por CyberSource.
+     *
+     * @param actionList (Opcional)
+     * Define acciones adicionales a ejecutar.
+     *
+     * - ["TOKEN_CREATE"] → Crea token permanente.
+     * - [] → No crea token.
+     *
+     * @param actionTokenTypes (Opcional)
+     * Define qué tipos de token se crearán.
+     *
+     * Valores comunes:
+     * - "customer"
+     * - "paymentInstrument"
+     *
+     * @param capture (Opcional)
+     * Define si la transacción se captura inmediatamente.
+     *
+     * - true  → Autorización + captura inmediata.
+     * - false → Solo autorización.
+     *
+     * -------------------------------------------------------
+     * @returns Promise<iPagosCSClientResponse<T>>
+     *
+     * Respuesta estandarizada:
+     *
+     * {
+     *   success: true,
+     *   data: ...
+     * }
+     *
+     * o
+     *
+     * {
+     *   success: false,
+     *   status?: number,
+     *   error: any
+     * }
+     *
+     * -------------------------------------------------------
+     * 🔐 SEGURIDAD
+     *
+     * Este método debe ejecutarse únicamente en backend.
+     * Nunca expongas secretKey en frontend.
+     *
+     * -------------------------------------------------------
+     */
+    createPaymentToken<T = any>({ transientToken, internalId, amountDetails, billTo, actionTokenTypes, actionList, capture, }: {
+        transientToken: string;
+        internalId: string;
+        amountDetails: {
+            totalAmount: number;
+            currency: string;
+        };
+        billTo: BillTo;
+        actionList?: string[];
+        actionTokenTypes?: string[];
+        capture?: boolean;
+    }): Promise<iPagosCSClientResponse<T>>;
+    /**
+     * createSession
+     * -------------------------------------------------------
+     * Genera un token de sesión (contexto) para inicializar
+     * el SDK de Flex (Microform).
+     *
+     * Esta sesión permite que el frontend:
+     *
+     * 1️⃣ Inicialice el formulario seguro de tarjeta.
+     * 2️⃣ Capture datos sensibles de tarjeta de forma segura.
+     * 3️⃣ Genere un transientToken (token de transición).
+     *
+     * 🔹 Flujo típico:
+     *
+     * Backend:
+     *   → createSession()
+     *
+     * Frontend:
+     *   → Inicializa Flex con el sessionToken
+     *   → Captura datos de tarjeta
+     *   → Genera transientToken
+     *
+     * Backend:
+     *   → Usa transientToken para crear el pago
+     *
+     * -------------------------------------------------------
+     * @param targetOrigins
+     * Dominio autorizado para inicializar Flex.
+     *
+     * Ejemplo:
+     *   "https://micomercio.com"
+     *
+     * ⚠️ Debe coincidir exactamente con el dominio donde
+     * se ejecutará el SDK de Flex.
+     *
+     * ⚠️ No usar comodines (*).
+     *
+     * -------------------------------------------------------
+     * @param allowedCardNetworks (Opcional)
+     * Define las marcas de tarjeta permitidas.
+     *
+     * Valores comunes:
+     * - "VISA"
+     * - "MASTERCARD"
+     * - "AMEX"
+     *
+     * Si no se especifica, por defecto:
+     * ["VISA", "MASTERCARD", "AMEX"]
+     *
+     * -------------------------------------------------------
+     * @param allowedPaymentTypes (Opcional)
+     * Define el tipo de método de pago permitido.
+     *
+     * Valor común:
+     * - "CARD"
+     *
+     * Si no se especifica, por defecto:
+     * ["CARD"]
+     *
+     * -------------------------------------------------------
+     * @returns Promise<iPagosCSClientResponse<T>>
+     *
+     * Respuesta exitosa:
+     *
+     * {
+     *   success: true,
+     *   data: {
+     *     id: string,
+     *     clientVersion: string,
+     *     ...
+     *   }
+     * }
+     *
+     * El ID retornado se usa en el frontend para
+     * inicializar Flex.
+     *
+     * -------------------------------------------------------
+     * 🔐 SEGURIDAD
+     *
+     * Este método debe ejecutarse únicamente en backend.
+     * Nunca expongas secretKey ni firmes requests desde frontend.
+     *
+     * El sessionToken tiene vigencia limitada.
+     *
+     * -------------------------------------------------------
+     * 🧠 Buenas Prácticas
+     *
+     * - Generar sesión por cada intento de pago.
+     * - No reutilizar sesiones antiguas.
+     * - Validar que targetOrigins coincida con tu dominio real.
+     *
+     * -------------------------------------------------------
+     */
+    createSession<T = any>({ targetOrigins, allowedCardNetworks, allowedPaymentTypes }: {
+        targetOrigins: string;
+        allowedCardNetworks?: string[];
+        allowedPaymentTypes?: string[];
+    }): Promise<iPagosCSClientResponse<T>>;
+    /**
+     * createCharge
+     * -------------------------------------------------------
+     * Realiza un cobro utilizando un customer_id y
+     * paymentInstrument_id previamente generados mediante
+     * tokenización.
+     *
+     * Este método se utiliza cuando:
+     *
+     * 1️⃣ Ya se tokenizó una tarjeta previamente.
+     * 2️⃣ Se desea realizar cobros recurrentes.
+     * 3️⃣ Se ejecutan cargos automáticos (suscripciones).
+     * 4️⃣ Se realizan cobros manuales administrativos.
+     *
+     * 🔹 No requiere transientToken.
+     * 🔹 No requiere interacción del cliente.
+     *
+     * -------------------------------------------------------
+     * FLUJO TÍPICO:
+     *
+     * 1) Cliente ingresa tarjeta (Flex).
+     * 2) Se genera transientToken.
+     * 3) Se ejecuta createPaymentToken() con TOKEN_CREATE.
+     * 4) Se obtiene:
+     *      - customer_id
+     *      - paymentInstrument_id
+     * 5) En futuros cobros se usa createCharge().
+     *
+     * -------------------------------------------------------
+     * @param internalId
+     * Identificador único interno del comercio.
+     * Se envía como clientReferenceInformation.code.
+     *
+     * ⚠️ Debe ser único por transacción.
+     * Recomendado: UUID o ID de orden interno.
+     *
+     * -------------------------------------------------------
+     * @param amountDetails
+     * Información del monto del pago.
+     *
+     * - totalAmount: Número con máximo 2 decimales.
+     *   Ejemplo válido: 499.99
+     *
+     * - currency: Código de moneda ISO 4217 en mayúsculas.
+     *   Ejemplo: "MXN", "USD"
+     *
+     * ⚠️ Currency debe ser de 3 caracteres.
+     *
+     * -------------------------------------------------------
+     * @param customer_id
+     * Identificador del cliente generado al tokenizar.
+     *
+     * Representa al cliente almacenado en CyberSource.
+     *
+     * -------------------------------------------------------
+     * @param paymentInstrument_id
+     * Identificador del método de pago tokenizado.
+     *
+     * Representa la tarjeta tokenizada asociada al customer_id.
+     *
+     * -------------------------------------------------------
+     * @param capture (Opcional)
+     * Define si la transacción se captura inmediatamente.
+     *
+     * - true  → Autorización + captura inmediata.
+     * - false → Solo autorización (capture posterior).
+     *
+     * Por defecto: true
+     *
+     * -------------------------------------------------------
+     * @returns Promise<iPagosCSClientResponse<T>>
+     *
+     * Respuesta exitosa:
+     *
+     * {
+     *   success: true,
+     *   data: {
+     *     id: string,
+     *     status: string,
+     *     ...
+     *   }
+     * }
+     *
+     * Respuesta de error:
+     *
+     * {
+     *   success: false,
+     *   status?: number,
+     *   error: any
+     * }
+     *
+     * -------------------------------------------------------
+     * 🧠 CASOS DE USO COMUNES
+     *
+     * - Suscripciones mensuales
+     * - Membresías
+     * - Financiamiento en parcialidades
+     * - Renovaciones automáticas
+     * - Reintentos de cobro
+     *
+     * -------------------------------------------------------
+     * 🔐 SEGURIDAD
+     *
+     * Este método debe ejecutarse únicamente en backend.
+     *
+     * No expone datos sensibles de tarjeta.
+     * Utiliza únicamente identificadores tokenizados.
+     *
+     * Ideal para arquitecturas PCI SAQ-A.
+     *
+     * -------------------------------------------------------
+     */
+    createCharge<T = any>({ internalId, amountDetails, customer_id, paymentInstrument_id, capture, }: {
+        internalId: string;
+        amountDetails: {
+            totalAmount: number;
+            currency: string;
+        };
+        customer_id: string;
+        paymentInstrument_id: string;
+        capture?: boolean;
+    }): Promise<iPagosCSClientResponse<T>>;
+}