Skip to main content
Beta. @fire-spark/payments-payphone-checkout is in beta since SDK 0.15.0. Card payments work only on the web, Payphone reverses only whole, same-day transactions by API (no partial refunds), and the Payphone error catalog is still pending. Test with a Payphone test app before going live.
Payphone (payphone.app) is an Ecuadorian payment platform. One package covers two methods:
  • 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.
The Payphone token never reaches the channel: Fire spark calls Payphone with it on the server. The card is typed in Payphone’s own form and never reaches your channel or Fire spark.

How it works

Card (web)

  1. 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.
  2. Your template’s bridge opens the Payphone form in a browser tab (a popup, a new tab, or a full-page redirect).
  3. The customer pays. Payphone sends the browser back to your responseUrl with id and clientTransactionId in the query string.
  4. 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)

  1. The adapter takes the phone number from the order customer, or asks for it with ui.input.
  2. Fire spark sends the charge to that phone with API Sale (sale).
  3. 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.
  4. A push nobody approves in time is withdrawn (sale_cancel), and the tender ends FAILED with WALLET_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 (localhost works 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: origin or origin-when-cross-origin. With a stricter policy Payphone answers “Acceso denegado o dominio no permitido”.
  • For card: a responseUrl page 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

  1. 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.
  2. 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

Register the adapters your channel offers: card on the web, wallet on kiosks and apps.
The wallet phone prompt uses your payment UI (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.
Popup or new tab, with postMessage from the return page:
The responseUrl page sends the return to the opener, or saves it for takeReturn after a full-page redirect:
After a 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 to amountWithoutTax, 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 your responseUrl 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 FAILED with AMBIGUOUS and needs_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 call order.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.
A failed reversal stays in the order’s payment ledger with Payphone’s reason, for an operator to finish.

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.
  1. Invite your testers from the Payphone app, so they can pay with their own Payphone accounts.
  2. Pay a card or wallet tender from your channel.
  3. Review the transactions in Payphone Developer, under Probadores > Transacciones.
Card payments work from localhost during development, with the Referrer-Policy above.

Compatibility