Skip to main content
Beta. @fire-spark/payments-paymentez-checkout is in beta. In Ecuador Paymentez only refunds whole transactions, and OTP, 3DS and the checkout inside a WebView are not tested against Paymentez yet. Test with a sandbox application before going live.
Paymentez is Nuvei’s platform for Latin America (Nuvei LATAM). Fire spark charges with its Payment Checkout: Fire spark creates the charge reference with the server application, your channel opens the Paymentez checkout, and Fire spark confirms the payment by reading the transaction from Paymentez.
Paymentez is not the Nuvei package. A Paymentez account has application codes and app keys; a Nuvei global REST API account has a Merchant ID, Site ID and Secret key. Confirm with Nuvei which platform your account is on.
The server app key never reaches the channel. The card is typed in the Paymentez checkout and never reaches your channel or Fire spark.

How it works

  1. The adapter asks Fire spark to prepare the charge (prepare). Fire spark calls Paymentez init_reference with the tender amount and answers the reference.
  2. Your template’s bridge opens PaymentCheckout with that reference.
  3. The customer pays. The checkout answers { transaction: { status, id, status_detail } }.
  4. The adapter asks Fire spark for the status (status). Fire spark reads the transaction from Paymentez and accepts it only if it is this attempt’s (dev_reference) and for the tender amount.
If the channel closes before step 4, the Paymentez webhook settles the tender.

Requirements

  • A Paymentez server application per environment: application code and app key. The Nuvei/Paymentez team provides them (sandbox ones start with NUVEISTG-).
  • The customer email on the order, or pass it in email: Paymentez requires it.
  • Pages served over https.

Activate it

  1. In the dashboard, create a payment with the Paymentez provider and the CARD method.
  2. In Connection Settings, fill in:
  1. Optional, per store: in Store settings set the store application_code and secret_app_key. Fire spark uses the store pair only when both are set; otherwise it uses the Connection Settings pair.
  2. In Paymentez, set the callback URL to https://<your-api-host>/api/webhooks/payments/paymentez.

Use it in the SDK

Web bridge

Load the checkout and open it from the pay button click: browsers block the popup when it opens from another callback.

React Native (kiosk and app)

Run the same checkout in a react-native-webview with an https page that loads the script, opens PaymentCheckout with the reference and sends the answer with window.ReactNativeWebView.postMessage. Turn the message into the bridge outcome: onResponse → { type: "response", response }, onClose → { type: "closed", by: "user" }. Test the WebView in sandbox before production.

Charge states

Webhooks

POST /api/webhooks/payments/paymentez settles charges the channel did not confirm. Fire spark checks the stoken (HMAC-SHA256 with the app key, or the legacy MD5), reads the transaction again from Paymentez and only applies what matches the attempt and the amount.

Refunds

Paymentez voids and refunds run on the Fire spark server. order.cancel() and order.refund() work as with any method: the device does nothing with a paid Paymentez tender and the server refunds it in the same call.
  • In Ecuador Paymentez refunds whole transactions. A partial refund fails in the ledger and is done by hand in the Paymentez dashboard.
  • A pending answer from Paymentez counts as accepted; the webhook confirms the refund.

Common errors