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

> Cobra tarjetas en Ecuador con el Payment Checkout de Paymentez (Nuvei LATAM) y @fire-spark/payments-paymentez-checkout.

> [!WARNING]
>
> **Beta.** `@fire-spark/payments-paymentez-checkout` está en beta. En Ecuador Paymentez solo reembolsa transacciones completas, y el OTP, el 3DS y el checkout dentro de un WebView todavía no se probaron contra Paymentez. Prueba con una aplicación de sandbox antes de salir a producción.

Paymentez es la plataforma de Nuvei para Latinoamérica (Nuvei LATAM). Fire spark cobra con su **Payment Checkout**: Fire spark crea la referencia del cobro con la aplicación de servidor, tu canal abre el checkout de Paymentez y Fire spark confirma el pago leyendo la transacción en Paymentez.

> [!NOTE]
>
> Paymentez no es el paquete [Nuvei](https://firespark.cloud/docs/es/integrations/payments/nuvei/card.md). Una cuenta de Paymentez tiene *application codes* y *app keys*; una cuenta de la REST API global de Nuvei tiene Merchant ID, Site ID y Secret key. Confirma con Nuvei en qué plataforma está tu cuenta.

La app key de servidor nunca llega al canal. La tarjeta se escribe en el checkout de Paymentez y nunca llega a tu canal ni a Fire spark.

| | |
| - | - |
| Países | Ecuador |
| Monedas | USD |
| Estado | Disponible (beta) |
| Paquete | `@fire-spark/payments-paymentez-checkout` |

| Método | Canal | Qué hace el cliente |
| - | - | - |
| Tarjeta (`CARD`) | Web, app móvil y kiosco (WebView) | Escribe la tarjeta en el checkout de Paymentez y, si el banco lo pide, el OTP o el 3DS |

## Cómo funciona

1. El adaptador le pide a Fire spark preparar el cobro (`prepare`). Fire spark llama a `init_reference` de Paymentez con el monto del tender y responde la `reference`.
2. El **bridge** de tu plantilla abre `PaymentCheckout` con esa referencia.
3. El cliente paga. El checkout responde `{ transaction: { status, id, status_detail } }`.
4. El adaptador le pide a Fire spark el estado (`status`). Fire spark lee la transacción en Paymentez y la acepta solo si es de este intento (`dev_reference`) y por el monto del tender.

Si el canal se cierra antes del paso 4, el webhook de Paymentez cierra el tender.

## Requisitos

* Una aplicación de **servidor** de Paymentez por ambiente: *application code* y *app key*. Las entrega el equipo de Nuvei/Paymentez (en sandbox empiezan con `NUVEISTG-`).
* El email del cliente en la orden, o pasarlo en `email`: Paymentez lo exige.
* Páginas servidas por https.

## Activarlo

1. En el dashboard, crea un pago con el proveedor **Paymentez** y el método `CARD`.
2. En **Connection Settings** completa:

| Campo | Clave | Secreto | Notas |
| - | - | - | - |
| Application code | `application_code` | No | Application code de servidor |
| App key | `secret_app_key` | Sí | Firma cada solicitud y el webhook. Queda en la API de Fire spark |

3. Opcional, por tienda: en **Store settings** pon el `application_code` y la `secret_app_key` de la tienda. Fire spark usa el par de la tienda solo si tiene los dos; si no, usa el de Connection Settings.
4. En Paymentez, configura la callback URL `https://<host-de-tu-api>/api/webhooks/payments/paymentez`.

## Usarlo en el 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 });
```

### Bridge web

Carga el checkout y ábrelo desde el clic del botón de pagar: los navegadores bloquean el popup si se abre en otro 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 (kiosco y app)

Corre el mismo checkout en un `react-native-webview` con una página https que cargue el script, abra `PaymentCheckout` con la `reference` y mande la respuesta con `window.ReactNativeWebView.postMessage`. Convierte el mensaje en el resultado del bridge: `onResponse` → `{ type: "response", response }`, `onClose` → `{ type: "closed", by: "user" }`. Prueba el WebView en sandbox antes de producción.

## Estados del cobro

| Checkout | Tender |
| - | - |
| `success` (`status_detail` 3) | `PAID` cuando Fire spark confirma la transacción |
| Esperando OTP o 3DS (`status_detail` 31, 35, 36) | `PENDING`; el SDK vuelve a consultar |
| Rechazada | `FAILED` con el código de la tabla de abajo |
| Cerrado por el cliente sin pagar | `FAILED` con `CANCELLED_BY_USER` |

## Webhooks

`POST /api/webhooks/payments/paymentez` cierra los cobros que el canal no confirmó. Fire spark valida el `stoken` (HMAC-SHA256 con la app key, o el MD5 de la versión vieja), relee la transacción en Paymentez y solo aplica lo que coincide con el intento y el monto.

## Reembolsos

Las anulaciones y reembolsos de Paymentez corren en el servidor de Fire spark. `order.cancel()` y `order.refund()` funcionan igual que con cualquier método: el dispositivo no hace nada con un tender Paymentez pagado y el servidor lo reembolsa en la misma llamada.

* En Ecuador Paymentez reembolsa **transacciones completas**. Un reembolso parcial falla en el ledger y se hace a mano en el dashboard de Paymentez.
* Una respuesta `pending` de Paymentez cuenta como aceptada; el webhook confirma el reembolso.

## Errores comunes

| Código Spark | `status_detail` de Paymentez | Qué hacer |
| - | - | - |
| `CARD_DECLINED` | 9, 16, 19, 33, 37 | Pide otra tarjeta u otro método |
| `FRAUD_SUSPECTED` | 6, 11, 12 | Pide otro método |
| `WALLET_EXPIRED` | 13, 14, 15, 20 | El checkout venció. Empieza de nuevo |
| `CANCELLED_BY_USER` | 17, 18 | El cliente abandonó el checkout |
| `INVALID_CREDENTIALS` | HTTP 401 | Revisa el application code, la app key y el ambiente |
| `PROVIDER_UNAVAILABLE` | 10, HTTP 5xx | Reintentable |
| `AMBIGUOUS` | Sin respuesta | Queda en revisión; revisa la transacción en el dashboard de Paymentez |


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