Saltar al contenido principal
Beta. @fire-spark/payments-payphone-checkout está en beta desde el SDK 0.15.0. El pago con tarjeta funciona solo en la web, Payphone solo reversa por API transacciones completas del mismo día (no hay devoluciones parciales) y el catálogo de errores de Payphone todavía está pendiente. Prueba con una app de pruebas de Payphone antes de salir a producción.
Payphone (payphone.app) es una plataforma de pagos de Ecuador. Un solo paquete cubre dos métodos:
  • Tarjeta en la web con el Botón de Pago por redirección: Fire spark prepara el formulario de Payphone, tu plantilla web lo abre en una pestaña del navegador y Fire spark confirma el pago cuando el cliente vuelve.
  • Push a la app Payphone con la API Sale, para kioscos y apps móviles: Fire spark envía el cobro a la app Payphone del cliente y el cliente lo aprueba ahí.
El token de Payphone nunca llega al canal: Fire spark llama a Payphone con él desde el servidor. La tarjeta se escribe en el formulario de Payphone y nunca llega a tu canal ni a Fire spark.

Cómo funciona

Tarjeta (web)

  1. El adaptador le pide a Fire spark preparar el pago (prepare). Fire spark llama a Prepare de Payphone con el token y el monto del tender, y responde las URLs del formulario.
  2. El bridge de tu plantilla abre el formulario de Payphone en una pestaña del navegador (popup, pestaña nueva o redirección de página completa).
  3. El cliente paga. Payphone devuelve el navegador a tu responseUrl con id y clientTransactionId en la query string.
  4. El adaptador le pide a Fire spark confirmar (confirm). Payphone reversa cualquier cobro que no se confirme en 5 minutos, así que el canal confirma apenas el cliente vuelve. El formulario de Payphone dura 10 minutos.

Billetera (kiosco y app)

  1. El adaptador toma el celular del cliente de la orden, o lo pide con ui.input.
  2. Fire spark envía el cobro a ese celular con la API Sale (sale).
  3. El cliente aprueba el push en la app Payphone en menos de 5 minutos. El adaptador muestra “Aprueba el pago en tu app Payphone” y lee el estado (sale_status) cada 3 segundos.
  4. Un push que nadie aprueba a tiempo se retira (sale_cancel) y el tender termina FAILED con WALLET_EXPIRED.

Requisitos

  • Una cuenta de negocio Payphone y una configuración de app en Payphone Developer, con su token. Pruebas y producción usan configuraciones distintas (ver Probar).
  • Para tarjeta: una plantilla web en el dominio registrado en Payphone Developer, servida por https (localhost sirve para desarrollo). Payphone prohíbe su formulario dentro de apps, iframes y WebViews, así que el pago con tarjeta es solo web.
  • Para tarjeta: tu sitio debe enviar Referrer-Policy: origin u origin-when-cross-origin. Con una política más estricta Payphone responde “Acceso denegado o dominio no permitido”.
  • Para tarjeta: una página responseUrl en ese dominio que lea el retorno y se lo pase al bridge (ver El bridge).
  • Para billetera: clientes con la app Payphone y un celular registrado en Payphone.

Activarlo

  1. En el dashboard, abre tu comercio, ve a Payments y crea un pago con el proveedor Payphone y el método CARD, WALLET o uno de cada uno.
  2. En Connection Settings, completa:
Payphone usa el mismo host para pruebas y producción: el token decide a cuál cobras.

Por tienda

Cada tienda puede sobrescribir el id de tienda Payphone en Store settings del formulario del pago. Una tienda que lo deja vacío usa el de los Connection Settings. Fire spark cobra con el id de tienda de la tienda de la orden.

Usarlo en el SDK

Registra los adaptadores que ofrece tu canal: tarjeta en la web, billetera en kioscos y apps.
La pregunta del celular de la billetera 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 Payphone con otro método, llama order.setTenders con una asignación y luego payIntent(). Ver Usar pagos en el SDK.

Opciones de tarjeta

Opciones de billetera

Si el cliente deja vacía la pregunta del celular, el tender termina FAILED con CANCELLED_BY_USER.

El bridge

El bridge es código de tu plantilla web. El paquete define su forma (PayphoneRedirectBridge), no su UI: El paquete exporta parsePayphoneReturn(url), que lee id y clientTransactionId de una URL de retorno, o null si no lo es. clientTransactionId es la referencia del intento: el adaptador rechaza con INVALID_REQUEST un retorno de otro intento.
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 responseUrl envía el retorno a quien la abrió, o lo guarda para takeReturn después de una redirección de página completa:
Después de un resultado redirected el tender queda PENDING. Cuando el adaptador lo consulta, llama takeReturn y confirma el retorno apenas está ahí. Confirma dentro de los 5 minutos del pago, o Payphone lo reversa.

Montos e impuestos

Fire spark calcula los montos en el servidor, en centavos, a partir de las líneas de la orden: las líneas sin impuesto van a amountWithoutTax, las gravadas sin su impuesto a amountWithTax y el impuesto a tax. Cada parte se prorratea al monto del tender y suman exactamente ese monto. El dispositivo nunca envía un monto. Fire spark también envía el email, el celular y la cédula del titular desde el cliente de la orden cuando los tiene.

Endpoints del storefront

Los adaptadores los llaman con las operaciones de servidor del pago. Usan la sesión del storefront.

Qué ve el cliente

En la web, el formulario de Payphone en una pestaña del navegador y luego tu página responseUrl. En kioscos y apps, tu pregunta del celular (cuando la orden no tiene celular) y el mensaje de espera mientras aprueba en la app Payphone. Un tender de tarjeta pagado guarda details con la marca, los últimos 4 dígitos y el código de autorización. Un tender de billetera (o un pago con tarjeta hecho con el saldo Payphone) guarda method: "WALLET", wallet: "payphone" y una referencia. La metadata del resultado incluye attempt_reference, payment (provider_transaction_id, authorization_code, reference, brand, card_type, last4) y provider (transaction_id, client_transaction_id, status_code, deferred). No hay voucher.

Tiempos y resultados desconocidos

  • Un intento con tarjeta dura hasta 15 minutos; uno con billetera, hasta 6 minutos. Ninguno se reintenta solo: un reintento sería un cobro nuevo.
  • Si Payphone no responde en 30 segundos, el tender termina FAILED con AMBIGUOUS y needs_review. Revisa la transacción en Payphone Business.
  • Un cobro con tarjeta que nunca se confirma lo reversa el propio Payphone a los 5 minutos.
  • Fire spark no usa el webhook de estado de Payphone (“notificación externa”): Payphone debe habilitarlo y no viene firmado. Los adaptadores leen el estado por su cuenta.

Reembolsos

Fire Spark reversa un cobro pagado de Payphone en el servidor cuando llamas order.cancel() u order.refund(), con el token del pago (Reverse de Payphone por id de transacción). 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 Payphone: la operación del ledger falla y la devuelves a mano en Payphone Business.
  • Solo el mismo día. Payphone reversa una transacción solo hasta las 23:59, hora de Ecuador, del día en que se pagó. Después, el reverso falla: devuélvela a mano en Payphone Business.
  • Un intento que nunca se cobró solo se descarta.
Un reverso fallido queda en el ledger de pagos de la orden con el motivo de Payphone, para que un operador lo termine.

Errores comunes

El paquete exporta el mapa de códigos de Payphone como payphoneErrors. Los códigos que no conoce caen en CARD_DECLINED (tarjeta) o WALLET_REJECTED (billetera). Ver Errores de pago.

Probar

Crea una configuración de pruebas en Payphone Developer y pega su token en Connection Settings. Una app de pruebas de Payphone aprueba todas las transacciones: no hay bancos ni cobros reales.
  1. Invita a tus probadores desde la app Payphone, para que paguen con sus propias cuentas Payphone.
  2. Paga un tender con tarjeta o billetera desde tu canal.
  3. Revisa las transacciones en Payphone Developer, en Probadores > Transacciones.
El pago con tarjeta funciona desde localhost durante el desarrollo, con el Referrer-Policy de arriba.

Compatibilidad