Integración del Botón de Pago Nuvei: Cobros Seguros en Ecuador

Integrar pasarelas de pago y cobros con tarjeta en Ecuador ha sido tradicionalmente un desafío de desarrollo complejo. Las regulaciones de la Superintendencia de Bancos y los requerimientos de procesadores locales como Medianet o Datafast imponen altos estándares de cumplimiento. Sin embargo, Nuvei (con su infraestructura de tecnología robusta heredada de Kushki en la región) ha revolucionado esto ofreciendo una solución moderna, ágil y de alta disponibilidad.

¿Qué es el Botón de Pago Nuvei y cómo funciona?

Para evitar violar el cumplimiento normativo estricto de **PCI-DSS** (que prohíbe terminantemente almacenar, procesar o transmitir números de tarjetas de crédito en servidores que no estén certificados), Nuvei utiliza un flujo de trabajo basado en **Tokenización por Campos Alojados**:

• El frontend del cliente carga campos de entrada seguros controlados directamente por los servidores de Nuvei mediante su script JS.
• Cuando el usuario envía el pago, los datos de la tarjeta viajan directamente a Nuvei, que devuelve un token temporal de un solo uso (token).
• El cliente envía este token a nuestro backend, el cual realiza una petición HTTP segura de servidor a servidor (Server-to-Server) para debitar el monto real, manteniendo los datos sensibles completamente fuera de nuestro alcance.

Paso 1: Inicializar la Interfaz con Nuvei Checkout

Para iniciar el proceso de checkout en nuestro cliente, importamos la librería de Nuvei/Kushki y creamos el formulario seguro. Esto inyecta iFrames protegidos para el número de tarjeta, CVV y fecha de expiración.

<!-- Contenedor del Formulario de Pago Seguro de Nuvei -->
<div id="nuvei-checkout-container"></div>

<!-- Importar Script oficial de Nuvei/Kushki -->
<script src="https://cdn.kushkipagos.com/kushki.min.js"></script>
<script>
  const kushki = new Kushki({
    merchantId: 'TU_PUBLIC_MERCHANT_ID', // Tu clave pública provista por Nuvei
    inTestEnvironment: true // Modo sandbox/UAT en desarrollo
  });

  // Ejemplo de solicitud de tokenización al hacer submit
  kushki.requestToken({
    amount: '29.99',
    currency: 'USD'
  }, (response) => {
    if (response.token) {
      // Transmitir token generado de manera segura al backend
      enviarTokenAlServidor(response.token);
    } else {
      alert('Fallo en la autenticación de la tarjeta: ' + response.error.message);
    }
  });
</script>

Paso 2: Procesamiento del Cargo en el Backend (Node.js)

Una vez que nuestro backend recibe el token, realizamos una solicitud POST autenticada a la API de Nuvei utilizando la clave privada de comercio (Private Merchant ID). Es aquí donde se define el desglose de impuestos requerido en Ecuador (como el cálculo del IVA 15% o 0% e ICE).

import axios from 'axios';

interface PagoNuveiInput {
  token: string;
  monto: number;
  correoCliente: string;
}

export async function procesarCobroNuvei({ token, monto, correoCliente }: PagoNuveiInput) {
  try {
    // Endpoint de sandbox / pruebas (Kushki LATAM API)
    const urlNuvei = 'https://api-uat.kushkipagos.com/card/v1/charges';

    const response = await axios.post(
      urlNuvei,
      {
        token: token,
        amount: {
          subtotalIva0: monto, // En Ecuador, suscripciones digitales operan con IVA 0% o exento en SaaS
          iva: 0,
          subtotalIva: 0,
          ice: 0,
          currency: 'USD' // Moneda oficial en Ecuador
        },
        metadata: {
          description: 'Suscripción Premium Factuplan',
          email: correoCliente
        }
      },
      {
        headers: {
          'Private-Merchant-Id': process.env.NUVEI_PRIVATE_KEY, // Credencial de producción privada resguardada en variables de entorno
          'Content-Type': 'application/json'
        }
      }
    );

    if (response.data.status === 'approved') {
      return { success: true, transaccionId: response.data.ticketNumber };
    }
    return { success: false, error: response.data.error.message };
  } catch (error: any) {
    console.error('Error debitando en Nuvei:', error.response?.data || error.message);
    return { success: false, error: error.message };
  }
}

Doble Autenticación obligatoria: 3D Secure 2.0

Para evitar fraudes de tarjeta y contracargos (chargebacks) en comercios electrónicos ecuatorianos, Nuvei integra automáticamente **3D Secure 2.0 (3DS)**. Durante la tokenización, si el banco emisor local (por ejemplo, Banco Pichincha, Banco Guayaquil o PacifiCard) lo requiere, el usuario completará un paso de validación multifactor (como un código OTP enviado por SMS), garantizando una transacción 100% segura para ambas partes.

Caso de Estudio de Producción: Mi Experiencia en Tenvia (SaaS Multi-Tenant)

Durante el desarrollo de la aplicación móvil para Tenvia —un robusto ecosistema ecommerce tipo SaaS operando con arquitectura multi-tenant— nos enfrentamos a la implementación técnica de permitir a los usuarios vincular tarjetas bancarias para efectuar pagos recurrentes y suscripciones. En nuestra primera versión (v1), inyectamos un WebView seguro que desplegaba el formulario nativo de Nuvei, encargándose de capturar y tokenizar el plástico, y retornando el token de usuario correspondiente para validar y asociar la tarjeta. No obstante, nos topamos con dos retos sumamente interesantes y formativos en producción:

• El Bloqueo de Tarjetas por Anti-Fraude: Durante la etapa álgida de pruebas, de forma involuntaria dejé mi correo electrónico personal hardcodeado en los flujos de pruebas de la pasarela. El sistema inteligente de detección de fraudes de Nuvei identificó este patrón repetitivo y comenzó a rechazar y marcar en cadena como sospechosas todas las tarjetas de pruebas subsiguientes. Para complicar más las cosas, Nuvei ofrece un panel administrativo (Dashboard) donde se auditan estos bloqueos; yo no tenía accesos directos al panel pero el cliente sí. Nos percatamos del problema de forma tardía, lo que nos obligó a realizar ajustes y despliegues inmediatos en producción desde el lado web para corregir la fuga de correo.
• La Fricción de la Sumatoria de Decimales: También lidiamos con un error sutil en la matemática de cálculo. Al estructurar el objeto de cargo, el desglose detallado de valores (subtotales de IVA 0%, IVA, ICE, etc.) difería por apenas un par de decimales en comparación con el total absoluto a debitar debido al redondeo en nuestro backend. Nuvei rechaza en el acto cualquier transacción si la suma exacta del desglose de impuestos no coincide a la centésima con el total general, bloqueando la ejecución del cobro recurrente. Tuvimos que reestructurar la lógica del redondeo para asegurar un acoplamiento perfecto de decimales.