Saltar al contenido principal
Beta. @fire-spark/payments-nuvei-card está en beta desde el SDK 0.15.0. Funciona solo en la web, no usa las notificaciones de estado de Nuvei (DMN) y todavía no mapea los códigos de error detallados de Nuvei. Prueba en sandbox antes de salir a producción.
Nuvei (nuvei.com) es un procesador de tarjetas global. Fire spark abre una sesión de pago de Nuvei en el servidor, tu plantilla web muestra el formulario de tarjeta de Nuvei (Web SDK con Nuvei Fields, o Simply Connect) y después Fire spark le pregunta a Nuvei el resultado antes de marcar el tender como pagado. La tarjeta nunca llega al código de tu canal ni a Fire spark, y la clave secreta de Nuvei nunca sale de la API de Fire spark.

Cómo funciona

  1. El adaptador le pide a Fire spark abrir una sesión de Nuvei (open_order). Fire spark llama a /openOrder de Nuvei con el monto y la moneda del tender, la referencia del intento como clientUniqueId y la dirección de facturación del cliente de la orden, firmado con tu clave secreta. Responde el token de sesión.
  2. El bridge de tu plantilla muestra el formulario de tarjeta de Nuvei con esa sesión. Nuvei cobra la tarjeta y hace 3-D Secure por su cuenta.
  3. Cuando el formulario termina, el adaptador le pide a Fire spark el estado (status). Fire spark llama a /getPaymentStatus de Nuvei y acepta el pago solo si es de este intento y el monto y la moneda coinciden con el tender.
Nuvei advierte que el resultado del navegador no es confiable, así que el bridge solo avisa que el formulario terminó. El tender se paga solo con lo que Nuvei le responde a Fire spark.

Requisitos

  • Una cuenta de comercio en Nuvei con su merchant ID, merchant site ID y clave secreta, para cada entorno (sandbox y producción son distintos).
  • Una plantilla web que cargue el Web SDK o Simply Connect desde el CDN de Nuvei. Kioscos y apps móviles todavía no están soportados.
  • La dirección de facturación completa del cliente de la orden (nombre, email, dirección, ciudad, país). Nuvei la usa para la verificación de dirección (AVS) y los controles de riesgo.
En Ecuador, Nuvei también opera Nuvei LATAM (antes Paymentez), otra plataforma con otra API. Este paquete usa la REST API global de Nuvei. Confirma con Nuvei en qué plataforma está tu cuenta antes de empezar.

Actívalo

  1. En el dashboard, abre tu merchant, ve a Payments y crea un pago con el proveedor Nuvei y el método CARD.
  2. En Connection Settings, completa:
  1. Opcional: configura provider_environment para forzar sandbox o production. Sin él, el entorno sigue el del merchant.

Por tienda

Cada tienda puede cambiar el merchant site ID en Store settings del formulario del pago. Una tienda que lo deja vacío usa el de Connection Settings. Fire spark abre sesiones, lee estados y reversa cobros con la configuración de la tienda de la orden.

Úsalo en el SDK

payIntent({ payment }) registra un tender real. Para dividir Nuvei con otro método, llama a order.setTenders con una asignación y después a payIntent(). Ver Usar pagos en el SDK.

Opciones

El bridge

El bridge es código de tu plantilla web. El paquete define su forma (NuveiCheckoutBridge), no su UI. pay(input) recibe la sesión que abrió Fire spark: el token de sesión, merchant ID, merchant site ID, env del Web SDK (int en sandbox, prod en producción), monto, moneda, país y email del cliente, más un signal que se aborta cuando el intento se cancela o vence. Resuelve con: Resolver completed no marca el tender como pagado: el adaptador siempre le pide el estado a Fire spark.
El código de abajo es un ejemplo del código de tu plantilla, no parte del paquete. Revisa los nombres de los campos de input contra el tipo NuveiCheckoutBridge y adapta el formulario a tu UI y a la documentación del Web SDK de Nuvei.

Montos

Fire spark le envía a Nuvei el monto del tender (dos decimales) y su moneda, desde el servidor. El dispositivo nunca envía un monto.

Endpoints de storefront

El adaptador los llama a través de las operaciones de servidor del pago. Usan la sesión de storefront.

Qué ve el cliente

El formulario de tarjeta de Nuvei dentro de tu página, y el reto de 3-D Secure de Nuvei cuando el emisor lo pide. Un tender pagado registra details con la marca, los últimos 4 dígitos y el código de autorización. No hay voucher.

Tiempos de espera y resultados desconocidos

  • Si Nuvei no responde en 30 segundos, la operación falla con AMBIGUOUS. Revisa la transacción en el panel de control de Nuvei.
  • Una sesión sin transacción todavía queda PENDING y el adaptador vuelve a leer el estado.
  • Fire spark todavía no usa las notificaciones DMN de Nuvei: el adaptador lee el estado por su cuenta.

Fraude y riesgo

El motor de riesgo de Nuvei corre en cada pago:
  • Sus reglas aceptan, rechazan o marcan (flag) un pago. Un pago marcado igual se cobra: revísalo en el panel de control de Nuvei.
  • Dynamic 3D decide cuándo pedir 3-D Secure; el formulario de Nuvei maneja el reto.
  • Los resultados de CVV y de verificación de dirección (AVS) vienen del emisor. AVS necesita la dirección de facturación completa y real, que Fire spark envía desde el cliente de la orden.

Reembolsos

Fire spark reversa un cobro pagado de Nuvei en el servidor cuando llamas a order.cancel() o order.refund(), con la clave secreta del pago. El dispositivo no hace nada: el adaptador reporta el reverso como server.
  • Cancelar anula (void) la transacción. Si Nuvei rechaza la anulación (el cobro ya pasó al adquirente en el lote diario, o el adquirente no tiene anulación), Fire spark devuelve el monto total.
  • Reembolsar puede ser parcial. La suma de los reembolsos no puede superar el monto original, en la misma moneda.
  • Idempotente. Fire spark envía la llave de idempotencia del ledger como clientRequestId de Nuvei.
  • Un intento que nunca se cobró solo se descarta.
Un reverso fallido queda en el ledger de pagos de la orden con el motivo de Nuvei, para que un operador lo termine.

Errores comunes

Un transactionStatus ERROR falla el tender con el motivo de Nuvei. Un estado de otro intento, o con otro monto o moneda, se rechaza y nunca marca el tender como pagado. Los códigos detallados del gateway de Nuvei (gwErrorCode, gwExtendedErrorCode) se guardan pero todavía no se mapean. Ver Errores de pago.

Prueba en sandbox

Configura provider_environment en sandbox (o usa un merchant de sandbox) con tus credenciales de sandbox de Nuvei. Usa las tarjetas de la página de tarjetas de prueba de Nuvei para probar aprobaciones, rechazos y retos de 3-D Secure.

Compatibilidad