Saltar al contenido principal
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.
Paymentez no es el paquete Nuvei. 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.

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:
  1. 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.
  2. En Paymentez, configura la callback URL https://<host-de-tu-api>/api/webhooks/payments/paymentez.

Usarlo en el SDK

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.

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

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