Skip to main content
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.

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.
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:
  1. 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. Fire spark opens sessions, reads statuses, and reverses charges with the settings of the order’s store.

Use it in the SDK

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.

Options

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: Resolving completed doesn’t mark the tender paid: the adapter always asks Fire spark for the status.
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.

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.

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

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.

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