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

# PlacetoPay

> Cobra tarjetas en la web en Ecuador con WebCheckout de PlacetoPay y @fire-spark/payments-placetopay-checkout.

> [!WARNING]
>
> **Beta.** `@fire-spark/payments-placetopay-checkout` está en beta desde el SDK 0.17.0. El pago con tarjeta funciona solo en la web, PlacetoPay solo reversa por API transacciones completas (no hay devoluciones parciales) y el catálogo de códigos de PlacetoPay todavía está pendiente. Prueba en el sandbox de PlacetoPay antes de salir a producción.

PlacetoPay ofrece **WebCheckout**, una página de pago alojada. Fire spark abre una sesión de WebCheckout para el tender, tu plantilla web envía al cliente a ella y Fire spark le pregunta a PlacetoPay el estado de la sesión cuando el cliente vuelve.

La secret key de PlacetoPay nunca llega al canal: Fire spark firma con ella cada llamada a PlacetoPay desde el servidor. La tarjeta se escribe en la página de PlacetoPay y nunca llega a tu canal ni a Fire spark.

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

| Método | Canal | Qué hace el cliente |
| - | - | - |
| Tarjeta (`CARD`) | Web | Paga en la página WebCheckout de PlacetoPay abierta en una pestaña del navegador y vuelve a tu sitio |

## Cómo funciona

1. El adaptador le pide a Fire spark abrir una sesión (`create_session`). Fire spark llama a PlacetoPay con el login del sitio, un `tranKey` firmado, el monto del tender y la referencia del intento como referencia del pago, y responde la URL de WebCheckout (`processUrl`). La sesión dura 15 minutos.
2. El **bridge** de tu plantilla abre WebCheckout en una pestaña del navegador (popup, pestaña nueva o redirección de página completa).
3. El cliente paga. PlacetoPay devuelve el navegador a tu `returnUrl`, con `placetopay_reference` (la referencia del intento) agregado por Fire spark.
4. El adaptador le pide a Fire spark el estado de la sesión (`status`). El tender queda `PAID` solo cuando PlacetoPay aprobó una transacción para este intento, monto y moneda. El retorno del navegador nunca se toma como resultado.
5. Si el cliente cierra la pestaña, o el intento vence, Fire spark cancela la sesión (`cancel_session`) para que no se pueda pagar después. Primero la lee y nunca cancela una que se pagó.

## Requisitos

* Un **sitio** de WebCheckout de PlacetoPay para Ecuador, con su **login** y su **secret key**. Sandbox y producción usan sitios distintos (ver [Probar](#probar)).
* Una plantilla web servida por https (`localhost` sirve para desarrollo). El pago con tarjeta es solo web.
* Una página `returnUrl` que le avise al bridge que el cliente volvió (ver [El bridge](#el-bridge)).

## Activarlo

1. En el dashboard, abre tu comercio, ve a **Payments** y crea un pago con el proveedor **PlacetoPay** y el método `CARD`.
2. En **Connection Settings**, completa:

| Campo | Clave | Secreto | Notas |
| - | - | - | - |
| Login | `placetopay_login` | No | Login de tu sitio PlacetoPay (hasta 32 caracteres) |
| Secret key | `secret_key` | Sí | Secret key de tu sitio PlacetoPay. Firma cada solicitud a PlacetoPay (`tranKey`). Queda en la API de Fire spark; nunca llega a los canales |

3. Opcional: define `provider_environment` para forzar `sandbox` o `production`. Sin él, el entorno sigue al del comercio.

| Entorno | Host de PlacetoPay |
| - | - |
| `sandbox` | `https://checkout-test.placetopay.ec` |
| `production` | `https://checkout.placetopay.ec` |

No hay ajustes por tienda.

### Notificación

En la configuración de tu sitio en PlacetoPay, registra como URL de notificación:

```
https://<api de Fire spark>/api/webhooks/payments/place_to_pay
```

Fire spark valida la firma con tu secret key y vuelve a consultar la sesión en PlacetoPay antes de cambiar el pago: el aviso solo dispara la consulta. Así se confirma un pago aunque el cliente nunca haya vuelto a tu tienda.

## Usarlo en el SDK

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

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

order.setPaymentAdapters([
  placetopayCheckoutPayments({
    bridge, // el PlacetopayRedirectBridge de tu plantilla, ver abajo
    returnUrl: "https://shop.example.com/placetopay/return"
  })
]);

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

Los mensajes de progreso ("Confirmando pago…") usan `message` en `order.setPaymentUI`, y el id de la sesión se guarda en tu almacenamiento de pagos para la redirección de página completa. 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 PlacetoPay 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

| Opción | Obligatoria | Descripción |
| - | - | - |
| `bridge` | Sí | Abre WebCheckout en una pestaña del navegador y reporta el retorno (`PlacetopayRedirectBridge`) |
| `returnUrl` | Sí | Página https a la que PlacetoPay devuelve al cliente ("Volver al comercio"). Hasta 255 caracteres |
| `cancelUrl` | No | Página https para "No deseo continuar". Por defecto: la página propia de PlacetoPay |
| `locale` | No | `es_EC` (por defecto), `en_US` o cualquier locale `xx_YY` que PlacetoPay soporte. Idioma de WebCheckout |
| `skipResult` | No | `true` salta la página de resultado de PlacetoPay y vuelve directo a `returnUrl` |

### El bridge

El bridge es código de tu plantilla web. El paquete define su forma (`PlacetopayRedirectBridge`), no su UI:

| Miembro | Descripción |
| - | - |
| `open({ url, attemptReference, returnUrl, signal })` | Abre `url` en una pestaña del navegador. Resuelve `{ type: "returned" }` cuando la pestaña vuelve a `returnUrl`, `{ 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 |

La página de retorno no necesita reenviar nada más que "returned": el resultado siempre sale del estado de la sesión que Fire spark lee de PlacetoPay. El paquete exporta `parsePlacetopayReturn(url)`, que lee la referencia del intento (`placetopay_reference`) de una URL de retorno, o `null` si no lo es. Úsala para ignorar retornos de otros intentos.

> [!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 {
  PlacetopayRedirectBridge,
  PlacetopayRedirectOutcome
} from "@fire-spark/payments-placetopay-checkout";

const MESSAGE = "placetopay:return";

export const bridge: PlacetopayRedirectBridge = {
  open: ({ url, attemptReference, 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: PlacetopayRedirectOutcome) => {
        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;
        if (event.data.reference !== attemptReference) return;
        tab.close();
        finish({ type: "returned" });
      };
      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);
    })
};
```

La página `returnUrl` le avisa a quien la abrió que el cliente volvió o, después de una redirección de página completa, vuelve a tu checkout:

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

const reference = parsePlacetopayReturn(window.location.href);

if (reference && window.opener) {
  // Popup o pestaña nueva: avisa al checkout y cierra.
  window.opener.postMessage(
    { type: "placetopay:return", reference },
    window.location.origin
  );
  window.close();
} else if (reference) {
  // Redirección de página completa: vuelve a tu checkout, que retoma el
  // tender pendiente y lee el estado de la sesión.
  window.location.replace("/checkout");
}
```

Después de un resultado `redirected` el tender queda `PENDING`. Cuando el adaptador lo consulta, lee el id de la sesión del resultado pendiente (o de tu almacenamiento de pagos) y le pide el estado a Fire spark. Dale a la orden un almacenamiento de pagos que sobreviva a la carga de la página.

Si defines `cancelUrl`, esa página puede resolver `cancelled` en lugar de `returned`, para que Fire spark cancele la sesión de inmediato. Resolver `returned` ahí también funciona: decide el estado.

## Montos e impuestos

Fire spark calcula el monto en el servidor, en dólares con dos decimales: el `total` de la sesión es el monto del tender. Cuando la orden tiene líneas gravadas, Fire spark también envía el IVA (`valueAddedTax`) con su base gravada, ambos prorrateados al monto del tender. El dispositivo nunca envía un monto.

Fire spark también envía el comprador desde el cliente de la orden cuando los tiene (nombre, apellido, email, celular y número de documento), para que PlacetoPay prellene su formulario. El tipo de documento sale del número: `CI` (10 dígitos), `RUC` (13 dígitos), si no `PPN` (pasaporte). La IP y el navegador (User-Agent) del cliente salen de la solicitud del storefront.

## Endpoints del storefront

El adaptador los llama 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/create_session` | `CARD` | Abre la sesión de WebCheckout del intento de pago actual y devuelve `request_id`, `process_url` y `expiration`. Recibe `return_url`, `cancel_url`, `locale`, `skip_result` y `user_agent`; ambas URLs deben ser https (o `localhost`). El monto sale del tender, nunca de la solicitud |
| `POST /api/storefront/v1/payments/{payment_id}/operations/status` | `CARD` | Lee la sesión (`request_id`) y devuelve el resultado (`PAID`, `FAILED` o `PENDING`) |
| `POST /api/storefront/v1/payments/{payment_id}/operations/cancel_session` | `CARD` | Cancela una sesión que nadie pagó (`request_id`). Si la sesión se aprobó, responde el resultado pagado |

## Qué ve el cliente

WebCheckout en una pestaña del navegador, la página de resultado de PlacetoPay (salvo con `skipResult`) y luego tu página `returnUrl`. Mientras tanto tu checkout muestra "Confirmando pago…".

Un tender pagado guarda `details` con la marca, los últimos 4 dígitos y el código de autorización. La metadata del resultado incluye `attempt_reference`, `payment` (`provider_transaction_id`, `authorization_code`, `reference`, `brand`, `last4`) y `provider` (`request_id`, `internal_reference`, `session_status`, `reason`, `franchise`, `payment_method`, `issuer_name`, `receipt`). No hay voucher.

## Tiempos y resultados desconocidos

* Un intento dura hasta 15 minutos, la vida de la sesión. No se reintenta solo: un reintento es una sesión nueva.
* Una transacción que PlacetoPay todavía tiene pendiente queda `PENDING` y el adaptador lee su estado cada 5 segundos.
* Cuando el intento vence, Fire spark cancela la sesión si nadie la pagó. Cualquier otra cosa queda para revisión.
* Si PlacetoPay no responde en 30 segundos, el tender termina `FAILED` con `AMBIGUOUS` y `needs_review`. Revisa la sesión en la consola de PlacetoPay.
* La [notificación](#notificación) de PlacetoPay confirma las sesiones que el canal no volvió a leer, por ejemplo si se cerró la página de la tienda durante el pago. PlacetoPay la envía una sola vez.

## Reembolsos

Fire Spark reversa un cobro pagado de PlacetoPay en el servidor cuando llamas `order.cancel()` u `order.refund()`, con las credenciales del sitio (`reverse` de PlacetoPay por `internalReference`). 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 PlacetoPay: la operación del ledger falla y la devuelves a mano en la consola de PlacetoPay.
* Un intento que nunca se cobró solo se descarta.

Un reverso fallido queda en el ledger de pagos de la orden con el mensaje de PlacetoPay, para que un operador lo termine.

## Errores comunes

| Código Spark | Causa en PlacetoPay | Qué hacer |
| - | - | - |
| `CARD_DECLINED` | Sesión rechazada, motivo `XN`, o un motivo que Fire spark no conoce | Pide otra tarjeta u otro método |
| `CANCELLED_BY_USER` | El cliente cerró la pestaña, o motivo `?C`, `MC` | Ofrece el método de nuevo |
| `AMBIGUOUS` | Sin respuesta, motivo `PT`, una sesión aceptada sin request id, o una sesión que no coincide con el tender | Marcado para revisión (`needs_review`). Revisa la sesión en la consola de PlacetoPay |
| `INVALID_CREDENTIALS` | Login rechazado (HTTP 401), motivo `401` o `103` (el reloj del servidor difiere más de 5 minutos del de PlacetoPay) | Revisa `placetopay_login`, `secret_key` y `provider_environment` en Connection Settings |
| `INVALID_REQUEST` | `returnUrl` o `cancelUrl` sin https, `request_not_valid`, PlacetoPay rechazó la sesión | Corrige las URLs e intenta de nuevo |
| `PROVIDER_UNAVAILABLE` | HTTP 5xx, 429, `transaction_request_error` | Intenta de nuevo con un nuevo intento |

El paquete exporta el mapa de códigos de PlacetoPay como `placetopayErrors`. Los códigos que no conoce caen en `CARD_DECLINED`. Ver [Errores de pago](https://firespark.cloud/docs/es/guides/payments/errors.md).

## Probar

Pídele a PlacetoPay un **sitio de sandbox** y pega su login y su secret key en Connection Settings, con `provider_environment` en `sandbox` (o usa un comercio de sandbox). Fire spark llama entonces a `https://checkout-test.placetopay.ec`.

1. Paga un tender con tarjeta desde tu canal web, con las tarjetas de prueba que te da PlacetoPay.
2. Prueba cerrar la pestaña antes de pagar: la sesión se cancela y el tender termina `CANCELLED_BY_USER`.
3. Revisa las sesiones en la consola de sandbox de PlacetoPay.

El pago con tarjeta funciona desde `localhost` durante el desarrollo.

## Compatibilidad

| `@fire-spark/payments-placetopay-checkout` | Proveedor | `@fire-spark/payments` |
| - | - | - |
| 0.17.0 (beta) | PlacetoPay WebCheckout (Ecuador) | Misma versión |


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