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

# Redeban

> Cobra con tarjeta en un datáfono Redeban desde el kiosco con @fire-spark/payments-redeban-pinpad. El kiosco llama a SIPConnector por HTTPS.

Redeban es el datáfono de los kioscos de Fire spark en Colombia. Un pago del dashboard es un botón del checkout. El kiosco llama a SIPConnector por HTTPS y el datáfono toma la venta de esa nube. Tu kiosco dibuja el aviso de espera que envía el adaptador.

| | |
| - | - |
| Países | Colombia |
| Monedas | COP |
| Estado | Disponible |
| Paquete | `@fire-spark/payments-redeban-pinpad` |

Solo kiosco. POS, web e iOS no usan este paquete. No hay módulo nativo, config plugin de Expo ni binario.

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 que ya cobra con `@fire-spark/core` (`setPaymentAdapters`, `setPaymentOptions`, `payIntent`).
* El pago del comercio completo en el dashboard: URL del servicio, código único, usuario, clave y clave de supervisor.
* En cada kiosco: código de terminal, número de caja y código de cajero. Los tres tienen que estar guardados. Si falta uno, la API no manda el pago y el botón no sale en el checkout.

## Activarlo

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

| Campo | Clave | Secreto | Notas |
| - | - | - | - |
| Service URL | `base_url` | No | URL HTTPS del SIPConnector |
| Unique code | `codigo_unico` | No | Código Incocredito, de 1 a 10 dígitos. Conserva los ceros a la izquierda |
| User | `usuario` | No | Usuario del servicio |
| Password | `secret_clave` | Sí | Clave del servicio |
| Supervisor password | `secret_supervisor_password` | Sí | 4 dígitos. Solo se usa para anular una venta |

No hay ajustes por tienda. Estos valores los comparten todos los datáfonos Redeban del comercio.

3. 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 code | `terminal_id` | No | Código de terminal del datáfono, hasta 10 caracteres |
| Register number | `register_number` | No | Número de caja, hasta 10 caracteres |
| Cashier code | `cashier_code` | No | Código de cajero, hasta 10 caracteres |

> [!NOTE]
>
> Un pago al que le falta un dato del dispositivo no llega al kiosco, así que su botón no aparece en el checkout. En el listado de dispositivos, la columna **Payments** muestra lo que sigue vacío.

## Botón del checkout

Cada pago Redeban 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.

Redeban no tiene modalidades. `paymentInstructionKind` trata un pago `PIN_PAD` como tarjeta, así que el template muestra la ilustración de tarjeta. El paquete no forma parte del template público. Agrégalo en la app de kiosco del comercio. `useCheckoutPayments` oculta solo el datáfono de personal de Fire spark (`firespark` y `PIN_PAD`). Un pago Redeban se queda en la lista.

## Usarlo en el SDK

Agrega el paquete a la app del kiosco. No forma parte del template público. Fíjalo a la misma versión que `@fire-spark/payments`.

```bash theme={null}
pnpm add @fire-spark/payments-redeban-pinpad@0.12.5
```

Este pago no tiene config plugin de Expo ni paso de prebuild.

Registra el adaptador una vez por pedido. `redebanPinPadPayments()` no recibe URL ni claves. Cada cobro lee el contexto que arma `PaymentSession` a partir de `getKioskConfig`.

```typescript theme={null}
import { redebanPinPadPayments } from "@fire-spark/payments-redeban-pinpad";

order.setPaymentAdapters([redebanPinPadPayments()]);

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`. La config autenticada incluye `secret_clave` y `secret_supervisor_password`. El listado público del storefront quita esos secretos. Cada `start` pide un token nuevo a SIPConnector. El token dura 3 minutos. Déjalo en el adaptador.

El adaptador no dibuja nada. Al empezar el cobro llama a `ui.message` con el texto `Present the card on the pinpad` y `kind: "waiting"`.

```typescript theme={null}
order.setPaymentUI({
  message: ({ text }) => setTerminalMessage(text)
});
```

| Método | Cuándo llega | Qué devuelves |
| - | - | - |
| `message` | `Present the card on the pinpad` | Nada. Muestra ese texto, con un control para cancelar |

Cancelar aborta la señal de `payIntent`. El kiosco no llama a Borrar y no arma la trama de la venta.

| Cuándo cancela el cliente | Qué vuelve |
| - | - |
| Antes de que el datáfono tome la venta | `CANCELLED` |
| Con la tarjeta ya adentro (último código `02`) | El cobro sigue. Si se vence el plazo: `FAILED` con `AMBIGUOUS` |

Cobra el pago que eligió el cliente:

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

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

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

El plazo del cobro es de 370 segundos. Cubre dos fases de consulta de 184 segundos. Deja `runtime.timeout_ms` sin definir para conservar ese plazo. Un valor en el pago lo reemplaza, así que uno más corto corta la venta a la mitad.

`order.getMissingPaymentFields(payment)` lista los campos del dispositivo que siguen vacíos. La API ya oculta un pago incompleto. Usa el helper en la pantalla de administración del kiosco cuando quieras mostrar qué falta.

## Qué ve el cliente

El aviso de espera y un control para cancelar. En `PAID`, sigue con el pedido. El código de autorización, la marca, los últimos 4 dígitos, el número de recibo y el terminal están en `result.metadata.payment`. No hay texto de vía del cliente para imprimir. El kiosco no los guarda por su cuenta.

| Resultado | Qué hace el kiosco |
| - | - |
| `PAID` | Sigue con el pedido |
| `CANCELLED`, o `FAILED` con `CANCELLED_BY_USER` | Vuelve a la lista de métodos y no muestra un error |
| `FAILED` con `CARD_DECLINED` | La tarjeta fue rechazada. Deja reintentar |
| `FAILED` con `TIMEOUT` o `TERMINAL_BUSY` | El datáfono no está disponible. Reintenta solo si `error.retryable` es verdadero |
| `FAILED` con `TERMINAL_NOT_CONFIGURED` | Faltan datos del dispositivo o del pago. No reintentes en el checkout |
| `FAILED` con `AMBIGUOUS` y `needs_review` | No reintentes. Manda al cliente al mostrador |
| `FAILED` con `INVALID_REQUEST` y `needs_review` | El total aprobado no coincide con el pedido. No reintentes y no anules a mano |

`AMBIGUOUS` es el código del error, no un estado. El estado sigue en `FAILED`. El texto sale de `formatPaymentError` en `@fire-spark/payments`.

## Webhooks

Ninguno.

## Anulaciones

`order.cancel()` anula un pedido que no se entregó. `order.refund()` reembolsa uno que sí. `reversalFor` siempre devuelve `cancel`, así que las dos corren la anulación total del adaptador. No hay devolución parcial, y el adaptador no tiene operación `refund`.

La anulación envía el recibo guardado y `secret_supervisor_password` del pago. El kiosco no pide esa clave.

| Resultado | Qué hace el kiosco |
| - | - |
| `CANCELLED` | La anulación quedó aprobada en el datáfono |
| `FAILED` con `AMBIGUOUS` | La anulación no se cerró. No lances otra compra con el mismo id de transacción |
| `FAILED` con `CARD_DECLINED` | El datáfono rechazó la anulación. Queda para el mostrador |

## Errores comunes

| Código Spark | Código del proveedor | Qué hacer |
| - | - | - |
| `CANCELLED_BY_USER` | — | El cliente canceló antes de que el datáfono tomara la venta. Vuelve a los métodos |
| `CARD_DECLINED` | Código financiero distinto de `00` | El datáfono rechazó la tarjeta. Ofrece reintentar u otro método |
| `TERMINAL_BUSY` | `06` | El terminal ya tiene una transacción. Reintenta si `error.retryable` es verdadero |
| `TERMINAL_NOT_CONFIGURED` | — | Falta un dato del pago o del dispositivo. Revisa [Activarlo](#activarlo) |
| `TIMEOUT` | — | El datáfono no tomó la venta antes de que se acabara el plazo. Reintenta si `error.retryable` es verdadero |
| `AMBIGUOUS` | Último código `02`, o el plazo se acabó después de que el pinpad empezó | Déjalo para revisión. Ver [Errores de pago](https://firespark.cloud/docs/es/guides/payments/errors.md) |
| `INVALID_REQUEST` | `03`, `05`, `08`, `09`, `12`, `18` | El pedido fue rechazado, o el total aprobado no coincide (`needs_review`). No reintentes un total distinto y no lo anules a mano |
| `INVALID_CREDENTIALS` | `07`, `16` | El código único o la clave fueron rechazados. Corrige el pago en [Activarlo](#activarlo) |
| `NETWORK_ERROR` | — | SIPConnector no respondió. Reintenta si `error.retryable` es verdadero |
| `PROVIDER_UNAVAILABLE` | `10`, `11`, `14`, `99` | SIPConnector no pudo guardar la venta. Reintenta si `error.retryable` es verdadero |

## Compatibilidad

| `@fire-spark/payments-redeban-pinpad` | Proveedor | `@fire-spark/payments` |
| - | - | - |
| 0.12.5 | SIPConnector 1.5 | 0.12.5 |

## Prompt para un agente

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

```text title="Prompt de integración" theme={null}
Integra solo el pinpad Redeban en esta app de kiosco de Fire spark. No agregues ningún otro proveedor de pagos. No agregues este paquete a POS, web ni iOS. No lo agregues al template público del kiosco. Regístralo en la app de kiosco del comercio.

Redeban cobra con tarjeta en un datáfono en Colombia (COP). El kiosco no habla con el pinpad. Llama a SIPConnector por HTTPS y el datáfono toma la venta de esa nube. 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 nuevo.

Redeban no tiene modalidades. paymentInstructionKind trata un pago PIN_PAD como tarjeta, así que el template muestra la ilustración de tarjeta. useCheckoutPayments oculta solo el datáfono de personal de Fire spark (proveedor firespark y método PIN_PAD). Deja el pago Redeban en la lista. No lo trates como Pix.

Paquete, fijado a la misma versión que @fire-spark/payments:
- @fire-spark/payments-redeban-pinpad@0.12.5

No hay módulo nativo, config plugin de Expo, binario ni paso de prebuild. Cobra solo con redebanPinPadPayments(). No le pases URL ni claves. No armes un cliente HTTP. No hables con el datáfono por USB, Bluetooth ni un SDK nativo. Cada start pide un token nuevo (dura 3 minutos). No guardes secret_clave, secret_supervisor_password ni el token.

Regístralo una vez por pedido:

import { redebanPinPadPayments } from "@fire-spark/payments-redeban-pinpad";

order.setPaymentAdapters([redebanPinPadPayments()]);

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.message y muestra el texto tal como llega: "Present the card on the pinpad" (kind "waiting"). No devuelve nada. No hay select, input, confirm ni QR. Pon un control para cancelar en esa pantalla. Cancelar aborta la señal de payIntent. No llames a Borrar y no armes la trama de la venta.
- Cancelar antes de que el datáfono tome la venta: estado CANCELLED.
- Cancelar con la tarjeta adentro (último código 02): el cobro sigue. Si se vence el plazo, el resultado es FAILED con AMBIGUOUS. No borres una transacción cuyo último código fue 02.
- Un Cod 00 sin trama financiera significa que el pinpad todavía no respondió. No lo trates como PAID.

Cobra el pago que eligió el cliente:

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

El plazo del cobro es de 370 segundos (dos fases de consulta de 184 segundos). Deja runtime.timeout_ms sin definir. Un valor más corto corta la venta a la mitad.

Resultados:
- PAID: sigue con el pedido. El código de autorización, la marca, los últimos 4, el número de recibo y el terminal están en result.metadata.payment. No hay texto de vía del cliente para imprimir. No los guardes por tu cuenta.
- CANCELLED, o FAILED con CANCELLED_BY_USER: vuelve a la lista de métodos y no muestres un error.
- FAILED con CARD_DECLINED: la tarjeta fue rechazada. Deja reintentar.
- FAILED con TIMEOUT o TERMINAL_BUSY: el datáfono no está disponible. Reintenta solo si error.retryable es verdadero.
- FAILED con TERMINAL_NOT_CONFIGURED: no reintentes en el checkout.
- FAILED con AMBIGUOUS y needs_review: no reintentes. Manda al cliente al mostrador. AMBIGUOUS es el código del error. El estado sigue en FAILED.
- FAILED con INVALID_REQUEST y needs_review: el total aprobado no coincide con el pedido. No reintentes y no anules a mano.

Anulaciones: order.cancel() si el pedido no se entregó, order.refund() si se entregó. reversalFor siempre devuelve "cancel", así que las dos corren la anulación total del adaptador. No hay devolución parcial y el adaptador no tiene operación refund. No implementes una. La anulación envía el recibo guardado y secret_supervisor_password del pago. El kiosco no pide esa clave.
- CANCELLED: la anulación quedó aprobada en el datáfono.
- FAILED con AMBIGUOUS: la anulación no se cerró. No lances otra compra con el mismo id de transacción.
- FAILED con CARD_DECLINED: el datáfono rechazó la anulación. Queda para el mostrador.

Errores a manejar: CANCELLED_BY_USER, CARD_DECLINED (código financiero distinto de 00), TERMINAL_BUSY (06), TERMINAL_NOT_CONFIGURED, TIMEOUT, AMBIGUOUS (último código 02, o el plazo se acabó después de que el pinpad empezó), INVALID_REQUEST (03, 05, 08, 09, 12, 18, o un total distinto), INVALID_CREDENTIALS (07, 16), NETWORK_ERROR, PROVIDER_UNAVAILABLE (10, 11, 14, 99).

Los valores del dashboard los llena una persona; no los inventes. Proveedor Redeban, método PIN pad. Config del pago: base_url (HTTPS), codigo_unico (de 1 a 10 dígitos; conserva los ceros a la izquierda; 0010203040 y 10203040 son comercios distintos), usuario, secret_clave, secret_supervisor_password (4 dígitos, solo anulaciones). No hay ajustes por tienda. Por kiosco, settings_overrides.payment_settings[paymentId]: terminal_id, register_number, cashier_code. Los tres son obligatorios. Un pago al que le falta uno no aparece en el checkout. order.getMissingPaymentFields(payment) lista lo que sigue vacío. No reutilices IdTransaccion. El adaptador lo saca de attemptReference.
```


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