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

# Transbank Webpay Plus

> Cobra con tarjeta en Chile desde la web y apps con el formulario de Webpay Plus y @fire-spark/payments-transbank-webpay.

Webpay Plus es el formulario de pago de Transbank para tarjetas en Chile. Fire spark crea la transacción con tus llaves de comercio, tu canal abre el formulario de Webpay y Fire spark confirma el pago cuando Webpay devuelve al cliente. Las llaves nunca llegan al navegador ni a la app.

| | |
| - | - |
| Países | Chile |
| Monedas | CLP |
| Estado | Disponible |
| Paquete | `@fire-spark/payments-transbank-webpay` |

Web y apps móviles. Los kioscos con pinpad Hasar usan [Transbank pinpad](https://firespark.cloud/docs/es/integrations/payments/transbank/pinpad.md).

Sigue las secciones de abajo para integrarlo a mano. Para pasarle el mismo trabajo a un agente, copia el prompt de [Prompt para agentes de IA](#prompt-para-agentes-de-ia).

## Requisitos

* Un canal que ya cobra con `@fire-spark/core` (`setPaymentAdapters`, `setPaymentOptions`, `payIntent`).
* `setPaymentUI` con `challenge`. Webpay se abre como un challenge de pago: popup o pestaña nueva en la web, WebView en una app. Transbank desaconseja el iframe.
* Un código de comercio de Webpay Plus. Para integración, usa `597055555532` con la llave pública de integración.

## Actívalo

1. En el dashboard, abre tu merchant, ve a **Payments** y crea un pago con el proveedor **Transbank** y el método **Card**.
2. En **Connection Settings**, completa:

| Campo | Clave | Secreto | Notas |
| - | - | - | - |
| Código de comercio | `commerce_code` | No | Código de comercio de Webpay Plus (`Tbk-Api-Key-Id`). De 8 a 12 dígitos |
| Llave secreta | `secret_api_key` | Sí | `Tbk-Api-Key-Secret`. Se queda en la API de Fire spark |

> [!NOTE]
>
> El ambiente sandbox llama a `webpay3gint.transbank.cl` y producción a `webpay3g.transbank.cl`. En sandbox, usa el código `597055555532` y la llave `579B532A7440BB0C9079DED94D31EA1615BACEB56610332264630D42D0A36B1C`. Transbank envía la llave de producción cuando apruebas la validación.

## Úsalo en el SDK

```bash theme={null}
pnpm add @fire-spark/payments-transbank-webpay@0.17.2
```

```typescript theme={null}
import { transbankWebpayPayments } from "@fire-spark/payments-transbank-webpay";

order.setPaymentAdapters([transbankWebpayPayments()]);
```

El adaptador no recibe opciones. Implementa `challenge` en `setPaymentUI`. El adaptador lo llama con `method: "POST"` y un parámetro, `token_ws`. En la web, `paymentChallengeDocument(challenge)` de `@fire-spark/payments` arma la página que envía el formulario:

```typescript theme={null}
import { paymentChallengeDocument, parsePaymentChallengeMessage } from "@fire-spark/payments";

order.setPaymentUI({
  message: ({ text }) => setStatus(text),
  challenge: ({ signal, ...challenge }) =>
    new Promise(resolve => {
      const popup = window.open("", "webpay");
      popup?.document.write(paymentChallengeDocument(challenge));
      const done = (completed: boolean) => {
        window.removeEventListener("message", onMessage);
        clearInterval(watch);
        popup?.close();
        resolve({ completed });
      };
      const onMessage = (event: MessageEvent) => {
        if (parsePaymentChallengeMessage(event.data)) done(true);
      };
      window.addEventListener("message", onMessage);
      const watch = setInterval(() => popup?.closed && done(false), 500);
      signal.addEventListener("abort", () => done(false));
    })
});
```

En una app React Native, carga `paymentChallengeDocument(challenge)` en un WebView con `source={{ html }}` y resuelve con el mensaje `fire-spark:payment-challenge` de `window.ReactNativeWebView`.

Cobra el pago que eligió el cliente:

```typescript theme={null}
const result = await order.payIntent({ payment: webpayPayment });
```

`payIntent({ payment })` crea un tender real. Para dividir Webpay con otro método, llama `order.setTenders` con una asignación y después `payIntent()`. Ver [Usar pagos en el SDK](https://firespark.cloud/docs/es/guides/payments/use-payments-in-the-sdk.md).

Cuando el challenge termina, el adaptador le pide el resultado a Fire spark. Si el cliente cerró la ventana antes de que Webpay lo devolviera, Fire spark confirma el token igual, así que un pago que pasó no se pierde.

## Qué ve el cliente

El formulario de Webpay y después tu pantalla de resultado. Transbank pide que muestres tu propio comprobante: número de orden, comercio, monto, código de autorización, fecha, tipo de pago, cuotas y los últimos 4 dígitos. Están en `result.details` y `result.metadata.payment`.

| Resultado | Qué hace tu canal |
| - | - |
| `PAID` | Muestra el comprobante y sigue con la orden |
| `FAILED` con `CARD_DECLINED`, `INVALID_CARD`, `EXPIRED_CARD`, `FRAUD_SUSPECTED`, `LIMIT_EXCEEDED` | La tarjeta fue rechazada. Permite reintentar u otro método |
| `FAILED` con `CANCELLED_BY_USER` | El cliente anuló en Webpay o cerró el formulario sin pagar |
| `FAILED` con `USER_TIMEOUT` | Se acabó el tiempo del formulario (4 minutos en producción) |
| `FAILED` con `AMBIGUOUS` y `needs_review` | Se perdió la respuesta o el monto no coincide. No cobres de nuevo; revísalo en el portal de Transbank |
| `FAILED` con `INVALID_CREDENTIALS` | El código de comercio o la llave están mal |
| `FAILED` con `INVALID_REQUEST` | La moneda no es CLP, o tu canal no tiene `challenge` |

## Webhooks

Ninguno. Webpay devuelve el navegador a una URL de Fire spark firmada por intento. Fire spark confirma ahí y cierra el pago.

## Anulaciones

Cancela o devuelve la orden. Fire spark devuelve un pago `PAID` con las llaves del comercio. Webpay decide el tipo:

* El monto total dentro de las 3 horas del pago es una reversa.
* Después de eso, o un monto parcial, es una anulación, hasta 90 días. La anulación parcial no funciona en cuotas con interés.

Una devolución que Transbank rechaza (por ejemplo después de 90 días) falla en el ledger de la orden con el mensaje de Webpay, y se devuelve a mano.

## Errores comunes

| Código Spark | Cuándo | Qué hacer |
| - | - | - |
| `CARD_DECLINED` | `response_code` distinto de 0, o un status distinto de `AUTHORIZED` | Ofrece reintentar u otro método |
| `INVALID_CARD` | `response_code` -1 | Pide otra tarjeta |
| `FRAUD_SUSPECTED` | `response_code` -5 | Pide otro método |
| `INVALID_CREDENTIALS` | Webpay respondió 401 | Revisa el código de comercio y la llave de este ambiente |
| `INVALID_REQUEST` | La moneda no es CLP, el monto tiene decimales o no hay `challenge` | Cobra en CLP enteros e implementa `challenge` |
| `AMBIGUOUS` | Respuesta perdida o monto distinto | No reintentes. Revisa el pago |

## Pasar a producción

1. Aprueba la validación de Transbank en [validador.transbankdevelopers.cl](https://validador.transbankdevelopers.cl/) con tu código de comercio de producción y tu logo de 130x59.
2. Pon el código de comercio de producción y la llave que te envía Transbank en el pago de producción.
3. Haz una compra de \$50 en producción.

## Compatibilidad

| `@fire-spark/payments-transbank-webpay` | Proveedor | `@fire-spark/payments` |
| - | - | - |
| 0.17.x | Webpay Plus API REST 1.2 | 0.17.2 |

No incluye: captura diferida, Webpay Plus Mall, Oneclick ni USD.

## Prompt para agentes de IA

Pega esto en el agente que edita tu canal web o app. Cubre solo Transbank Webpay Plus.

```text title="Prompt de integración" theme={null}
Integra solo Transbank Webpay Plus (pagos con tarjeta en Chile, CLP) en este canal de Fire spark. No agregues otros proveedores de pago. No uses el paquete del pinpad Hasar.

Paquete: @fire-spark/payments-transbank-webpay@0.17.2, fijado a la misma versión que @fire-spark/payments.

Regístralo: order.setPaymentAdapters([transbankWebpayPayments()]). No recibe opciones ni llaves. El código de comercio y la llave secreta viven en el pago del dashboard (proveedor Transbank, método Card) y se quedan en la API de Fire spark. Nunca los pongas en la app.

Implementa setPaymentUI.challenge. El adaptador lo llama con { url, method: "POST", parameters: [{ name: "token_ws", value }], version, signal }.
- Web: abre un popup o una pestaña nueva (no un iframe; Transbank lo desaconseja). Escribe paymentChallengeDocument(challenge) de @fire-spark/payments ahí; esa página envía token_ws a Webpay.
- React Native: carga paymentChallengeDocument(challenge) en un WebView con source={{ html }}.
- Resuelve { completed: true } cuando llega un mensaje que parsePaymentChallengeMessage acepta (type "fire-spark:payment-challenge"). Resuelve { completed: false } cuando el cliente cierra la ventana o signal aborta. Cierra la ventana en los dos casos.
- Implementa también message: muestra el último texto.

Cobra:
const result = await order.payIntent({ payment: webpayPayment }); // webpayPayment es el pago Transbank Card de services.payments.list

Resultados:
- PAID: muestra tu propio comprobante con número de orden, comercio, monto, código de autorización (result.details.auth_code), fecha, tipo de pago y cuotas (result.metadata.payment) y últimos 4 dígitos (result.details.last4).
- FAILED con CARD_DECLINED, INVALID_CARD, EXPIRED_CARD, FRAUD_SUSPECTED, LIMIT_EXCEEDED: rechazada. Permite reintentar u otro método.
- FAILED con CANCELLED_BY_USER: el cliente anuló o cerró Webpay. Vuelve a la lista de métodos sin mostrar error.
- FAILED con USER_TIMEOUT: se acabó el tiempo del formulario. Permite reintentar.
- FAILED con AMBIGUOUS y metadata.needs_review: no cobres de nuevo. Dile al cliente que el pago se está revisando.
- FAILED con INVALID_CREDENTIALS o INVALID_REQUEST: problema de configuración. No reintentes en el checkout.

La moneda tiene que ser CLP en pesos enteros. No llames a Webpay desde la app, no confirmes y no devuelvas desde la app: Fire spark confirma en la vuelta y devuelve cuando la orden se cancela o se reembolsa.
```


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