Saltar al contenido principal
Beta. @fire-spark/payments-placetopay-checkout está en beta desde el SDK 0.17.0. El pago con tarjeta funciona solo en la web, PlacetoPay solo reversa por API transacciones completas (no hay devoluciones parciales) y el catálogo de códigos de PlacetoPay todavía está pendiente. Prueba en el sandbox de PlacetoPay antes de salir a producción.
PlacetoPay ofrece WebCheckout, una página de pago alojada. Fire spark abre una sesión de WebCheckout para el tender, tu plantilla web envía al cliente a ella y Fire spark le pregunta a PlacetoPay el estado de la sesión cuando el cliente vuelve. La secret key de PlacetoPay nunca llega al canal: Fire spark firma con ella cada llamada a PlacetoPay desde el servidor. La tarjeta se escribe en la página de PlacetoPay y nunca llega a tu canal ni a Fire spark.

Cómo funciona

  1. El adaptador le pide a Fire spark abrir una sesión (create_session). Fire spark llama a PlacetoPay con el login del sitio, un tranKey firmado, el monto del tender y la referencia del intento como referencia del pago, y responde la URL de WebCheckout (processUrl). La sesión dura 15 minutos.
  2. El bridge de tu plantilla abre WebCheckout en una pestaña del navegador (popup, pestaña nueva o redirección de página completa).
  3. El cliente paga. PlacetoPay devuelve el navegador a tu returnUrl, con placetopay_reference (la referencia del intento) agregado por Fire spark.
  4. El adaptador le pide a Fire spark el estado de la sesión (status). El tender queda PAID solo cuando PlacetoPay aprobó una transacción para este intento, monto y moneda. El retorno del navegador nunca se toma como resultado.
  5. Si el cliente cierra la pestaña, o el intento vence, Fire spark cancela la sesión (cancel_session) para que no se pueda pagar después. Primero la lee y nunca cancela una que se pagó.

Requisitos

  • Un sitio de WebCheckout de PlacetoPay para Ecuador, con su login y su secret key. Sandbox y producción usan sitios distintos (ver Probar).
  • Una plantilla web servida por https (localhost sirve para desarrollo). El pago con tarjeta es solo web.
  • Una página returnUrl que le avise al bridge que el cliente volvió (ver El bridge).

Activarlo

  1. En el dashboard, abre tu comercio, ve a Payments y crea un pago con el proveedor PlacetoPay y el método CARD.
  2. En Connection Settings, completa:
  1. Opcional: define provider_environment para forzar sandbox o production. Sin él, el entorno sigue al del comercio.
No hay ajustes por tienda.

Notificación

En la configuración de tu sitio en PlacetoPay, registra como URL de notificación:
Fire spark valida la firma con tu secret key y vuelve a consultar la sesión en PlacetoPay antes de cambiar el pago: el aviso solo dispara la consulta. Así se confirma un pago aunque el cliente nunca haya vuelto a tu tienda.

Usarlo en el SDK

Los mensajes de progreso (“Confirmando pago…”) usan message en order.setPaymentUI, y el id de la sesión se guarda en tu almacenamiento de pagos para la redirección de página completa. Ver Preguntas del terminal y almacenamiento. payIntent({ payment }) crea un tender real. Para dividir PlacetoPay con otro método, llama order.setTenders con una asignación y luego payIntent(). Ver Usar pagos en el SDK.

Opciones

El bridge

El bridge es código de tu plantilla web. El paquete define su forma (PlacetopayRedirectBridge), no su UI: La página de retorno no necesita reenviar nada más que “returned”: el resultado siempre sale del estado de la sesión que Fire spark lee de PlacetoPay. El paquete exporta parsePlacetopayReturn(url), que lee la referencia del intento (placetopay_reference) de una URL de retorno, o null si no lo es. Úsala para ignorar retornos de otros intentos.
El código de abajo es un ejemplo del código propio de tu plantilla, no parte del paquete. Adáptalo a tu router y tu UI.
Popup o pestaña nueva, con postMessage desde la página de retorno:
La página returnUrl le avisa a quien la abrió que el cliente volvió o, después de una redirección de página completa, vuelve a tu checkout:
Después de un resultado redirected el tender queda PENDING. Cuando el adaptador lo consulta, lee el id de la sesión del resultado pendiente (o de tu almacenamiento de pagos) y le pide el estado a Fire spark. Dale a la orden un almacenamiento de pagos que sobreviva a la carga de la página. Si defines cancelUrl, esa página puede resolver cancelled en lugar de returned, para que Fire spark cancele la sesión de inmediato. Resolver returned ahí también funciona: decide el estado.

Montos e impuestos

Fire spark calcula el monto en el servidor, en dólares con dos decimales: el total de la sesión es el monto del tender. Cuando la orden tiene líneas gravadas, Fire spark también envía el IVA (valueAddedTax) con su base gravada, ambos prorrateados al monto del tender. El dispositivo nunca envía un monto. Fire spark también envía el comprador desde el cliente de la orden cuando los tiene (nombre, apellido, email, celular y número de documento), para que PlacetoPay prellene su formulario. El tipo de documento sale del número: CI (10 dígitos), RUC (13 dígitos), si no PPN (pasaporte). La IP y el navegador (User-Agent) del cliente salen de la solicitud del storefront.

Endpoints del storefront

El adaptador los llama con las operaciones de servidor del pago. Usan la sesión del storefront.

Qué ve el cliente

WebCheckout en una pestaña del navegador, la página de resultado de PlacetoPay (salvo con skipResult) y luego tu página returnUrl. Mientras tanto tu checkout muestra “Confirmando pago…”. Un tender pagado guarda details con la marca, los últimos 4 dígitos y el código de autorización. La metadata del resultado incluye attempt_reference, payment (provider_transaction_id, authorization_code, reference, brand, last4) y provider (request_id, internal_reference, session_status, reason, franchise, payment_method, issuer_name, receipt). No hay voucher.

Tiempos y resultados desconocidos

  • Un intento dura hasta 15 minutos, la vida de la sesión. No se reintenta solo: un reintento es una sesión nueva.
  • Una transacción que PlacetoPay todavía tiene pendiente queda PENDING y el adaptador lee su estado cada 5 segundos.
  • Cuando el intento vence, Fire spark cancela la sesión si nadie la pagó. Cualquier otra cosa queda para revisión.
  • Si PlacetoPay no responde en 30 segundos, el tender termina FAILED con AMBIGUOUS y needs_review. Revisa la sesión en la consola de PlacetoPay.
  • La notificación de PlacetoPay confirma las sesiones que el canal no volvió a leer, por ejemplo si se cerró la página de la tienda durante el pago. PlacetoPay la envía una sola vez.

Reembolsos

Fire Spark reversa un cobro pagado de PlacetoPay en el servidor cuando llamas order.cancel() u order.refund(), con las credenciales del sitio (reverse de PlacetoPay por internalReference). 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 PlacetoPay: la operación del ledger falla y la devuelves a mano en la consola de PlacetoPay.
  • Un intento que nunca se cobró solo se descarta.
Un reverso fallido queda en el ledger de pagos de la orden con el mensaje de PlacetoPay, para que un operador lo termine.

Errores comunes

El paquete exporta el mapa de códigos de PlacetoPay como placetopayErrors. Los códigos que no conoce caen en CARD_DECLINED. Ver Errores de pago.

Probar

Pídele a PlacetoPay un sitio de sandbox y pega su login y su secret key en Connection Settings, con provider_environment en sandbox (o usa un comercio de sandbox). Fire spark llama entonces a https://checkout-test.placetopay.ec.
  1. Paga un tender con tarjeta desde tu canal web, con las tarjetas de prueba que te da PlacetoPay.
  2. Prueba cerrar la pestaña antes de pagar: la sesión se cancela y el tender termina CANCELLED_BY_USER.
  3. Revisa las sesiones en la consola de sandbox de PlacetoPay.
El pago con tarjeta funciona desde localhost durante el desarrollo.

Compatibilidad