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 back-end)

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

🏗 Arquitectura Recomendada

Flujo estándar:

1. Backend → createSession()
2. Frontend → Inicializa Flex con sessionToken
3. Frontend → Genera transientToken
4. Backend → getPaymentDetails() (opcional)
5. Backend → createPaymentToken() o createCharge()
6. Backend → refundsPayment() (si aplica)

🔑 Configuración

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 necesario para inicializar Flex en frontend.

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

• Genera sesión temporal.
• Permite obtener transientToken en frontend.
• No realiza cobros.

2️⃣ getPaymentDetails(transientToken)

Obtiene información de tarjeta asociada al transientToken.

await client.getPaymentDetails(transientToken);

• No realiza cobro.
• Permite validaciones previas.
• Útil para antifraude.

3️⃣ createPaymentToken()

Procesa pago usando transientToken.

await client.createPaymentToken({
  transientToken,
  internalId: "ORDER_123",
  amountDetails: {
    totalAmount: 100.00,
    currency: "MXN"
  },
  billTo: {...}
});

Modos de uso:

Escenario actionList actionTokenTypes

Solo cobrar [] []

Cobrar + tokenizar ["TOKEN_CREATE"] ["customer","paymentInstrument"]

Solo tokenizar capture = false TOKEN_CREATE

4️⃣ createCharge()

Realiza cobro usando token previamente generado.

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

5️⃣ refundsPayment()

Realiza reembolso total o parcial.

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

⚠️ El monto no puede exceder el capturado.

⚠️ La moneda debe coincidir con la original.

Dependencias

• axios : "^1.13.5",
• crypto : "^1.0.1"

🔐 Seguridad

• Nunca exponer key, secret y mid en frontend.
• Ejecutar SDK únicamente en backend.
• No almacenar transientToken.
• Implementar idempotencia para evitar duplicados.

📊 Buenas Prácticas

• Usar UUID o un numero + prefijo o sufijo como internalId
• Registrar todos los paymentId y refundId.
• Implementar logging estructurado.
• Manejar retries controlados.

🏦 Casos de Uso

• Ecommerce
• SaaS
• Suscripciones
• Membresías
• Marketplaces
• Fintech

🚀 Producción

Antes de pasar a producción:

• Validar flujo completo en sandbox.
• Confirmar dominios targetOrigins.
• Validar webhooks.
• Implementar monitoreo.

🤝 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.

• Email: [email protected]

💡 iPagos

Procesamiento inteligente de pagos para tu ecosistema digital.