npm package: @ipagos.lat/ipagos-js-sdk
Description: SDK profesional de alto nivel para la integración con iPagos en JavaScript/TypeScript, optimizado para Node.js 18+.
Author: Integraciones iPagos
Latest version: 1.6.0

﻿# iPagos TS/JS SDK

![Version](https://img.shields.io/badge/version-1.6.0-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)
![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)
![Language](https://img.shields.io/badge/language-TypeScript-blue.svg)

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](#-instalación)
- [📌 Descripción General](#-descripción-general)
- [🏗 Arquitectura Recomendada](#-arquitectura-recomendada)
- [🔑 Configuración](#-configuración)
- [📘 Métodos Disponibles](#-métodos-disponibles)
  - [1️⃣ createSession()](#1️⃣-createsession)
  - [2️⃣ getPaymentDetails()](#2️⃣-getpaymentdetails)
  - [3️⃣ createPaymentToken()](#3️⃣-createpaymenttoken)
  - [4️⃣ createCharge()](#4️⃣-createcharge)
  - [5️⃣ refundsPayment()](#5️⃣-refundspayment)
- [📦 Dependencias](#-dependencias)
- [🔐 Seguridad](#-seguridad)
- [📊 Buenas Prácticas](#-buenas-prácticas)
- [🏦 Casos de Uso](#-casos-de-uso)
- [🚀 Puesta en Producción](#-puesta-en-producción)

---

## 🚀 Instalación

Instala el SDK utilizando tu gestor de paquetes favorito:

```bash
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.

```ts
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.

```ts
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`.

```ts
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`.

```ts
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).

```ts
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.

```ts
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.

---

<div align="center">
  <h3>iPagos</h3>
  <p><i>Infraestructura inteligente de pagos.</i></p>
  <p>📧 <a href="mailto:integraciones@ipagos.lat">integraciones@ipagos.lat</a></p>
</div>