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

# Paymentez (Nuvei LATAM)

> Charge cards in Ecuador with the Paymentez (Nuvei LATAM) Payment Checkout and @fire-spark/payments-paymentez-checkout.

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

> [!NOTE]
>
> Paymentez is not the [Nuvei](https://firespark.cloud/docs/integrations/payments/nuvei/card.md) 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.

| | |
| - | - |
| Countries | Ecuador |
| Currencies | USD |
| Status | Available (beta) |
| Package | `@fire-spark/payments-paymentez-checkout` |

| Method | Channel | What the customer does |
| - | - | - |
| Card (`CARD`) | Web, mobile app and kiosk (WebView) | Types the card in the Paymentez checkout and, when the bank asks, the OTP or 3DS |

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

| Field | Key | Secret | Notes |
| - | - | - | - |
| Application code | `application_code` | No | Server application code |
| App key | `secret_app_key` | Yes | Signs every request and the webhook. Stays in the Fire spark API |

3. 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.
4. In Paymentez, set the callback URL to `https://<your-api-host>/api/webhooks/payments/paymentez`.

## Use it in the SDK

```bash theme={null}
pnpm add @fire-spark/payments-paymentez-checkout
```

```typescript theme={null}
import { paymentezCheckoutPayments } from "@fire-spark/payments-paymentez-checkout";
import type { PaymentezCheckoutBridge } from "@fire-spark/payments-paymentez-checkout";

order.setPaymentAdapters([
  paymentezCheckoutPayments({ bridge, language: "es" })
]);

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

### Web bridge

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

```html theme={null}
<script src="https://cdn.paymentez.com/ccapi/sdk/payment_checkout_3.0.0.min.js"></script>
```

```typescript theme={null}
declare const PaymentCheckout: any;

export const bridge: PaymentezCheckoutBridge = {
  open: input => new Promise(resolve => {
    let done = false;
    const finish = outcome => {
      if (done) return;
      done = true;
      resolve(outcome);
    };
    const checkout = new PaymentCheckout.modal({
      env_mode: input.envMode,
      onResponse: response => finish({ type: "response", response }),
      onClose: () => finish({ type: "closed", by: "user" })
    });
    input.signal.addEventListener("abort", () => {
      checkout.close();
      finish({ type: "closed", by: "system" });
    });
    checkout.open({ reference: input.reference });
  })
};
```

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

| Checkout | Tender |
| - | - |
| `success` (`status_detail` 3) | `PAID` once Fire spark confirms the transaction |
| Waiting for OTP or 3DS (`status_detail` 31, 35, 36) | `PENDING`; the SDK reads it again |
| Declined | `FAILED` with the code from the table below |
| Closed by the customer without paying | `FAILED` with `CANCELLED_BY_USER` |

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

| Spark code | Paymentez `status_detail` | What to do |
| - | - | - |
| `CARD_DECLINED` | 9, 16, 19, 33, 37 | Ask for another card or method |
| `FRAUD_SUSPECTED` | 6, 11, 12 | Ask for another method |
| `WALLET_EXPIRED` | 13, 14, 15, 20 | The checkout expired. Start again |
| `CANCELLED_BY_USER` | 17, 18 | The customer abandoned the checkout |
| `INVALID_CREDENTIALS` | HTTP 401 | Check the application code, app key and environment |
| `PROVIDER_UNAVAILABLE` | 10, HTTP 5xx | Retryable |
| `AMBIGUOUS` | No answer | Left for review; check the transaction in the Paymentez dashboard |


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