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

> Cobra con tarjeta en un pinpad Transbank Hasar H2H desde el kiosco Android con @fire-spark/payments-transbank-pinpad-rn.

Transbank Hasar H2H es el pinpad de los kioscos de Fire spark en Chile. Un pago del dashboard es un botón del checkout. El kiosco escribe un archivo de propiedades y el JAR de Hasar habla con el pinpad por el puerto serial. Tu kiosco dibuja el aviso de espera que envía el adaptador.

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

Solo kiosco Android. POS, web e iOS no usan este paquete. No es POS Integrado ni el POS Autoservicio PAX IM30.

Sigue las secciones de abajo para integrarlo a mano. Para dárselo a un agente, copia el prompt de [Prompt para un agente](#prompt-para-un-agente).

## Requisitos

* Un kiosco Android que ya cobra con `@fire-spark/core` (`setPaymentAdapters`, `setPaymentOptions`, `payIntent`).
* Un development build. Expo Go no carga el módulo nativo.
* Los binarios de Hasar, fuera de git. El pinpad va en `/dev/ttyACM0`.
* El kiosco puede escribir `Download/SDKChile`.

> [!WARNING]
>
> No commitees los cuatro JAR ni `libjSerialComm.so`. La app del kiosco apunta el config plugin a un `binariesDir` de la máquina de build.

## Activarlo

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

| Campo | Clave | Secreto | Notas |
| - | - | - | - |
| Hostname | `hostname` | No | `ECULINK.HOSTNAME` |
| Port | `port` | No | Dígitos. `ECULINK.PORTNUMBER` |
| Timeout (ms) | `timeout_ms` | No | Dígitos. `ECULINK.TIMEOUT` |
| Deliver BIN | `deliver_bin` | No | `S` o `N` |
| Self service | `self_service` | No | `S` o `N` |
| Modalities | `modalities` | No | `CREDIT`, `DEBIT` o ambos. Al menos una. Ver [Botón del checkout](#botón-del-checkout) |

3. En cada tienda, agrega los ajustes de tienda:

| Campo | Clave | Notas |
| - | - | - |
| EcuLink IP | `eculink_ip` | IP del pinpad en la red de la tienda |
| Local | `local` | `TXC.LOCAL` |
| Store name | `store_name` | Encabezado del voucher |
| Store address | `store_address` | Encabezado del voucher |
| Store city | `store_city` | Encabezado del voucher |

4. En cada kiosco, abre el dispositivo y la pestaña **Payments**. Los valores viven en `settings_overrides.payment_settings`, con el id del pago como clave. Ver [Configurar un dispositivo](https://firespark.cloud/docs/es/guides/payments/configure-a-device.md).

| Campo | Clave | Secreto | Notas |
| - | - | - | - |
| Terminal ID | `terminal_id` | No | `TBS.TERMINALID` |
| Retailer ID | `retailer_id` | No | Id de caja de Maxpoint (`idCaja`). No es un código de comercio |
| Register number | `register_number` | No | `TXC.CAJA`. Distinto del retailer id |

> [!NOTE]
>
> Un pago al que le falta un campo de tienda o de dispositivo no llega al kiosco, así que su botón no sale en el checkout.

## Botón del checkout

Cada pago Transbank es un botón. El template del kiosco ya pinta una tarjeta por pago a partir de `services.payments.list` (`CheckoutPaymentMethodCard`). No agregas un componente de botón.

`paymentInstructionKind` trata un pago `PIN_PAD` como tarjeta, salvo que ese pago sea solo Pix. Las modalidades de Transbank son `CREDIT` y `DEBIT`, así que el template muestra la ilustración de tarjeta. El texto del botón es `payment.name`.

* Las dos modalidades en un pago: el cliente elige una antes de que arranque el pinpad. El adaptador pregunta con `ui.select`, título `Card type` y opciones `Credit` y `Debit`. Muestra esas cadenas tal como llegan. Si cierra el selector, la promesa se rechaza y el pinpad no arranca. Después el adaptador llama `ui.message` con `Present the card on the pinpad` y `kind: "waiting"`.
* Una sola modalidad: no hay selector. El cobro pasa directo al aviso de espera.
* Crédito y débito en botones propios: crea un segundo pago con una sola modalidad, por ejemplo `modalities: ["DEBIT"]`. Queda al lado del primero. Los dos muestran la ilustración de tarjeta. No hay un helper de Transbank como `isPixOnlyPayment`. No trates Transbank como Pix.

Los paquetes no forman parte del template público. Agrégalos en la app de kiosco del comercio. `useCheckoutPayments` oculta solo el datáfono de personal de Fire spark (`firespark` y `PIN_PAD`). Un pago Transbank se queda en la lista.

## Binarios

Agrega los dos paquetes a la app del kiosco del comercio. Fíjalos a la misma versión que `@fire-spark/payments`. No los agregues al template público del kiosco.

```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` es absoluta o relativa a la app. Tiene que verse así:

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

El plugin copia los JAR a `android/app/libs` y las `.so` a `jniLibs`. El prebuild falla con `[transbank] missing ...` si falta un archivo.

```bash theme={null}
TRANSBANK_BINARIES_DIR=/ruta/a/los/jar npx expo prebuild --platform android
npx expo run:android --device
```

## Usarlo en el SDK

Registra el adaptador una vez por orden. `transbankPinPadPayments()` no recibe llaves. Cada cobro lee el contexto que arma `PaymentSession` desde `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` es lo que devuelve `getKioskConfig`. Los valores del dispositivo llegan en `overrides.payment_settings`. No hay secretos.

Si las dos modalidades están activas, el adaptador llama `ui.select` con el título `Card type` y las opciones Credit y Debit. Después llama `ui.message` con `Present the card on the pinpad` y `kind: "waiting"`.

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

Cancelar en pantalla aborta la señal de `payIntent`. Eso solo vale antes de que empiece la llamada nativa. Una venta que ya está en el pinpad no se aborta.

Cobra el pago que eligió el cliente:

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

Una venta aprobada vuelve `PENDING` con `metadata.confirm_after_inject`. El core la confirma después de inyectar la orden. No la confirmes antes.

El plazo del adaptador es 180 segundos. Deja `runtime.timeout_ms` vacío para conservarlo. Un valor más corto en el pago lo reemplaza.

La moneda tiene que ser CLP. Cualquier otra devuelve `INVALID_REQUEST` y no llama al pinpad.

## Qué ve el cliente

La elección de tipo de tarjeta, cuando van las dos modalidades, y después el aviso de espera. En `PAID`, imprime `metadata.receipt.customer` y `metadata.receipt.merchant`. Los dos son el texto de `VOUCHER`. No lo decodifiques.

| Resultado | Qué hace el kiosco |
| - | - |
| `PENDING` con `confirm_after_inject` | Inyecta la orden. El core confirma y el resultado pasa a `PAID` |
| `PAID` | Imprime el voucher y sigue con la orden |
| `CANCELLED` | El cliente abortó antes de empezar, o la reversa fue aprobada |
| `FAILED` con `CARD_DECLINED` | La tarjeta fue rechazada. Permite reintentar |
| `FAILED` con `UNKNOWN` | El pinpad rechazó la venta (`TXCRET` distinto de `00`). No reintentes si viene `needs_review` |
| `FAILED` con `TERMINAL_NOT_CONFIGURED` | Falta un campo o el módulo nativo. No reintentes en el checkout |
| `FAILED` con `INVALID_REQUEST` | La moneda no es CLP |
| `REFUNDED` | La devolución y su confirmación fueron aprobadas |

## Webhooks

Ninguno.

## Anulaciones

El core elige la reversa con `reversalFor` del adaptador. Una venta que sigue `PENDING` (la orden no se inyectó) se reversa con `procesaReversa()`. Eso lo hace el core solo. Una venta `PAID` se deshace con una devolución (`devolucion`) y después una confirmación (`confirmacion()`). `order.cancel()` la corre en una orden no entregada. `order.refund()` la corre en una orden entregada.

| Resultado | Qué hace el kiosco |
| - | - |
| `CANCELLED` | La reversa fue aprobada |
| `REFUNDED` | La devolución y su confirmación fueron aprobadas |
| `FAILED` con `needs_review` | La confirmación o la reversa no terminó. No empieces otro cobro |

## Errores comunes

| Código Spark | Cuándo | Qué hacer |
| - | - | - |
| `CARD_DECLINED` | `TXCRET` es `00` y `AUTRET` está fuera de `001`–`009` | Ofrece reintentar u otro método |
| `UNKNOWN` | `TXCRET` no es `00`, incluido `20`, o la llamada nativa lanzó | No reintentes si viene `needs_review` |
| `TERMINAL_NOT_CONFIGURED` | Falta un campo o el módulo nativo | Revisa [Activarlo](#activarlo) y [Binarios](#binarios) |
| `INVALID_REQUEST` | La moneda no es CLP | Cobra en CLP |

## Compatibilidad

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

## Prompt para un agente

Pega esto en el agente que edita la app del kiosco. Cubre solo Transbank Hasar H2H. Las secciones de arriba son el mismo trabajo, escrito para una persona.

```text title="Prompt de integración" theme={null}
Integra solo el pinpad Transbank Hasar H2H en esta app de kiosco de Fire spark. No agregues ningún otro proveedor de pagos. No agregues estos paquetes a POS, web, iOS ni al template público del kiosco. Regístralos en la app Android del comercio.

Transbank cobra una tarjeta en un pinpad Hasar en Chile (CLP). Un pago del dashboard es un botón del checkout. El template del kiosco ya pinta una tarjeta por pago a partir de services.payments.list (CheckoutPaymentMethodCard). No crees un componente de botón. El kiosco escribe Download/SDKChile/spdh40.properties. El JAR habla con el pinpad en /dev/ttyACM0. No es POS Integrado ni el PAX IM30.

Botón del checkout:
- paymentInstructionKind trata un pago PIN_PAD como tarjeta, salvo que ese pago sea solo Pix. Las modalidades de Transbank son CREDIT y DEBIT, así que el template muestra la ilustración de tarjeta. El texto del botón es payment.name. No trates Transbank como Pix. No hay un helper como isPixOnlyPayment.
- useCheckoutPayments oculta solo el datáfono de personal de Fire spark (proveedor firespark y método PIN_PAD). Deja el pago Transbank en la lista.
- Las dos modalidades en un pago: el cliente elige una en ui.select antes de que arranque el pinpad. El título es "Card type". Las opciones son Credit y Debit. Muestra esas cadenas tal como llegan, en inglés. Si select se rechaza, el pinpad no arranca.
- Una sola modalidad: no hay selector. Pasa directo al aviso de espera.
- Crédito y débito en botones propios: un segundo pago con una sola modalidad, por ejemplo modalities: ["DEBIT"]. Las dos tarjetas muestran la ilustración de tarjeta.

Paquetes, fijados a la misma versión que @fire-spark/payments:
- @fire-spark/payments-transbank-client@0.17.2 (módulo Android y config plugin de Expo)
- @fire-spark/payments-transbank-pinpad-rn@0.17.2 (adaptador)

Setup nativo:
- Expo Go no carga el módulo. Usa un development build.
- En app.config.ts agrega el plugin ["@fire-spark/payments-transbank-client", { binariesDir: process.env.TRANSBANK_BINARIES_DIR }].
- Los binarios se quedan fuera de git. La carpeta tiene cyc-h2hpos-client-2.6.jar, cyc-h2hpos-caller-eculink-2.5.jar, EcuLink-1.0-SNAPSHOT.jar, jSerialComm-2.11.0.jar y jniLibs/<abi>/libjSerialComm.so. No commitees esos archivos.
- Genera Android con TRANSBANK_BINARIES_DIR definido: npx expo prebuild --platform android.
- El plugin copia los JAR a android/app/libs y las .so a jniLibs. El prebuild se detiene con "[transbank] missing ..." si falta un archivo.
- El kiosco tiene que poder escribir Download/SDKChile. El pinpad va en /dev/ttyACM0.

Registra una vez por orden. transbankPinPadPayments() no recibe llaves. Cada cobro lee el contexto que arma PaymentSession desde getKioskConfig. No hay secretos.

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 es lo que devuelve getKioskConfig. Los valores del dispositivo llegan en overrides.payment_settings.

El adaptador no dibuja nada. Implementa setPaymentUI:
- select: solo cuando el pago tiene CREDIT y DEBIT. Título "Card type". Opciones Credit y Debit. Resuelve con el value elegido. Rechaza si el cliente cancela. Si select se rechaza, el pinpad no arranca.
- message: muestra el último texto. "Present the card on the pinpad" con kind "waiting". No devuelve nada.
- No hay input, confirm ni QR.

Cancelar en pantalla aborta la señal de payIntent. Eso solo vale antes de que empiece la llamada nativa. Una venta que ya está en el pinpad no se aborta.

Cobra solo con transbankPinPadPayments(). No llames al cliente nativo para vender. No armes spdh40.properties en la app. No decodifiques el voucher.

Cobra el pago que eligió el cliente:

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

El plazo del cobro es de 180 segundos. Deja runtime.timeout_ms vacío. Un valor más corto en el pago lo reemplaza y corta la venta. La moneda tiene que ser CLP. Cualquier otra devuelve INVALID_REQUEST y no llama al pinpad.

Resultados:
- PENDING con metadata.confirm_after_inject: la tarjeta autorizó. Inyecta la orden. El core confirma después de inyectarla y el resultado pasa a PAID. No confirmes antes.
- PAID: imprime metadata.receipt.customer y metadata.receipt.merchant. Los dos son el texto de VOUCHER. No lo decodifiques. Sigue con la orden. La autorización, la marca y los últimos 4 están en result.metadata.payment. No los guardes por tu cuenta.
- CANCELLED: el cliente abortó antes de empezar, o la reversa fue aprobada. Vuelve a la lista de métodos y no muestres un error.
- FAILED con CARD_DECLINED: la tarjeta fue rechazada. Permite reintentar.
- FAILED con UNKNOWN: el pinpad rechazó la venta (TXCRET distinto de 00, incluido 20) o la llamada nativa lanzó. No reintentes si viene needs_review.
- FAILED con TERMINAL_NOT_CONFIGURED: falta un campo o el módulo nativo. No reintentes en el checkout.
- FAILED con INVALID_REQUEST: la moneda no es CLP.
- REFUNDED: la devolución y su confirmación fueron aprobadas.

Anulaciones: el core elige la reversa con reversalFor. Una venta PENDING (la orden no se inyectó) se reversa con procesaReversa, la hace el core solo. Una venta PAID se deshace con una devolución (devolucion) y después una confirmación. order.cancel() la corre en una orden no entregada, order.refund() en una orden entregada. No llames el adaptador ni el cliente nativo desde la app.
- CANCELLED: la reversa fue aprobada.
- REFUNDED: la devolución y su confirmación fueron aprobadas.
- FAILED con needs_review: la confirmación o la reversa no terminó. No empieces otro cobro.

Errores a manejar: CARD_DECLINED (TXCRET 00 y AUTRET fuera de 001-009), UNKNOWN (TXCRET distinto de 00, incluido 20, o la llamada nativa lanzó), TERMINAL_NOT_CONFIGURED (falta un campo o el módulo nativo), INVALID_REQUEST (la moneda no es CLP).

Los valores del dashboard los llena una persona; no los inventes. Proveedor Transbank, método PIN pad. Config del pago: hostname (ECULINK.HOSTNAME), port (dígitos, ECULINK.PORTNUMBER), timeout_ms (dígitos, ECULINK.TIMEOUT), deliver_bin (S o N), self_service (S o N), modalities (CREDIT, DEBIT o ambos; al menos una). Por tienda: eculink_ip, local (TXC.LOCAL), store_name, store_address, store_city. Por kiosco, settings_overrides.payment_settings[paymentId]: terminal_id (TBS.TERMINALID), retailer_id (idCaja de Maxpoint, no es un código de comercio), register_number (TXC.CAJA, distinto de retailer_id). Todos son obligatorios. Un pago al que le falta un dato de tienda o de dispositivo no aparece en el checkout. No hay secretos.
```


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