Saltar al contenido principal
Beta. @fire-spark/payments-pagoplux-card está en beta desde el SDK 0.13.1. PagoPlux solo anula por API transacciones completas del mismo día, y no tiene consulta de estado. Prueba en sandbox antes de salir a producción.
PagoPlux (pagoplux.com) es un procesador de tarjetas de Ecuador. Fire spark usa su API de Pago (tarjeta no presente): tu canal muestra su propio formulario de tarjeta en web, app o kiosco, el paquete cifra la tarjeta en el dispositivo y Fire spark la cobra con tus credenciales de PagoPlux. La tarjeta nunca llega a Fire spark en texto plano y la clave secreta de PagoPlux nunca llega al canal.

Cómo funciona

  1. Tu canal muestra su formulario de tarjeta y devuelve lo que escribió el titular.
  2. El paquete cifra cada campo de la tarjeta en el dispositivo con AES-256-ECB y una llave de 32 caracteres de un solo uso, y cifra esa llave con RSA usando la encryption_public_key del pago. PagoPlux exige que la tarjeta salga cifrada del cliente.
  3. Fire spark cobra la tarjeta cifrada con el client_id y el secret_key del pago. El monto sale del tender, nunca del dispositivo.
  4. Si la tarjeta necesita un código de un solo uso, el paquete lo pide y vuelve a enviar la misma tarjeta cifrada con el código.
El paquete nunca guarda ni registra la tarjeta, y la API de Fire spark nunca registra la tarjeta cifrada ni la sesión OTP.

Requisitos

  • Una cuenta de comercio en PagoPlux con acceso a la API de Pago, y sus claves de acceso de API por entorno (sandbox y producción están separados).
  • Una llave pública de cifrado generada en el dashboard de PagoPlux. PagoPlux debe habilitar el permiso de llave pública en tu cuenta antes de que puedas generarla. Hay una sola llave por comercio.
  • Tu propio formulario de tarjeta. Fire spark no lo dibuja; lo hace tu canal.
  • En React Native, crypto.getRandomValues: instala react-native-get-random-values o expo-crypto (ver React Native).

Activarlo

  1. En el dashboard, abre tu comercio, ve a Payments y crea un pago con el proveedor PagoPlux y el método CARD.
  2. En Connection Settings, completa:
  1. Opcional: define installments para ofrecer pagos diferidos (ver Cuotas) y provider_environment para forzar sandbox o production. Sin él, el entorno sigue al del comercio.

Por tienda

Cada tienda puede sobrescribir estos datos en Store settings del formulario del pago. Todo es opcional: lo que una tienda deja vacío usa los Connection Settings de arriba. Fire Spark cobra y anula con los datos de la tienda de la orden, y el adaptador le pide a Fire Spark la llave pública de la tienda (operación encryption_key) antes de cifrar la tarjeta.

Usarlo en el SDK

Tu canal implementa un collector: abre tu formulario de tarjeta y resuelve con lo que escribió el titular, o null si canceló. El adaptador hace el resto: cifra la tarjeta, pide a Fire spark que la cobre y pide el OTP cuando el banco lo exige.
La pregunta del OTP usa tu UI de pagos (input en order.setPaymentUI) y los mensajes de progreso usan message. Ver Preguntas del terminal y almacenamiento. payIntent({ payment }) crea un tender real. Para dividir PagoPlux con otro método, llama order.setTenders con una asignación y luego payIntent(). Ver Usar pagos en el SDK.

Opciones

El collector

collect(input) recibe: Resuelve con un PagopluxCardForm, o null si el cliente canceló (el tender termina FAILED con CANCELLED_BY_USER):
Nunca guardes, registres ni envíes la tarjeta a ningún otro lado. Resuelve la promesa y limpia el formulario: el adaptador cifra la tarjeta de inmediato.
PagoPlux exige el comprador completo: número de documento (cédula o RUC), nombres y apellidos, teléfono, email, ciudad, país y calle. Fire spark los toma del cliente de la orden (datos del cliente, dirección y facturación). Lo que el formulario envía en buyer y shippingAddress gana, así que pide el nombre del titular y su cédula cuando pueden ser distintos a los del cliente. Si aún falta un campo, el cobro se rechaza con INVALID_REQUEST.

React Native

El paquete cifra con crypto.getRandomValues, que React Native no trae. Haz una de estas:
Sin ninguna de las dos, el cobro falla antes de enviar nada a PagoPlux.

Código de un solo uso (OTP)

Las tarjetas Diners, Interdin y Discover piden un código que el banco envía al titular por SMS o email:
  1. Fire spark cobra la tarjeta y PagoPlux responde que se necesita un OTP.
  2. El adaptador pide el código con ui.input (etiqueta otpLabel).
  3. Vuelve a enviar la misma tarjeta cifrada con el código. El titular no vuelve a escribir la tarjeta.
  4. Un código incorrecto se puede volver a escribir hasta 3 veces en total. Después, el tender termina FAILED con INVALID_PIN.

3-D Secure

Cuando el banco del titular lo exige, PagoPlux responde con un desafío del banco en vez de cobrar:
  1. El adaptador lo muestra con ui.challenge de tu UI de pagos (ver Desafíos del banco). 3DS v1 envía un formulario al banco; 3DS v2 abre la URL del banco.
  2. El titular aprueba el pago en la página del banco.
  3. El banco envía el navegador a Fire spark, que confirma el pago con PagoPlux y registra el tender PAID o FAILED.
  4. El adaptador lee ese resultado y lo devuelve.
Si tu UI de pagos no tiene challenge, el tender termina FAILED con INVALID_REQUEST y no se cobra nada. Si el cliente cierra el desafío antes de que el banco responda, el tender termina FAILED con AMBIGUOUS y queda marcado para revisión: revisa el dashboard de PagoPlux.

Tarjetas guardadas

El cliente puede guardar su tarjeta en PagoPlux y pagar con ella después sin volver a escribirla. PagoPlux tokeniza la tarjeta (API de Registro de Tarjeta); Fire spark guarda solo una referencia cifrada al token, la marca, los últimos 4 dígitos y el vencimiento. El token nunca llega al canal.

Activarlas

En Connection Settings del pago PagoPlux: Guardar una tarjeta necesita un cliente con sesión en el storefront. Al registrarla, PagoPlux autoriza un monto mínimo para validar la tarjeta y lo reversa de inmediato: Fire spark no cobra ni reversa nada por la tokenización.

Guardar y pagar

Cuando el pago tiene las tarjetas guardadas activas, el collector recibe canSaveCard: true. Muestra una casilla “Guardar tarjeta” y devuelve saveCard: true si el cliente la marca. El adaptador:
  1. Guarda la tarjeta con la misma tarjeta cifrada. El OTP o el 3-D Secure de la tarjeta se piden aquí si el banco los exige.
  2. Cobra el tender con la tarjeta guardada, con las cuotas elegidas.
Un cobro con tarjeta guardada se anula igual que cualquier cobro de PagoPlux (ver Reembolsos).

Solo guardar

Para una pantalla de “mis tarjetas”, sin orden ni cobro:

Listar y eliminar

Cuotas

Activa installments en la configuración del pago (enabled y options) para ofrecer pagos diferidos. El adaptador pasa las opciones a tu formulario como installmentOptions; devuelve la cantidad elegida en installments e interests para diferido con intereses. El máximo es 48 meses. Las tarjetas de débito siempre son pago corriente (0).

Montos e impuestos

Fire spark calcula los montos en el servidor: la parte gravada de las líneas de la orden se prorratea al monto del tender y se envía como monto con IVA, el resto como monto sin IVA. Ambos suman el monto del tender. El dispositivo nunca envía un monto.

Endpoint del storefront

El adaptador lo llama con la operación de servidor del pago. Usa la sesión del storefront.

Qué ve el cliente

Tu formulario de tarjeta y, cuando el banco lo exige, la pregunta del OTP o el desafío del banco de tu UI de pagos. Un tender pagado guarda details con la marca, los últimos 4 dígitos, el código de autorización y las cuotas cuando son más de una. La metadata del resultado incluye attempt_reference, payment (provider_transaction_id, authorization_code, brand, card_type, last4, acquirer) y provider (code, transaction_id, token, date, amount). Cuando el cliente pidió guardar la tarjeta, provider.saved_card dice si se guardó. No hay voucher.

Tiempos y resultados desconocidos

  • Un intento dura hasta 10 minutos (formulario, emisor y OTP). Nunca se reintenta solo: la API de Pago no tiene llave de idempotencia, así que un reintento podría cobrar dos veces.
  • Si PagoPlux no responde en 45 segundos, o responde que el pago está pendiente, el tender termina FAILED con AMBIGUOUS y needs_review. La API de Pago no tiene consulta de estado, así que alguien debe revisar la transacción en el dashboard de PagoPlux.

Reembolsos

Fire Spark anula un cobro pagado de PagoPlux en el servidor cuando llamas order.cancel() u order.refund(), con el secret_key del pago (API de reversos por id de transacción de PagoPlux). El dispositivo no hace nada: el adaptador reporta el reverso como server.
  • Solo la transacción completa. Una devolución parcial no se envía a PagoPlux: la operación del ledger falla y la devuelves a mano en el dashboard de PagoPlux.
  • Solo el mismo día. PagoPlux anula una transacción solo antes de su corte diario (17h30 o medianoche, según el comercio). Después, la anulación falla con “fecha no permitida”: devuélvela a mano en el dashboard de PagoPlux.
  • Idempotente. Anular de nuevo responde “ya fue anulada previamente” y cuenta como hecho.
  • Un intento que nunca se cobró solo se descarta; si PagoPlux dice que nunca se autorizó, no hay nada que reversar.
Un reverso fallido queda en el ledger de pagos de la orden con el motivo de PagoPlux, para que un operador lo termine.

Errores comunes

El paquete exporta el mapa de códigos de PagoPlux como pagopluxErrors. Ver Errores de pago.

Probar en sandbox

Define provider_environment en sandbox (o usa un comercio de sandbox). Tarjetas de prueba de PagoPlux: Usa vencimiento 04/29 y CVV 123 (1234 para Amex), y una cédula ecuatoriana válida como document_number: el sandbox rechaza las inventadas. Si tu comercio de sandbox tiene 3-D Secure activo, VISA, Mastercard y Amex piden el desafío del banco; la página de prueba muestra el código. Las mismas tarjetas sirven para guardar una tarjeta.

Compatibilidad