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

> Charge cards on the web with Nuvei's own card form, verified on the server, with @fire-spark/payments-nuvei-card.

> [!WARNING]
>
> **Beta.** `@fire-spark/payments-nuvei-card` is in beta since SDK 0.15.0. It works on the web only, Nuvei's status notifications (DMN) are not used, and Nuvei's detailed error codes are not mapped yet. Test in sandbox before going live.

Nuvei (nuvei.com) is a global card processor. Fire spark opens a Nuvei payment session on the server, your web template shows **Nuvei's own card form** (Web SDK with Nuvei Fields, or Simply Connect), and Fire spark then asks Nuvei for the result before marking the tender paid. The card never reaches your channel's code or Fire spark, and the Nuvei secret key never leaves the Fire spark API.

| | |
| - | - |
| Countries | Ecuador by default (configurable billing country) |
| Currencies | The tender currency |
| Status | Available (beta) |
| Package | `@fire-spark/payments-nuvei-card` |

| Method | Channel | What the customer does |
| - | - | - |
| Card (`CARD`) | Web | Types the card in Nuvei's form and completes 3-D Secure when Nuvei asks for it |

## How it works

1. The adapter asks Fire spark to open a Nuvei session (`open_order`). Fire spark calls Nuvei `/openOrder` with the tender amount and currency, the attempt reference as `clientUniqueId`, and the billing address of the order customer, signed with your secret key. It answers the session token.
2. Your template's **bridge** shows Nuvei's card form with that session. Nuvei charges the card and runs 3-D Secure itself.
3. When the form finishes, the adapter asks Fire spark for the status (`status`). Fire spark calls Nuvei `/getPaymentStatus` and accepts the payment only if it belongs to this attempt and the amount and currency match the tender.

Nuvei warns that the browser result can't be trusted, so the bridge only reports that the form finished. The tender is paid only by what Nuvei answers to Fire spark.

## Requirements

* A Nuvei merchant account with its merchant ID, merchant site ID, and secret key, for each environment (sandbox and production are separate).
* A web template that loads Nuvei's Web SDK or Simply Connect from Nuvei's CDN. Kiosks and mobile apps are not supported yet.
* The order customer's full billing address (name, email, address, city, country). Nuvei uses it for address verification (AVS) and risk checks.

> [!NOTE]
>
> In Ecuador, Nuvei also runs **Nuvei LATAM** (formerly Paymentez), a different platform with a different API. This package uses Nuvei's global REST API. Confirm with Nuvei which platform your merchant account is on before you start.

## Activate it

1. In the dashboard, open your merchant, go to **Payments**, and create a payment with the provider **Nuvei** and the method `CARD`.
2. In **Connection Settings**, fill in:

| Field | Key | Secret | Notes |
| - | - | - | - |
| Merchant ID | `nuvei_merchant_id` | No | Your Nuvei merchant ID |
| Merchant site ID | `nuvei_merchant_site_id` | No | Your Nuvei merchant site ID. Can be overridden per store |
| Secret key | `secret_key` | Yes | Signs every Nuvei request. Stays in the Fire spark API; never sent to channels |
| Country | `country` | No | ISO-2 billing country when the customer has none. Default `EC` |

3. Optional: set `provider_environment` to force `sandbox` or `production`. Without it, the environment follows the merchant's.

### Per store

Each store can override the merchant site ID under **Store settings** in the payment form. A store that leaves it empty uses the Connection Settings one.

| Field | When |
| - | - |
| Merchant site ID (`nuvei_merchant_site_id`) | Each store with its own Nuvei merchant site |

Fire spark opens sessions, reads statuses, and reverses charges with the settings of the order's store.

## Use it in the 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 // your template's NuveiCheckoutBridge, see below
  })
]);

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

`payIntent({ payment })` places one real tender. To split Nuvei with another method, call `order.setTenders` with an allocation and then `payIntent()`. See [Use payments in the SDK](https://firespark.cloud/docs/guides/payments/use-payments-in-the-sdk.md).

### Options

| Option | Required | Description |
| - | - | - |
| `bridge` | Yes | Shows Nuvei's card form with the session and reports when it finishes (`NuveiCheckoutBridge`) |

### The bridge

The bridge is your web template's code. The package defines its shape (`NuveiCheckoutBridge`), not its UI.

`pay(input)` receives the session Fire spark opened: the session token, merchant ID, merchant site ID, Web SDK `env` (`int` for sandbox, `prod` for production), amount, currency, country, and customer email, plus a `signal` that aborts when the attempt is cancelled or times out. It resolves with:

| Outcome | When |
| - | - |
| `{ type: "completed", card?: { brand?, last4? } }` | Nuvei's form finished (paid, declined, or anything else). `card` is only for display |
| `{ type: "cancelled" }` | The customer closed the form, or `signal` aborted |

Resolving `completed` doesn't mark the tender paid: the adapter always asks Fire spark for the status.

> [!NOTE]
>
> The code below is an **example of your template's own code**, not part of the package. Check the input field names against the `NuveiCheckoutBridge` type, and adapt the form to your UI and to Nuvei's Web SDK documentation.

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

// Nuvei's Web SDK, loaded from Nuvei's CDN in your page.
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);
            // Never trust this result: Fire spark checks it with Nuvei.
            resolve({ type: "completed" });
          }
        );
      });
      onCloseClick(() => resolve({ type: "cancelled" }));
    })
};
```

## Amounts

Fire spark sends Nuvei the tender amount (two decimals) and currency, from the server. The device never sends an amount.

## Storefront endpoints

The adapter calls these through the payment server operations. They use the storefront session.

| Endpoint | What it does |
| - | - |
| `POST /api/storefront/v1/payments/{payment_id}/operations/open_order` | Opens a Nuvei session for the current payment attempt. Returns `session_token`, `merchant_id`, `merchant_site_id`, `env`, `amount`, `currency`, `country`, and `email`. The amount comes from the tender, never from the request |
| `POST /api/storefront/v1/payments/{payment_id}/operations/status` | Reads the session status from Nuvei, checks it belongs to this attempt with the tender amount and currency, and returns the outcome (`PAID`, `FAILED`, or `PENDING`) |

## What the customer sees

Nuvei's card form inside your page, and Nuvei's 3-D Secure challenge when the issuer asks for one. A paid tender records `details` with the card brand, last 4 digits, and authorization code. There is no voucher.

## Timeouts and unknown results

* If Nuvei does not answer within 30 seconds, the operation fails with `AMBIGUOUS`. Check the transaction in the Nuvei control panel.
* A session without a transaction yet stays `PENDING`, and the adapter reads the status again.
* Fire spark does not use Nuvei's DMN notifications yet: the adapter reads the status itself.

## Fraud and risk

Nuvei's risk engine runs on every payment:

* Its rules **accept**, **reject**, or **flag** a payment. A flagged payment is still charged: review it in the Nuvei control panel.
* **Dynamic 3D** decides when to ask for 3-D Secure; Nuvei's form handles the challenge.
* CVV and address verification (AVS) results come from the issuer. AVS needs the full, real billing address, which Fire spark sends from the order customer.

## Refunds

Fire spark reverses a paid Nuvei charge on the server when you call `order.cancel()` or `order.refund()`, with the payment's secret key. The device does nothing: the adapter reports the reversal as `server`.

* **Cancel** voids the transaction. If Nuvei refuses the void (the charge already went to the acquirer in the daily batch, or the acquirer has no void), Fire spark refunds the full amount instead.
* **Refund** can be **partial**. All refunds together can't exceed the original amount, in the same currency.
* **Idempotent.** Fire spark sends the ledger idempotency key as Nuvei's `clientRequestId`.
* An attempt that was never charged is just discarded.

A failed reversal stays in the order's payment ledger with Nuvei's reason, for an operator to finish.

## Common errors

| Spark code | Nuvei cause | What to do |
| - | - | - |
| `CARD_DECLINED` | `transactionStatus` `DECLINED` | Ask for another card or method |
| `CANCELLED_BY_USER` | The customer closed the form | Offer the method again |
| `AMBIGUOUS` | No answer from Nuvei | Check the transaction in the Nuvei control panel |
| `PROVIDER_UNAVAILABLE` | HTTP 5xx, 429 | Try again with a new attempt |

A `transactionStatus` of `ERROR` fails the tender with Nuvei's reason. A status for another attempt, or with another amount or currency, is rejected and never marks the tender paid. Nuvei's detailed gateway codes (`gwErrorCode`, `gwExtendedErrorCode`) are recorded but not mapped yet. See [Payment errors](https://firespark.cloud/docs/guides/payments/errors.md).

## Test in sandbox

Set `provider_environment` to `sandbox` (or use a sandbox merchant) with your Nuvei sandbox credentials. Use the cards on Nuvei's test cards page to try approvals, declines, and 3-D Secure challenges.

## Compatibility

| `@fire-spark/payments-nuvei-card` | Provider | `@fire-spark/payments` |
| - | - | - |
| 0.15.0 (beta) | Nuvei REST API 1.0 | Same version |


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