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

> Charge a card on a Redeban datáfono from the kiosk with @fire-spark/payments-redeban-pinpad. The kiosk calls SIPConnector over HTTPS.

Redeban runs the datáfono on Fire spark kiosks in Colombia. One dashboard payment is one checkout button. The kiosk calls SIPConnector over HTTPS, and the datáfono picks the sale up from that cloud. Your kiosk draws the waiting message the adapter sends.

| | |
| - | - |
| Countries | Colombia |
| Currencies | COP |
| Status | Available |
| Package | `@fire-spark/payments-redeban-pinpad` |

Kiosk only. POS, web, and iOS do not use this package. There is no native module, Expo config plugin, or binary.

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 kiosk that already charges with `@fire-spark/core` (`setPaymentAdapters`, `setPaymentOptions`, `payIntent`).
* The merchant payment filled in the dashboard: service URL, unique code, user, password, and supervisor password.
* On each kiosk: terminal code, register number, and cashier code. All three have to be saved. If one is missing, the API does not send the payment and the button stays off the checkout.

## Activate it

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

| Field | Key | Secret | Notes |
| - | - | - | - |
| Service URL | `base_url` | No | HTTPS URL of SIPConnector |
| Unique code | `codigo_unico` | No | Incocredito code, 1 to 10 digits. Keep the leading zeros |
| User | `usuario` | No | Service user |
| Password | `secret_clave` | Yes | Service password |
| Supervisor password | `secret_supervisor_password` | Yes | 4 digits. Used only to void a sale |

There are no per-store settings. These values are shared by every Redeban datáfono of the merchant.

3. 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 code | `terminal_id` | No | Datáfono terminal code, up to 10 characters |
| Register number | `register_number` | No | Register number, up to 10 characters |
| Cashier code | `cashier_code` | No | Cashier code, up to 10 characters |

> [!NOTE]
>
> A payment that is missing a device field never reaches the kiosk, so its button stays off the checkout. On the device list, the **Payments** column shows what is still empty.

## Checkout button

Each Redeban 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.

Redeban has no modalities. `paymentInstructionKind` treats a `PIN_PAD` payment as a card, so the template shows the card illustration. The package is not part of the public template. Add it in the merchant kiosk app. `useCheckoutPayments` hides only the Fire spark staff datáfono (`firespark` and `PIN_PAD`). A Redeban payment stays on the list.

## Use it in the SDK

Add the package to the kiosk app. It is not part of the public template. Pin it to the same version as `@fire-spark/payments`.

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

There is no Expo config plugin and no prebuild step for this payment.

Register the adapter once per order. `redebanPinPadPayments()` takes no URL and no keys. Each charge reads the context that `PaymentSession` builds from `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` is what `getKioskConfig` returns. Device values arrive on `overrides.payment_settings`. The authenticated config includes `secret_clave` and `secret_supervisor_password`. The public storefront list strips those secrets. Each `start` asks SIPConnector for a new token. The token lasts 3 minutes. Leave it in the adapter.

The adapter draws nothing. When the charge starts it calls `ui.message` with the text `Present the card on the pinpad` and `kind: "waiting"`.

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

| Method | When it arrives | What you return |
| - | - | - |
| `message` | `Present the card on the pinpad` | Nothing. Show that text, with a cancel control |

Cancel aborts the `payIntent` signal. The kiosk does not call Borrar and does not build the sale frame.

| When the customer cancels | What comes back |
| - | - |
| Before the datáfono takes the sale | `CANCELLED` |
| After the card is already in (last code `02`) | The charge continues. If the window ends: `FAILED` with `AMBIGUOUS` |

Charge the payment the customer picked:

```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 })` still places one tender. To split Redeban with another method, call `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).

The charge window is 370 seconds. It covers two poll phases of 184 seconds. Leave `runtime.timeout_ms` unset to keep that window. A value on the payment replaces it, so a shorter one cuts the sale in half.

`order.getMissingPaymentFields(payment)` lists device fields that are still empty. The API already hides an incomplete payment. Use the helper on the kiosk admin screen when you want to show what is missing.

## What the customer sees

The waiting message and a cancel control. On `PAID`, continue the order. The authorization code, brand, last 4 digits, receipt number, and terminal are on `result.metadata.payment`. There is no customer receipt text to print. The kiosk does not store them itself.

| Result | What the kiosk does |
| - | - |
| `PAID` | Continue the order |
| `CANCELLED`, or `FAILED` with `CANCELLED_BY_USER` | Return to the method list and do not show an error |
| `FAILED` with `CARD_DECLINED` | The card was declined. Allow a retry |
| `FAILED` with `TIMEOUT` or `TERMINAL_BUSY` | The datáfono is unavailable. Retry only when `error.retryable` is true |
| `FAILED` with `TERMINAL_NOT_CONFIGURED` | Device or payment fields are missing. Do not retry at checkout |
| `FAILED` with `AMBIGUOUS` and `needs_review` | Do not retry. Send the customer to the counter |
| `FAILED` with `INVALID_REQUEST` and `needs_review` | The approved total does not match the order. Do not retry and do not void it by hand |

`AMBIGUOUS` is the error code, not a status. The status stays `FAILED`. The text comes from `formatPaymentError` in `@fire-spark/payments`.

## Webhooks

None.

## Voids

`order.cancel()` voids an order that was not fulfilled. `order.refund()` refunds one that was. `reversalFor` always returns `cancel`, so both run the adapter's full void. There is no partial refund, and the adapter has no `refund` operation.

The void sends the stored receipt and `secret_supervisor_password` from the payment. The kiosk does not ask for that password.

| Result | What the kiosk does |
| - | - |
| `CANCELLED` | The void was approved on the datáfono |
| `FAILED` with `AMBIGUOUS` | The void did not finish. Do not start another charge with the same transaction id |
| `FAILED` with `CARD_DECLINED` | The datáfono refused the void. Leave it for the counter |

## Common errors

| Spark code | Provider code | What to do |
| - | - | - |
| `CANCELLED_BY_USER` | — | The customer cancelled before the datáfono took the sale. Return to the methods |
| `CARD_DECLINED` | Financial code other than `00` | The datáfono declined the card. Offer a retry or another method |
| `TERMINAL_BUSY` | `06` | The terminal already has a transaction. Retry when `error.retryable` is true |
| `TERMINAL_NOT_CONFIGURED` | — | A payment or device field is missing. Check [Activate it](#activate-it) |
| `TIMEOUT` | — | The datáfono did not take the sale before the window ended. Retry when `error.retryable` is true |
| `AMBIGUOUS` | Last code `02`, or the window ended after the pinpad started | Leave it for review. See [Payment errors](https://firespark.cloud/docs/guides/payments/errors.md) |
| `INVALID_REQUEST` | `03`, `05`, `08`, `09`, `12`, `18` | The request was rejected, or the approved total does not match (`needs_review`). Do not retry a mismatched total, and do not void it by hand |
| `INVALID_CREDENTIALS` | `07`, `16` | The unique code or the password was rejected. Fix the payment in [Activate it](#activate-it) |
| `NETWORK_ERROR` | — | SIPConnector did not answer. Retry when `error.retryable` is true |
| `PROVIDER_UNAVAILABLE` | `10`, `11`, `14`, `99` | SIPConnector could not store the sale. Retry when `error.retryable` is true |

## Compatibility

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

## AI agent prompt

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

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

Redeban charges a card on a datáfono in Colombia (COP). The kiosk does not talk to the pinpad. It calls SIPConnector over HTTPS, and the datáfono picks the sale up from that cloud. 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.

Redeban has no modalities. paymentInstructionKind treats a PIN_PAD payment as a card, so the template shows the card illustration. useCheckoutPayments hides only the Fire spark staff datáfono (provider firespark and method PIN_PAD). Leave a Redeban payment on the list. Do not special-case Redeban as Pix.

Package, pinned to the same version as @fire-spark/payments:
- @fire-spark/payments-redeban-pinpad@0.12.5

There is no native module, Expo config plugin, binary, or prebuild step. Charge only through redebanPinPadPayments(). Pass no URL and no keys. Do not build an HTTP client. Do not talk to the datáfono over USB, Bluetooth, or a native SDK. Each start asks for a new token (it lasts 3 minutes). Do not store secret_clave, secret_supervisor_password, or the token.

Register once per order:

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 is what getKioskConfig returns. Device values arrive on overrides.payment_settings.

The adapter draws nothing. Implement setPaymentUI.message and show the text as it arrives: "Present the card on the pinpad" (kind "waiting"). Return nothing. There is no select, input, confirm, or QR. Put a cancel control on that screen. Cancel aborts the payIntent signal. Do not call Borrar and do not build the sale frame.
- Cancel before the datáfono takes the sale: status CANCELLED.
- Cancel after the card is in (last code 02): the charge continues. If the window ends, the result is FAILED with AMBIGUOUS. Do not erase a transaction whose last code was 02.
- A Cod 00 with no financial frame means the pinpad has not answered yet. Do not treat it as PAID.

Charge the payment the customer picked:

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

The charge window is 370 seconds (two poll phases of 184 seconds). Leave runtime.timeout_ms unset. A shorter value cuts the sale in half.

Results:
- PAID: continue the order. Authorization code, brand, last 4, receipt number, and terminal are on result.metadata.payment. There is no customer receipt text to print. Do not store them yourself.
- CANCELLED, or FAILED with CANCELLED_BY_USER: return to the method list and do not show an error.
- FAILED with CARD_DECLINED: the card was declined. Allow a retry.
- FAILED with TIMEOUT or TERMINAL_BUSY: the datáfono is unavailable. Retry only when error.retryable is true.
- FAILED with TERMINAL_NOT_CONFIGURED: do not retry at checkout.
- FAILED with AMBIGUOUS and needs_review: do not retry. Send the customer to the counter. AMBIGUOUS is the error code. The status stays FAILED.
- FAILED with INVALID_REQUEST and needs_review: the approved total does not match the order. Do not retry and do not void it by hand.

Voids: order.cancel() for an order that was not fulfilled, order.refund() for one that was. reversalFor always returns "cancel", so both run the adapter's full void. There is no partial refund, and the adapter has no refund operation. Do not implement one. The void sends the stored receipt and secret_supervisor_password from the payment. The kiosk does not ask for that password.
- CANCELLED: the void was approved on the datáfono.
- FAILED with AMBIGUOUS: the void did not finish. Do not start another charge with the same transaction id.
- FAILED with CARD_DECLINED: the datáfono refused the void. Leave it for the counter.

Errors to handle: CANCELLED_BY_USER, CARD_DECLINED (financial code other than 00), TERMINAL_BUSY (06), TERMINAL_NOT_CONFIGURED, TIMEOUT, AMBIGUOUS (last code 02, or the window ended after the pinpad started), INVALID_REQUEST (03, 05, 08, 09, 12, 18, or a mismatched total), INVALID_CREDENTIALS (07, 16), NETWORK_ERROR, PROVIDER_UNAVAILABLE (10, 11, 14, 99).

Dashboard values are filled by a person, not invented by you. Provider Redeban, method PIN pad. Payment config: base_url (HTTPS), codigo_unico (1 to 10 digits; keep the leading zeros; 0010203040 and 10203040 are different merchants), usuario, secret_clave, secret_supervisor_password (4 digits, voids only). No per-store settings. Per kiosk, settings_overrides.payment_settings[paymentId]: terminal_id, register_number, cashier_code. All three are required. A payment missing one does not appear at checkout. order.getMissingPaymentFields(payment) lists what is still empty. Do not reuse IdTransaccion. The adapter takes it from attemptReference.
```


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