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

> Charge cards in Chile from the web and apps through the Webpay Plus form with @fire-spark/payments-transbank-webpay.

Webpay Plus is the Transbank payment form for cards in Chile. Fire spark creates the transaction with your commerce keys, your channel opens the Webpay form, and Fire spark commits the payment when Webpay sends the customer back. The keys never reach the browser or the app.

| | |
| - | - |
| Countries | Chile |
| Currencies | CLP |
| Status | Available |
| Package | `@fire-spark/payments-transbank-webpay` |

Web and mobile apps. Kiosks with a Hasar pinpad use [Transbank pinpad](https://firespark.cloud/docs/integrations/payments/transbank/pinpad.md) instead.

Follow the sections below to wire it by hand. To hand the same work to an agent, copy the prompt in [AI agent prompt](#ai-agent-prompt).

## Requirements

* A channel that already charges with `@fire-spark/core` (`setPaymentAdapters`, `setPaymentOptions`, `payIntent`).
* `setPaymentUI` with `challenge`. Webpay opens as a payment challenge: a popup or new tab on the web, a WebView in an app. Transbank advises against an iframe.
* A Webpay Plus commerce code. For integration, use `597055555532` with the public integration key.

## Activate it

1. In the dashboard, open your merchant, go to **Payments**, and create a payment with the provider **Transbank** and the method **Card**.
2. In **Connection Settings**, fill in:

| Field | Key | Secret | Notes |
| - | - | - | - |
| Commerce code | `commerce_code` | No | Webpay Plus commerce code (`Tbk-Api-Key-Id`). 8 to 12 digits |
| Secret key | `secret_api_key` | Yes | `Tbk-Api-Key-Secret`. Stays on the Fire spark API |

> [!NOTE]
>
> The sandbox environment calls `webpay3gint.transbank.cl` and production calls `webpay3g.transbank.cl`. In sandbox, use the commerce code `597055555532` and the key `579B532A7440BB0C9079DED94D31EA1615BACEB56610332264630D42D0A36B1C`. Transbank sends the production key after you pass validation.

## Use it in the 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()]);
```

The adapter takes no options. Implement `challenge` in `setPaymentUI`. The adapter calls it with `method: "POST"` and one parameter, `token_ws`. On the web, `paymentChallengeDocument(challenge)` from `@fire-spark/payments` builds the page that posts the form:

```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));
    })
});
```

In a React Native app, load `paymentChallengeDocument(challenge)` in a WebView with `source={{ html }}` and resolve on the `fire-spark:payment-challenge` message from `window.ReactNativeWebView`.

Charge the payment the customer picked:

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

`payIntent({ payment })` places one real tender. To split Webpay with another method, call `order.setTenders` with an allocation and then `payIntent()`. See [Use payments in the SDK](https://firespark.cloud/docs/guides/payments/use-payments-in-the-sdk.md).

When the challenge resolves, the adapter asks Fire spark for the result. If the customer closed the window before Webpay sent them back, Fire spark commits the token anyway, so a payment that went through is not lost.

## What the customer sees

The Webpay form, then your result screen. Transbank asks you to show your own receipt: order number, merchant, amount, authorization code, date, payment type, installments, and the last 4 digits. They are on `result.details` and `result.metadata.payment`.

| Result | What your channel does |
| - | - |
| `PAID` | Show the receipt and continue the order |
| `FAILED` with `CARD_DECLINED`, `INVALID_CARD`, `EXPIRED_CARD`, `FRAUD_SUSPECTED`, `LIMIT_EXCEEDED` | The card was declined. Allow a retry or another method |
| `FAILED` with `CANCELLED_BY_USER` | The customer cancelled in Webpay or closed the form without paying |
| `FAILED` with `USER_TIMEOUT` | The Webpay form timed out (4 minutes in production) |
| `FAILED` with `AMBIGUOUS` and `needs_review` | The answer was lost or the amount did not match. Do not charge again; check it in the Transbank portal |
| `FAILED` with `INVALID_CREDENTIALS` | The commerce code or key is wrong |
| `FAILED` with `INVALID_REQUEST` | The currency is not CLP, or your channel has no `challenge` |

## Webhooks

None. Webpay sends the browser back to a Fire spark URL that is signed per attempt. Fire spark commits there and closes the payment.

## Voids

Cancel or refund the order. Fire spark refunds a `PAID` payment with the commerce keys. Webpay decides the kind:

* The full amount within 3 hours of the payment is a reversal.
* After that, or a partial amount, is an annulment, up to 90 days. Partial annulment does not work on installments with interest.

A refund Transbank refuses (for example after 90 days) fails in the order ledger with the Webpay message, and you refund it by hand.

## Common errors

| Spark code | When | What to do |
| - | - | - |
| `CARD_DECLINED` | `response_code` other than 0, or a status other than `AUTHORIZED` | Offer a retry or another method |
| `INVALID_CARD` | `response_code` -1 | Ask for another card |
| `FRAUD_SUSPECTED` | `response_code` -5 | Ask for another method |
| `INVALID_CREDENTIALS` | Webpay answered 401 | Check the commerce code and the secret key for this environment |
| `INVALID_REQUEST` | Currency is not CLP, the amount has decimals, or there is no `challenge` | Charge whole CLP and implement `challenge` |
| `AMBIGUOUS` | Lost answer or a different amount | Do not retry. Review the payment |

## Go live

1. Pass the Transbank validation at [validador.transbankdevelopers.cl](https://validador.transbankdevelopers.cl/) with your production commerce code and your 130x59 logo.
2. Put the production commerce code and the key Transbank sends you on the production payment.
3. Make a \$50 purchase in production.

## Compatibility

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

Not included: deferred capture, Webpay Plus Mall, Oneclick, and USD.

## AI agent prompt

Paste this into the agent that edits your web or app channel. It covers only Transbank Webpay Plus.

```text title="Integration prompt" theme={null}
Integrate only Transbank Webpay Plus (card payments in Chile, CLP) into this Fire spark channel. Do not add any other payment provider. Do not use the Hasar pinpad package.

Package: @fire-spark/payments-transbank-webpay@0.17.2, pinned to the same version as @fire-spark/payments.

Register it: order.setPaymentAdapters([transbankWebpayPayments()]). It takes no options and no keys. The commerce code and the secret key live in the dashboard payment (provider Transbank, method Card) and stay on the Fire spark API. Never put them in the app.

Implement setPaymentUI.challenge. The adapter calls it with { url, method: "POST", parameters: [{ name: "token_ws", value }], version, signal }.
- Web: open a popup or a new tab (not an iframe; Transbank advises against it). Write paymentChallengeDocument(challenge) from @fire-spark/payments into it; that page posts token_ws to Webpay.
- React Native: load paymentChallengeDocument(challenge) in a WebView with source={{ html }}.
- Resolve { completed: true } when a message arrives that parsePaymentChallengeMessage accepts (type "fire-spark:payment-challenge"). Resolve { completed: false } when the customer closes the window or signal aborts. Close the window either way.
- Also implement message: show the latest text.

Charge:
const result = await order.payIntent({ payment: webpayPayment }); // webpayPayment is the Transbank Card payment from services.payments.list

Results:
- PAID: show your own receipt with order number, merchant, amount, authorization code (result.details.auth_code), date, payment type and installments (result.metadata.payment), and last 4 digits (result.details.last4).
- FAILED with CARD_DECLINED, INVALID_CARD, EXPIRED_CARD, FRAUD_SUSPECTED, LIMIT_EXCEEDED: declined. Allow a retry or another method.
- FAILED with CANCELLED_BY_USER: the customer cancelled or closed Webpay. Return to the method list without an error.
- FAILED with USER_TIMEOUT: the form timed out. Allow a retry.
- FAILED with AMBIGUOUS and metadata.needs_review: do not charge again. Tell the customer the payment is being checked.
- FAILED with INVALID_CREDENTIALS or INVALID_REQUEST: configuration problem. Do not retry at checkout.

Currency must be CLP in whole pesos. Do not call Webpay from the app, do not commit, and do not refund from the app: Fire spark commits on the return and refunds when the order is cancelled or refunded.
```


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