- Card on the web with the Botón de Pago por redirección: Fire spark prepares the Payphone form, your web template opens it in a browser tab, and Fire spark confirms the payment when the customer comes back.
- Payphone app push with API Sale, for kiosks and mobile apps: Fire spark sends the charge to the customer’s Payphone app, and the customer approves it there.
How it works
Card (web)
- The adapter asks Fire spark to prepare the payment (
prepare). Fire spark calls Payphone Prepare with the token and the tender amount, and answers the form URLs. - Your template’s bridge opens the Payphone form in a browser tab (a popup, a new tab, or a full-page redirect).
- The customer pays. Payphone sends the browser back to your
responseUrlwithidandclientTransactionIdin the query string. - The adapter asks Fire spark to confirm (
confirm). Payphone reverses any charge not confirmed within 5 minutes, so the channel confirms as soon as the customer is back. The Payphone form itself lives 10 minutes.
Wallet (kiosk and app)
- The adapter takes the phone number from the order customer, or asks for it with
ui.input. - Fire spark sends the charge to that phone with API Sale (
sale). - The customer approves the push in the Payphone app within 5 minutes. The adapter shows “Aprueba el pago en tu app Payphone” and reads the status (
sale_status) every 3 seconds. - A push nobody approves in time is withdrawn (
sale_cancel), and the tender endsFAILEDwithWALLET_EXPIRED.
Requirements
- A Payphone business account and an app configuration in Payphone Developer, with its token. Test and production use separate configurations (see Test).
- For card: a web template on the domain registered in Payphone Developer, served over https (
localhostworks for development). Payphone forbids its form inside apps, iframes, and WebViews, so card payments are web only. - For card: your site must send
Referrer-Policy: originororigin-when-cross-origin. With a stricter policy Payphone answers “Acceso denegado o dominio no permitido”. - For card: a
responseUrlpage on that domain that reads the return and hands it to the bridge (see The bridge). - For wallet: customers with the Payphone app and a phone number registered in Payphone.
Activate it
- In the dashboard, open your merchant, go to Payments, and create a payment with the provider Payphone and the method
CARD,WALLET, or one of each. - In Connection Settings, fill in:
Payphone uses the same host for test and production: the token decides which one you charge.
Per store
Each store can override the Payphone store ID under Store settings in the payment form. A store that leaves it empty uses the Connection Settings one.
Fire spark charges with the store ID of the order’s store.
Use it in the SDK
input in order.setPaymentUI), and progress messages use message. See Terminal prompts and storage.
payIntent({ payment }) places one real tender. To split Payphone with another method, call order.setTenders with an allocation and then payIntent(). See Use payments in the SDK.
Card options
Wallet options
If the customer leaves the phone prompt empty, the tender ends
FAILED with CANCELLED_BY_USER.
The bridge
The bridge is your web template’s code. The package defines its shape (PayphoneRedirectBridge), not its UI:
The package exports
parsePayphoneReturn(url), which reads id and clientTransactionId from a return URL, or null if it is not one. clientTransactionId is the attempt reference: the adapter rejects a return for another attempt with INVALID_REQUEST.
The code below is an example of your template’s own code, not part of the package. Adapt it to your router and UI.
postMessage from the return page:
responseUrl page sends the return to the opener, or saves it for takeReturn after a full-page redirect:
redirected outcome the tender stays PENDING. When the adapter queries it, it calls takeReturn and confirms the return as soon as it is there. Confirm within 5 minutes of the payment, or Payphone reverses it.
Amounts and taxes
Fire spark computes the amounts on the server, in cents, from the order lines: untaxed lines go toamountWithoutTax, taxed lines without their tax to amountWithTax, and the tax to tax. Each part is prorated to the tender amount, and they add up to it exactly. The device never sends an amount. Fire spark also sends the cardholder’s email, phone, and ID number from the order customer when it has them.
Storefront endpoints
The adapters call these through the payment server operations. They use the storefront session.What the customer sees
On the web, the Payphone form in a browser tab, then yourresponseUrl page. On kiosks and apps, your phone prompt (when the order has no phone) and the waiting message while they approve in the Payphone app.
A paid card tender records details with the card brand, last 4 digits, and authorization code. A wallet tender (or a card payment made with the Payphone balance) records method: "WALLET", wallet: "payphone", and a reference. The result metadata includes attempt_reference, payment (provider_transaction_id, authorization_code, reference, brand, card_type, last4), and provider (transaction_id, client_transaction_id, status_code, deferred). There is no voucher.
Timeouts and unknown results
- One card attempt lasts up to 15 minutes; one wallet attempt up to 6 minutes. Neither is retried automatically: a retry would be a new charge.
- If Payphone does not answer within 30 seconds, the tender ends
FAILEDwithAMBIGUOUSandneeds_review. Check the transaction in Payphone Business. - A card charge that is never confirmed is reversed by Payphone itself after 5 minutes.
- Fire spark does not use Payphone’s status webhook (“notificación externa”): it needs Payphone to enable it and is not signed. The adapters read the status themselves.
Refunds
Fire Spark reverses a paid Payphone charge on the server when you callorder.cancel() or order.refund(), with the payment’s token (Payphone Reverse by transaction id). The device does nothing: the adapter reports the reversal as server.
- Whole transaction only. A partial refund is not sent to Payphone: the ledger operation fails and you refund it by hand in Payphone Business.
- Same day only. Payphone reverses a transaction only until 23:59 Ecuador time of the day it was paid. After that the reversal fails: refund it by hand in Payphone Business.
- An attempt that was never charged is just discarded.
Common errors
The package exports the Payphone code map as
payphoneErrors. Codes it does not know fall back to CARD_DECLINED (card) or WALLET_REJECTED (wallet). See Payment errors.
Test
Create a test configuration in Payphone Developer and paste its token in Connection Settings. A Payphone test app approves every transaction: there are no banks and no real charges.- Invite your testers from the Payphone app, so they can pay with their own Payphone accounts.
- Pay a card or wallet tender from your channel.
- Review the transactions in Payphone Developer, under Probadores > Transacciones.
localhost during development, with the Referrer-Policy above.