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

> Charge a card on a Transbank Hasar H2H pinpad from the Android kiosk with @fire-spark/payments-transbank-pinpad-rn.

Transbank Hasar H2H runs the pinpad on Fire spark kiosks in Chile. One dashboard payment is one checkout button. The kiosk writes a properties file and the Hasar JAR talks to the pinpad over serial. Your kiosk draws the waiting message the adapter sends.

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

Android kiosk only. POS, web, and iOS do not use this package. This is not POS Integrado and not the PAX IM30 self-service terminal.

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

* An Android kiosk that already charges with `@fire-spark/core` (`setPaymentAdapters`, `setPaymentOptions`, `payIntent`).
* A development build. Expo Go does not load the native module.
* The Hasar binaries, kept outside git. The pinpad is on `/dev/ttyACM0`.
* The kiosk can write `Download/SDKChile`.

> [!WARNING]
>
> Do not commit the four JARs or `libjSerialComm.so`. The kiosk app points the config plugin at a `binariesDir` on the build machine.

## Activate it

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

| Field | Key | Secret | Notes |
| - | - | - | - |
| Hostname | `hostname` | No | `ECULINK.HOSTNAME` |
| Port | `port` | No | Digits. `ECULINK.PORTNUMBER` |
| Timeout (ms) | `timeout_ms` | No | Digits. `ECULINK.TIMEOUT` |
| Deliver BIN | `deliver_bin` | No | `S` or `N` |
| Self service | `self_service` | No | `S` or `N` |
| Modalities | `modalities` | No | `CREDIT`, `DEBIT`, or both. At least one. See [Checkout button](#checkout-button) |

3. On each store, add store settings:

| Field | Key | Notes |
| - | - | - |
| EcuLink IP | `eculink_ip` | Pinpad IP on the store network |
| Local | `local` | `TXC.LOCAL` |
| Store name | `store_name` | Voucher header |
| Store address | `store_address` | Voucher header |
| Store city | `store_city` | Voucher header |

4. On each kiosk, open the device and the **Payments** tab. Values live in `settings_overrides.payment_settings`, keyed by payment id. See [Configure a device](https://firespark.cloud/docs/guides/payments/configure-a-device.md).

| Field | Key | Secret | Notes |
| - | - | - | - |
| Terminal ID | `terminal_id` | No | `TBS.TERMINALID` |
| Retailer ID | `retailer_id` | No | Maxpoint cash register id (`idCaja`). This is not a commerce code |
| Register number | `register_number` | No | `TXC.CAJA`. Separate from the retailer id |

> [!NOTE]
>
> A payment that is missing a store or device field never reaches the kiosk, so its button stays off the checkout.

## Checkout button

Each Transbank payment is one button. The kiosk template already renders one card per payment from `services.payments.list` (`CheckoutPaymentMethodCard`). You do not add a button component.

`paymentInstructionKind` treats a `PIN_PAD` payment as a card, unless that payment is Pix only. Transbank modalities are `CREDIT` and `DEBIT`, so the template shows the card illustration. The label is `payment.name`.

* Both modalities on one payment: the customer picks one before the pinpad starts. The adapter asks through `ui.select`, with the title `Card type` and the options `Credit` and `Debit`. Show those strings as they arrive. Closing the picker rejects the promise and the pinpad does not start. The adapter then calls `ui.message` with `Present the card on the pinpad` and `kind: "waiting"`.
* One modality: there is no picker. The charge goes straight to the waiting message.
* Credit and debit as their own buttons: create a second payment with a single modality, for example `modalities: ["DEBIT"]`. It sits next to the first. Both show the card illustration. There is no Transbank helper like `isPixOnlyPayment`. Do not special-case Transbank as Pix.

The packages are not part of the public template. Add them in the merchant kiosk app. `useCheckoutPayments` hides only the Fire spark staff datáfono (`firespark` and `PIN_PAD`). A Transbank payment stays on the list.

## Binaries

Add both packages to the merchant kiosk app. Pin them to the same version as `@fire-spark/payments`. Do not add them to the public kiosk template.

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

`binariesDir` is absolute, or relative to the app. It has to look like this:

```text theme={null}
cyc-h2hpos-client-2.6.jar
cyc-h2hpos-caller-eculink-2.5.jar
EcuLink-1.0-SNAPSHOT.jar
jSerialComm-2.11.0.jar
jniLibs/<abi>/libjSerialComm.so
```

```typescript theme={null}
export default {
  plugins: [
    [
      "@fire-spark/payments-transbank-client",
      { binariesDir: process.env.TRANSBANK_BINARIES_DIR }
    ]
  ]
};
```

The plugin copies the JARs into `android/app/libs` and the `.so` files into `jniLibs`. Prebuild fails with `[transbank] missing ...` when a file is absent.

```bash theme={null}
TRANSBANK_BINARIES_DIR=/path/to/the/jars npx expo prebuild --platform android
npx expo run:android --device
```

## Use it in the SDK

Register the adapter once per order. `transbankPinPadPayments()` takes no keys. Each charge reads the context that `PaymentSession` builds from `getKioskConfig`.

```typescript theme={null}
import { transbankPinPadPayments } from "@fire-spark/payments-transbank-pinpad-rn";

order.setPaymentAdapters([transbankPinPadPayments()]);

order.setPaymentOptions({
  isProduction: merchant.env_is_prod,
  collectAt: "KIOSK",
  deviceSettings: kioskConfig.overrides.payment_settings,
  deviceId: kioskConfig.device.id
});
```

`kioskConfig` is what `getKioskConfig` returns. Device values arrive on `overrides.payment_settings`. There are no secrets.

When both modalities are enabled, the adapter calls `ui.select` with the title `Card type` and the options Credit and Debit. Then it calls `ui.message` with `Present the card on the pinpad` and `kind: "waiting"`.

```typescript theme={null}
order.setPaymentUI({
  select: ({ title, options }) => pick(title, options),
  message: ({ text }) => setTerminalMessage(text)
});
```

Cancel on screen aborts the `payIntent` signal. That only works before the native call starts. A sale already on the pinpad is not aborted.

Charge the payment the customer picked:

```typescript theme={null}
await order.setTenders([
  {
    method: "PIN_PAD",
    provider: "transbank",
    payment_id: payment.id,
    collect_at: "DEVICE",
    allocation: null
  }
]);

const result = await order.payIntent({
  onProgress: progress => render(progress)
});
```

An approved sale comes back `PENDING` with `metadata.confirm_after_inject`. The core confirms it after the order is injected. Do not confirm before that.

The adapter window is 180 seconds. Leave `runtime.timeout_ms` unset to keep it. A shorter value on the payment replaces it.

Currency has to be CLP. Any other currency returns `INVALID_REQUEST` and does not call the pinpad.

## What the customer sees

The card-type choice, when both modalities are on, then the waiting message. On `PAID`, print `metadata.receipt.customer` and `metadata.receipt.merchant`. Both are the `VOUCHER` text. Do not URL-decode it.

| Result | What the kiosk does |
| - | - |
| `PENDING` with `confirm_after_inject` | Inject the order. The core confirms and the result becomes `PAID` |
| `PAID` | Print the voucher and continue the order |
| `CANCELLED` | The customer aborted before the sale started, or the reverse was approved |
| `FAILED` with `CARD_DECLINED` | The card was declined. Allow a retry |
| `FAILED` with `UNKNOWN` | The pinpad rejected the sale (`TXCRET` other than `00`). Do not retry when `needs_review` is set |
| `FAILED` with `TERMINAL_NOT_CONFIGURED` | A field or the native module is missing. Do not retry at checkout |
| `FAILED` with `INVALID_REQUEST` | The currency is not CLP |
| `REFUNDED` | The refund and its confirm were approved |

## Webhooks

None.

## Voids

The core picks the reversal with the adapter `reversalFor`. A sale still `PENDING` (the order was not injected) is reversed with `procesaReversa()`. The core does this on its own. A `PAID` sale is undone with a refund (`devolucion`) and then a confirm (`confirmacion()`). `order.cancel()` runs it on an order that is not delivered. `order.refund()` runs it on a delivered order.

| Result | What the kiosk does |
| - | - |
| `CANCELLED` | The reverse was approved |
| `REFUNDED` | The refund and its confirm were approved |
| `FAILED` with `needs_review` | Confirm or reverse did not finish. Do not start another charge |

## Common errors

| Spark code | When | What to do |
| - | - | - |
| `CARD_DECLINED` | `TXCRET` is `00` and `AUTRET` is outside `001`–`009` | Offer a retry or another method |
| `UNKNOWN` | `TXCRET` is not `00`, including `20`, or the native call threw | Do not retry when `needs_review` is set |
| `TERMINAL_NOT_CONFIGURED` | A field is missing or the native module is absent | Check [Activate it](#activate-it) and [Binaries](#binaries) |
| `INVALID_REQUEST` | Currency is not CLP | Charge in CLP |

## Compatibility

| `@fire-spark/payments-transbank-pinpad-rn` | Provider | `@fire-spark/payments` |
| - | - | - |
| 0.17.x | Hasar H2H client 2.6, caller 2.5 | 0.17.2 |

## AI agent prompt

Paste this into the agent that edits the kiosk app. It covers only Transbank Hasar H2H. The sections above are the same work, written for a person.

```text title="Integration prompt" theme={null}
Integrate only the Transbank Hasar H2H pinpad into this Fire spark kiosk app. Do not add any other payment provider. Do not add these packages to POS, web, iOS, or the public kiosk template. Register them in the merchant Android kiosk app.

Transbank charges a card on a Hasar pinpad in Chile (CLP). One dashboard payment is one checkout button. The kiosk template already renders one card per payment from services.payments.list (CheckoutPaymentMethodCard). Do not create a new button component. The kiosk writes Download/SDKChile/spdh40.properties. The JAR talks to the pinpad on /dev/ttyACM0. This is not POS Integrado and not the PAX IM30.

Checkout button:
- paymentInstructionKind treats a PIN_PAD payment as a card, unless that payment is Pix only. Transbank modalities are CREDIT and DEBIT, so the template shows the card illustration. The label is payment.name. Do not special-case Transbank as Pix. There is no helper like isPixOnlyPayment.
- useCheckoutPayments hides only the Fire spark staff datáfono (provider firespark and method PIN_PAD). Leave a Transbank payment on the list.
- Both modalities on one payment: the customer picks one in ui.select before the pinpad starts. Title is "Card type". Options are Credit and Debit. Show those strings as they arrive, in English. If select rejects, the pinpad does not start.
- One modality: there is no picker. Go straight to the waiting message.
- Credit and debit as their own buttons: a second payment with a single modality, for example modalities: ["DEBIT"]. Both cards show the card illustration.

Packages, pinned to the same version as @fire-spark/payments:
- @fire-spark/payments-transbank-client@0.17.2 (Android module and Expo config plugin)
- @fire-spark/payments-transbank-pinpad-rn@0.17.2 (adapter)

Native setup:
- Expo Go cannot load the module. Use a development build.
- In app.config.ts add the plugin ["@fire-spark/payments-transbank-client", { binariesDir: process.env.TRANSBANK_BINARIES_DIR }].
- Binaries stay outside git. The folder holds cyc-h2hpos-client-2.6.jar, cyc-h2hpos-caller-eculink-2.5.jar, EcuLink-1.0-SNAPSHOT.jar, jSerialComm-2.11.0.jar, and jniLibs/<abi>/libjSerialComm.so. Do not commit those files.
- Generate Android with TRANSBANK_BINARIES_DIR set: npx expo prebuild --platform android.
- The plugin copies the JARs into android/app/libs and the .so files into jniLibs. Prebuild stops with "[transbank] missing ..." when a file is absent.
- The kiosk must be able to write Download/SDKChile. The pinpad is on /dev/ttyACM0.

Register once per order. transbankPinPadPayments() takes no keys. Each charge reads the context that PaymentSession builds from getKioskConfig. There are no secrets.

import { transbankPinPadPayments } from "@fire-spark/payments-transbank-pinpad-rn";

order.setPaymentAdapters([transbankPinPadPayments()]);

order.setPaymentOptions({
  isProduction: merchant.env_is_prod,
  collectAt: "KIOSK",
  deviceSettings: kioskConfig.overrides.payment_settings,
  deviceId: kioskConfig.device.id
});

kioskConfig is what getKioskConfig returns. Device values arrive on overrides.payment_settings.

The adapter draws nothing. Implement setPaymentUI:
- select: only when the payment has both CREDIT and DEBIT. Title "Card type". Options Credit and Debit. Resolve with the chosen value. Reject when the customer cancels. If select rejects, the pinpad does not start.
- message: show the latest text. "Present the card on the pinpad" with kind "waiting". Return nothing.
- There is no input, confirm, or QR.

Cancel on screen aborts the payIntent signal. That only works before the native call starts. A sale already on the pinpad is not aborted.

Charge only through transbankPinPadPayments(). Do not call the native client to sell. Do not build spdh40.properties in the app. Do not URL-decode the voucher.

Charge the payment the customer picked:

await order.setTenders([{
  method: "PIN_PAD",
  provider: "transbank",
  payment_id: payment.id,
  collect_at: "DEVICE",
  allocation: null
}]);
const result = await order.payIntent({ onProgress: progress => render(progress) });

The charge window is 180 seconds. Leave runtime.timeout_ms unset. A shorter value on the payment replaces it and cuts the sale. Currency must be CLP. Any other currency returns INVALID_REQUEST and does not call the pinpad.

Results:
- PENDING with metadata.confirm_after_inject: the card authorized. Inject the order. The core confirms after injection and the result becomes PAID. Do not confirm before that.
- PAID: print metadata.receipt.customer and metadata.receipt.merchant. Both are the VOUCHER text. Do not URL-decode it. Continue the order. Authorization, brand, and last 4 are on result.metadata.payment. Do not store them yourself.
- CANCELLED: the customer aborted before the sale started, or the reverse was approved. Return to the method list and do not show an error.
- FAILED with CARD_DECLINED: the card was declined. Allow a retry.
- FAILED with UNKNOWN: the pinpad rejected the sale (TXCRET other than 00, including 20) or the native call threw. Do not retry when needs_review is set.
- FAILED with TERMINAL_NOT_CONFIGURED: a field or the native module is missing. Do not retry at checkout.
- FAILED with INVALID_REQUEST: the currency is not CLP.
- REFUNDED: the refund and its confirm were approved.

Voids: the core picks the reversal with reversalFor. A PENDING sale (order not injected) is reversed with procesaReversa, by the core on its own. A PAID sale is undone with a refund (devolucion) and then a confirm. order.cancel() runs it on an order that is not delivered, order.refund() on a delivered order. Do not call the adapter or the native client from the app yourself.
- CANCELLED: the reverse was approved.
- REFUNDED: the refund and its confirm were approved.
- FAILED with needs_review: confirm or reverse did not finish. Do not start another charge.

Errors to handle: CARD_DECLINED (TXCRET 00 and AUTRET outside 001-009), UNKNOWN (TXCRET other than 00, including 20, or the native call threw), TERMINAL_NOT_CONFIGURED (missing field or native module), INVALID_REQUEST (currency is not CLP).

Dashboard values are filled by a person, not invented by you. Provider Transbank, method PIN pad. Payment config: hostname (ECULINK.HOSTNAME), port (digits, ECULINK.PORTNUMBER), timeout_ms (digits, ECULINK.TIMEOUT), deliver_bin (S or N), self_service (S or N), modalities (CREDIT, DEBIT, or both; at least one). Per store: eculink_ip, local (TXC.LOCAL), store_name, store_address, store_city. Per kiosk, settings_overrides.payment_settings[paymentId]: terminal_id (TBS.TERMINALID), retailer_id (Maxpoint idCaja, not a commerce code), register_number (TXC.CAJA, separate from retailer_id). All of them are required. A payment missing a store or device field does not appear at checkout. There are no secrets.
```


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