ipagos-js-sdk 1.0.0

package/dist/client.js

@@ -0,0 +1,698 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.iPagosCSClient = void 0;
+const axios_1 = __importDefault(require("axios"));
+const crypto_1 = __importDefault(require("crypto"));
+class iPagosCSClient {
+    config;
+    client;
+    constructor(config) {
+        this.config = config;
+        let baseURL = config.environment === 'sandbox'
+            ? 'https://apitest.cybersource.com'
+            : 'https://api.cybersource.com';
+        this.client = axios_1.default.create({
+            baseURL,
+            headers: {
+                'Content-Type': 'application/json',
+                'v-c-merchant-id': config.merchantId
+            }
+        });
+    }
+    handleError(err) {
+        const error = err;
+        if (error.response?.data) {
+            return {
+                success: false,
+                status: error.response.status,
+                error: error.response.data
+            };
+        }
+        return {
+            success: false,
+            error: { message: error.message }
+        };
+    }
+    /**
+     * Firma CyberSource
+     */
+    sign(method, path, body) {
+        const date = new Date().toUTCString();
+        let digest;
+        if (body) {
+            const hash = crypto_1.default
+                .createHash('sha256')
+                .update(JSON.stringify(body))
+                .digest('base64');
+            digest = `SHA-256=${hash}`;
+        }
+        const host = new URL(this.client.defaults.baseURL).host;
+        const signatureHeaders = [
+            `(request-target): ${method.toLowerCase()} ${path}`,
+            `host: ${host}`,
+            `date: ${date}`
+        ];
+        if (digest) {
+            signatureHeaders.push(`digest: ${digest}`);
+        }
+        signatureHeaders.push(`v-c-merchant-id: ${this.config.merchantId}`);
+        const signatureString = signatureHeaders.join('\n');
+        const signature = crypto_1.default
+            .createHmac('sha256', Buffer.from(this.config.secretKey, 'base64'))
+            .update(signatureString)
+            .digest('base64');
+        return {
+            date,
+            digest,
+            signature: `keyid="${this.config.keyId}", algorithm="HmacSHA256", headers="(request-target) host date${digest ? ' digest' : ''} v-c-merchant-id", signature="${signature}"`
+        };
+    }
+    /**
+     * POST CyberSource
+     */
+    async post(path, body) {
+        try {
+            const signed = this.sign('POST', path, body);
+            const headers = {
+                Date: signed.date,
+                Signature: signed.signature
+            };
+            if (signed.digest) {
+                headers.Digest = signed.digest;
+            }
+            const response = await this.client.post(path, body, { headers });
+            return {
+                success: true,
+                data: response.data
+            };
+        }
+        catch (err) {
+            return this.handleError(err);
+        }
+    }
+    /**
+     * GET CyberSource
+     */
+    async get(path) {
+        try {
+            const signed = this.sign('GET', path);
+            const headers = {
+                Date: signed.date,
+                Signature: signed.signature
+            };
+            const response = await this.client.get(path, { headers });
+            return {
+                success: true,
+                data: response.data
+            };
+        }
+        catch (err) {
+            return this.handleError(err);
+        }
+    }
+    /**
+     * 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.
+     *
+     * -------------------------------------------------------
+     */
+    async getPaymentDetails(transientToken) {
+        try {
+            return await this.get(`/up/v1/payment-details/${transientToken}`);
+        }
+        catch (err) {
+            return this.handleError(err);
+        }
+    }
+    /**
+   * 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.
+   *
+   * -------------------------------------------------------
+   */
+    async refundsPayment({ paymentId, amountDetails }) {
+        try {
+            const payload = {
+                clientReferenceInformation: {
+                    code: `refund_${paymentId}_${Date.now()}`
+                },
+                orderInformation: {
+                    amountDetails
+                }
+            };
+            return await this.post(`/pts/v2/payments/${paymentId}/refunds`, payload);
+        }
+        catch (err) {
+            return this.handleError(err);
+        }
+    }
+    /**
+     * 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.
+     *
+     * -------------------------------------------------------
+     */
+    async createPaymentToken({ transientToken, internalId, amountDetails, billTo, actionTokenTypes = ["customer", "paymentInstrument"], actionList = ["TOKEN_CREATE"], capture = true, }) {
+        try {
+            const payload = {
+                clientReferenceInformation: {
+                    code: internalId,
+                },
+                processingInformation: {
+                    capture,
+                    actionList,
+                    actionTokenTypes
+                },
+                paymentInformation: {
+                    tokenizedCard: {
+                        transientTokenJwt: transientToken
+                    }
+                },
+                tokenInformation: {
+                    transientTokenJwt: transientToken,
+                },
+                orderInformation: {
+                    amountDetails,
+                    billTo,
+                },
+            };
+            return await this.post('/pts/v2/payments', payload);
+        }
+        catch (err) {
+            return this.handleError(err);
+        }
+    }
+    /**
+     * 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.
+     *
+     * -------------------------------------------------------
+     */
+    async createSession({ targetOrigins, allowedCardNetworks = [
+        "VISA",
+        "MASTERCARD",
+        "AMEX"
+    ], allowedPaymentTypes = ["CARD"] }) {
+        try {
+            const payload = {
+                "clientVersion": "v2",
+                "targetOrigins": [
+                    targetOrigins
+                ],
+                allowedCardNetworks,
+                allowedPaymentTypes,
+                "transientTokenResponseOptions": {
+                    "includeCardPrefix": false
+                }
+            };
+            return await this.post('/microform/v2/sessions', payload);
+        }
+        catch (err) {
+            return this.handleError(err);
+        }
+    }
+    /**
+     * 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.
+     *
+     * -------------------------------------------------------
+     */
+    async createCharge({ internalId, amountDetails, customer_id, paymentInstrument_id, capture = true, }) {
+        try {
+            const payload = {
+                clientReferenceInformation: {
+                    code: internalId,
+                },
+                processingInformation: {
+                    capture,
+                },
+                paymentInformation: {
+                    customer: {
+                        id: customer_id,
+                    },
+                    paymentInstrument: {
+                        id: paymentInstrument_id,
+                    },
+                },
+                orderInformation: {
+                    amountDetails
+                },
+            };
+            return await this.post('/pts/v2/payments', payload);
+        }
+        catch (err) {
+            return this.handleError(err);
+        }
+    }
+}
+exports.iPagosCSClient = iPagosCSClient;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './client';
+export * from './types';

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./client"), exports);
+__exportStar(require("./types"), exports);