> ## Documentation Index
> Fetch the complete documentation index at: https://firespark.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Payphone

> Cobra tarjetas en la web y pushes a la app Payphone en Ecuador con el Botón de Pago, la API Sale de Payphone y @fire-spark/payments-payphone-checkout.

> [!WARNING]
>
> **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.

| | |
| - | - |
| Países | Ecuador |
| Monedas | USD |
| Estado | Disponible (beta) |
| Paquete | `@fire-spark/payments-payphone-checkout` |

| Método | Canal | Qué hace el cliente |
| - | - | - |
| Tarjeta (`CARD`) | Web | Paga en el formulario de Payphone abierto en una pestaña del navegador y vuelve a tu sitio |
| Billetera (`WALLET`) | Kiosco, app móvil | Aprueba el push en su app Payphone en menos de 5 minutos, con su saldo Payphone o una tarjeta guardada en la app |

## 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](#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](#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:

| Campo | Clave | Secreto | Notas |
| - | - | - | - |
| Token | `secret_token` | Sí | Token de la configuración de tu app en Payphone Developer. Queda en la API de Fire spark; nunca llega a los canales |
| Id de tienda Payphone | `payphone_store_id` | No | Opcional. El `storeId` de Payphone de la sucursal a la que se cobra |
| Código de país | `country_code` | No | Solo `WALLET`. Código telefónico de país que se envía con la API Sale. Por defecto `593` |

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.

| Campo | Cuándo |
| - | - |
| Id de tienda Payphone (`payphone_store_id`) | Cada tienda que cobra a su propia sucursal Payphone |

Fire spark cobra con el id de tienda de la tienda de la orden.

## Usarlo en el SDK

```bash theme={null}
pnpm add @fire-spark/payments-payphone-checkout
```

Registra los adaptadores que ofrece tu canal: tarjeta en la web, billetera en kioscos y apps.

```typescript theme={null}
import {
  payphoneCardPayments,
  payphoneWalletPayments
} from "@fire-spark/payments-payphone-checkout";

// Web
order.setPaymentAdapters([
  payphoneCardPayments({
    bridge, // el PayphoneRedirectBridge de tu plantilla, ver abajo
    responseUrl: "https://shop.example.com/payphone/return"
  }),
  payphoneWalletPayments()
]);

// Kiosco o app móvil
order.setPaymentAdapters([payphoneWalletPayments()]);

const result = await order.payIntent({ payment: payphonePayment });
```

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](https://firespark.cloud/docs/es/guides/payments/use-payments-in-the-sdk.md#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](https://firespark.cloud/docs/es/guides/payments/use-payments-in-the-sdk.md).

### Opciones de tarjeta

| Opción | Obligatoria | Descripción |
| - | - | - |
| `bridge` | Sí | Abre el formulario de Payphone en una pestaña del navegador y reporta el retorno (`PayphoneRedirectBridge`) |
| `responseUrl` | Sí | Página https del dominio registrado a la que Payphone devuelve al cliente con `id` y `clientTransactionId` |
| `cancellationUrl` | No | Página https a la que Payphone envía al cliente cuando cancela el formulario |
| `payWith` | No | `card` (por defecto) abre el formulario de tarjeta. `payphone` abre el formulario propio de Payphone para pagar con el saldo Payphone |
| `language` | No | `es` (por defecto) o `en`. Idioma del formulario de Payphone |

### Opciones de billetera

| Opción | Obligatoria | Descripción |
| - | - | - |
| `phone` | No | `(ctx) => Promise<string \| null>`. Tu propia forma de obtener el celular. Por defecto: el celular del cliente de la orden, si no se pide con `ui.input` |
| `phoneLabel` | No | Etiqueta de la pregunta del celular. Por defecto: `Celular registrado en Payphone` |

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:

| Miembro | Descripción |
| - | - |
| `open({ url, attemptReference, responseUrl, signal })` | Abre `url` en una pestaña del navegador. Resuelve `{ type: "returned", id, clientTransactionId }` cuando la pestaña vuelve a `responseUrl`, `{ type: "cancelled" }` si el cliente la cerró, o `{ type: "redirected" }` cuando navegó toda la página. Cierra la pestaña y resuelve `cancelled` cuando `signal` se aborta |
| `takeReturn(attemptReference)` | Opcional. Después de una redirección de página completa, el retorno que guardó la página `responseUrl` para ese intento, una sola vez; si no, `null` |

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.

> [!NOTE]
>
> 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:

```typescript theme={null}
import type {
  PayphoneRedirectBridge,
  PayphoneRedirectOutcome
} from "@fire-spark/payments-payphone-checkout";

const MESSAGE = "payphone:return";

export const bridge: PayphoneRedirectBridge = {
  open: ({ url, signal }) =>
    new Promise(resolve => {
      const tab = window.open(url, "_blank");
      if (!tab) {
        // Popup bloqueado: redirige la página completa.
        resolve({ type: "redirected" });
        window.location.assign(url);
        return;
      }
      const finish = (outcome: PayphoneRedirectOutcome) => {
        window.removeEventListener("message", onMessage);
        clearInterval(closed);
        signal.removeEventListener("abort", onAbort);
        resolve(outcome);
      };
      const onMessage = (event: MessageEvent) => {
        if (event.origin !== window.location.origin) return;
        if (event.data?.type !== MESSAGE) return;
        finish({ type: "returned", ...event.data.back });
      };
      const onAbort = () => {
        tab.close();
        finish({ type: "cancelled" });
      };
      const closed = setInterval(() => {
        if (tab.closed) finish({ type: "cancelled" });
      }, 1000);
      window.addEventListener("message", onMessage);
      signal.addEventListener("abort", onAbort);
    }),
  takeReturn: async attemptReference => {
    const key = `payphone:return:${attemptReference}`;
    const saved = sessionStorage.getItem(key);
    if (!saved) return null;
    sessionStorage.removeItem(key);
    return JSON.parse(saved);
  }
};
```

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:

```typescript theme={null}
import { parsePayphoneReturn } from "@fire-spark/payments-payphone-checkout";

const back = parsePayphoneReturn(window.location.href);

if (back && window.opener) {
  // Popup o pestaña nueva: entrega el retorno al checkout y cierra.
  window.opener.postMessage(
    { type: "payphone:return", back },
    window.location.origin
  );
  window.close();
} else if (back) {
  // Redirección de página completa: guárdalo para bridge.takeReturn y
  // vuelve a tu checkout, que retoma el tender pendiente.
  const key = `payphone:return:${back.clientTransactionId}`;
  sessionStorage.setItem(key, JSON.stringify(back));
}
```

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.

| Endpoint | Método | Qué hace |
| - | - | - |
| `POST /api/storefront/v1/payments/{payment_id}/operations/prepare` | `CARD` | Prepara el formulario de Payphone del intento de pago actual y devuelve sus URLs. Recibe `response_url`, `cancellation_url` y `lang`; ambas URLs deben ser https (o `localhost`). El monto sale del tender, nunca de la solicitud |
| `POST /api/storefront/v1/payments/{payment_id}/operations/confirm` | `CARD` | Confirma el retorno (`id`, `client_transaction_id`) y devuelve el resultado (`PAID`, `FAILED` o `PENDING`) |
| `POST /api/storefront/v1/payments/{payment_id}/operations/sale` | `WALLET` | Envía el cobro a la app Payphone del cliente (`phone_number`) |
| `POST /api/storefront/v1/payments/{payment_id}/operations/sale_status` | `WALLET` | Estado del push de este intento |
| `POST /api/storefront/v1/payments/{payment_id}/operations/sale_cancel` | `WALLET` | Retira un push que sigue pendiente |

## 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

| Código Spark | Causa en Payphone | Qué hacer |
| - | - | - |
| `CARD_DECLINED` | `statusCode` `2` en un pago con tarjeta | Pide otra tarjeta u otro método |
| `WALLET_REJECTED` | `statusCode` `2` en un push, o el push fue rechazado | Pide otro método |
| `WALLET_EXPIRED` | Nadie aprobó el push en 5 minutos | Envía el push de nuevo con un nuevo intento |
| `CANCELLED_BY_USER` | El cliente cerró el formulario o dejó vacía la pregunta del celular | Ofrece el método de nuevo |
| `AMBIGUOUS` | Sin respuesta, o `errorCode` `20`, `25` | Marcado para revisión (`needs_review`). Revisa la transacción en Payphone Business |
| `INVALID_CREDENTIALS` | Token ausente o rechazado (HTTP 401, 403) | Revisa `secret_token` en Connection Settings |
| `INVALID_REQUEST` | `responseUrl` o `cancellationUrl` sin https, celular de menos de 7 dígitos, un retorno de otro intento, errores de validación de Payphone (`errorCode` `2029`) | Corrige las URLs o el celular e intenta de nuevo |
| `PROVIDER_UNAVAILABLE` | HTTP 5xx, 429 | Intenta de nuevo con un nuevo intento |

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](https://firespark.cloud/docs/es/guides/payments/errors.md).

## 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

| `@fire-spark/payments-payphone-checkout` | Proveedor | `@fire-spark/payments` |
| - | - | - |
| 0.15.0 (beta) | Payphone Botón de Pago + API Sale | Misma versión |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.