- 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í.
Cómo funciona
Tarjeta (web)
- 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. - 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).
- El cliente paga. Payphone devuelve el navegador a tu
responseUrlconidyclientTransactionIden la query string. - 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)
- El adaptador toma el celular del cliente de la orden, o lo pide con
ui.input. - Fire spark envía el cobro a ese celular con la API Sale (
sale). - 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. - Un push que nadie aprueba a tiempo se retira (
sale_cancel) y el tender terminaFAILEDconWALLET_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 (
localhostsirve 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: originuorigin-when-cross-origin. Con una política más estricta Payphone responde “Acceso denegado o dominio no permitido”. - Para tarjeta: una página
responseUrlen 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
- En el dashboard, abre tu comercio, ve a Payments y crea un pago con el proveedor Payphone y el método
CARD,WALLETo uno de cada uno. - 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
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.
postMessage desde la página de retorno:
responseUrl envía el retorno a quien la abrió, o lo guarda para takeReturn después de una redirección de página completa:
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 aamountWithoutTax, 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áginaresponseUrl. 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
FAILEDconAMBIGUOUSyneeds_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 llamasorder.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.
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.- Invita a tus probadores desde la app Payphone, para que paguen con sus propias cuentas Payphone.
- Paga un tender con tarjeta o billetera desde tu canal.
- Revisa las transacciones en Payphone Developer, en Probadores > Transacciones.
localhost durante el desarrollo, con el Referrer-Policy de arriba.