> ## Documentation Index
> Fetch the complete documentation index at: https://firespark.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Nuvei

> Cobra tarjetas en la web con el formulario de tarjeta de Nuvei, verificado en el servidor, con @fire-spark/payments-nuvei-card.

> [!WARNING]
>
> **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.

| | |
| - | - |
| Países | Ecuador por defecto (país de facturación configurable) |
| Monedas | La moneda del tender |
| Estado | Disponible (beta) |
| Paquete | `@fire-spark/payments-nuvei-card` |

| Método | Canal | Qué hace el cliente |
| - | - | - |
| Tarjeta (`CARD`) | Web | Escribe la tarjeta en el formulario de Nuvei y completa 3-D Secure cuando Nuvei lo pide |

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

> [!NOTE]
>
> 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:

| Campo | Clave | Secreta | Notas |
| - | - | - | - |
| Merchant ID | `nuvei_merchant_id` | No | Tu merchant ID de Nuvei |
| Merchant site ID | `nuvei_merchant_site_id` | No | Tu merchant site ID de Nuvei. Se puede cambiar por tienda |
| Clave secreta | `secret_key` | Sí | Firma cada llamada a Nuvei. Se queda en la API de Fire spark; nunca se envía a los canales |
| País | `country` | No | País de facturación ISO-2 cuando el cliente no tiene uno. Por defecto `EC` |

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

| Campo | Cuándo |
| - | - |
| Merchant site ID (`nuvei_merchant_site_id`) | Cada tienda con su propio merchant site en Nuvei |

Fire spark abre sesiones, lee estados y reversa cobros con la configuración de la tienda de la orden.

## Úsalo en el SDK

```bash theme={null}
pnpm add @fire-spark/payments-nuvei-card
```

```typescript theme={null}
import { nuveiCardPayments } from "@fire-spark/payments-nuvei-card";

order.setPaymentAdapters([
  nuveiCardPayments({
    bridge // el NuveiCheckoutBridge de tu plantilla, ver abajo
  })
]);

const result = await order.payIntent({ payment: nuveiPayment });
```

`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](https://firespark.cloud/docs/es/guides/payments/use-payments-in-the-sdk.md).

### Opciones

| Opción | Requerida | Descripción |
| - | - | - |
| `bridge` | Sí | Muestra el formulario de tarjeta de Nuvei con la sesión y avisa cuando termina (`NuveiCheckoutBridge`) |

### 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:

| Resultado | Cuándo |
| - | - |
| `{ type: "completed", card?: { brand?, last4? } }` | El formulario de Nuvei terminó (pagado, rechazado o cualquier otro resultado). `card` es solo para mostrar |
| `{ type: "cancelled" }` | El cliente cerró el formulario, o se abortó `signal` |

Resolver `completed` no marca el tender como pagado: el adaptador siempre le pide el estado a Fire spark.

> [!NOTE]
>
> 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.

```typescript theme={null}
import type { NuveiCheckoutBridge } from "@fire-spark/payments-nuvei-card";

// Web SDK de Nuvei, cargado desde el CDN de Nuvei en tu página.
declare const SafeCharge: any;

export const bridge: NuveiCheckoutBridge = {
  pay: input =>
    new Promise(resolve => {
      const sfc = SafeCharge({
        env: input.env,
        merchantId: input.merchantId,
        merchantSiteId: input.merchantSiteId,
        sessionToken: input.sessionToken
      });
      const card = sfc.fields().create("card", {});
      card.attach("#nuvei-card");

      const onAbort = () => resolve({ type: "cancelled" });
      input.signal.addEventListener("abort", onAbort, { once: true });

      onPayClick(() => {
        sfc.createPayment(
          {
            sessionToken: input.sessionToken,
            cardHolderName: readCardholderName(),
            paymentOption: card,
            billingAddress: { email: input.email, country: input.country }
          },
          () => {
            input.signal.removeEventListener("abort", onAbort);
            // Nunca confíes en este resultado: Fire spark lo verifica con Nuvei.
            resolve({ type: "completed" });
          }
        );
      });
      onCloseClick(() => resolve({ type: "cancelled" }));
    })
};
```

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

| Endpoint | Qué hace |
| - | - |
| `POST /api/storefront/v1/payments/{payment_id}/operations/open_order` | Abre una sesión de Nuvei para el intento de pago actual. Devuelve `session_token`, `merchant_id`, `merchant_site_id`, `env`, `amount`, `currency`, `country` y `email`. El monto sale del tender, nunca de la petición |
| `POST /api/storefront/v1/payments/{payment_id}/operations/status` | Lee el estado de la sesión en Nuvei, verifica que sea de este intento con el monto y la moneda del tender y devuelve el resultado (`PAID`, `FAILED` o `PENDING`) |

## 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

| Código Spark | Causa en Nuvei | Qué hacer |
| - | - | - |
| `CARD_DECLINED` | `transactionStatus` `DECLINED` | Pide otra tarjeta u otro método |
| `CANCELLED_BY_USER` | El cliente cerró el formulario | Ofrece el método de nuevo |
| `AMBIGUOUS` | Nuvei no respondió | Revisa la transacción en el panel de control de Nuvei |
| `PROVIDER_UNAVAILABLE` | HTTP 5xx, 429 | Intenta de nuevo con un intento nuevo |

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](https://firespark.cloud/docs/es/guides/payments/errors.md).

## 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

| `@fire-spark/payments-nuvei-card` | Proveedor | `@fire-spark/payments` |
| - | - | - |
| 0.15.0 (beta) | Nuvei REST API 1.0 | Misma versión |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.