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

# CliSiTef

> Charge debit, credit, voucher, and Pix on a CliSiTef pinpad from the Android kiosk with @fire-spark/payments-clisitef-pinpad-rn.

CliSiTef (Software Express) runs the pinpad on Fire spark kiosks in Brazil. One dashboard payment is one checkout button. The adapter talks to the pinpad; your kiosk draws the prompts it sends.

| | |
| - | - |
| Countries | Brazil |
| Currencies | BRL |
| Status | Available |
| Package | `@fire-spark/payments-clisitef-pinpad-rn` |

Android kiosk only. POS, web, and iOS do not use this package.

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 with the pinpad on USB.
* A development build. Expo Go does not load the native module.
* The CliSiTef binaries for that environment (homologation or production), from Software Express. Keep them outside git.

> [!WARNING]
>
> The binaries and a production `CLSIT` file stay out of the repository. The kiosk template is public, and Software Express licenses the binaries.

## Activate it

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

| Field | Key | Secret | Notes |
| - | - | - | - |
| Modalities | `modalities` | No | `DEBIT`, `CREDIT`, `VOUCHER`, or `PIX`. At least one. See [Checkout button](#checkout-button) |
| CNPJ Enterprise | `cnpj_enterprise` | No | Company CNPJ registered with SiTef, 14 digits |
| Operator | `operator` | No | Optional. When omitted, the adapter sends `KIOSKO_BR` |
| Restrictions by modality | `restrictions_by_modality` | No | Optional. Hides CliSiTef menu options for one modality, such as installments on credit |

3. In **Store settings**, fill in each store. The API sends the kiosk only its own store row.

| Field | Key | Secret | Notes |
| - | - | - | - |
| SiTef IP | `sitef_ip` | No | SiTef server of the store |
| Store code | `store_code` | No | SiTef store code, 8 characters |
| Store CNPJ | `cnpj_store` | No | Store CNPJ. The adapter strips punctuation |
| Supervisor password | `secret_supervisor_password` | Yes | Optional. Used on a void when the device has none. A device value wins |

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 number | `terminal_number` | No | SiTef terminal assigned to this kiosk |
| Supervisor password | `secret_supervisor_password` | Yes | Optional. Automatic voids send it. When it is empty, the adapter asks with `ui.input` |

`pinpad_type` is not on the form. When you omit it, the client uses `ANDROID_USB`. To use Bluetooth or auto-detect, set `pinpad_type` to `ANDROID_BT` or `ANDROID_AUTO` on the same device settings with the [Update kiosk device](https://firespark.cloud/docs/integrations-api/kiosk/devices/put.md) endpoint.

> [!NOTE]
>
> A payment that is missing store or device fields 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 CliSiTef payment is one button. The kiosk template already renders one card per payment from `services.payments.list`. You do not add a button component.

* Several modalities on one payment: the customer picks one before the pinpad starts. The adapter asks through `ui.select`, with the title `Selecione a forma de pagamento` and the options `Débito`, `Crédito`, `Voucher`, and `Pix`. Closing the picker rejects the promise and the pinpad does not start.
* Pix as its own button: create a second payment with `modalities: ["PIX"]`. It sits next to card and cash. The template treats a payment whose only modality is `PIX` as Pix (`isPixOnlyPayment` in the checkout helpers) and shows the Pix illustration. Any other `PIN_PAD` payment shows the card illustration.

> [!NOTE]
>
> Pix is a transfer: the customer pays by QR from their bank. The QR and the result still go through the CliSiTef native binaries (`@fire-spark/payments-clisitef-client`), the same module as debit and credit. Pix is a `PIX` modality of this payment. It cannot run on its own, and it is not a separate `BANK_TRANSFER` method.

Debit and voucher share one CliSiTef function. Restrictions are what separate them. A credit restriction list on voucher makes SiTef reject the charge.

## Use it in the SDK

Add both packages to the kiosk app. They are not part of the public template. Pin them to the same version as `@fire-spark/payments`.

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

`@fire-spark/payments-clisitef-client` is the Android module and the Expo config plugin. `@fire-spark/payments-clisitef-pinpad-rn` is the adapter. Charge through the adapter: it confirms, undoes, and recovers a transaction after a restart.

In `app.config.ts`:

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

`binariesDir` is absolute, or relative to the app root. Point it at a folder outside git:

```text theme={null}
binaries/
  clisitef-android.jar
  jniLibs/
    arm64-v8a/
      libclisitef.so
```

Then generate the Android project:

```bash theme={null}
CLISITEF_BINARIES_DIR=/path/to/binaries npx expo prebuild --platform android --clean
```

The plugin copies the JAR and the `.so` files, turns on `useLegacyPackaging` (Android 14 and later will not load a compressed `libclisitef.so`), and adds the internet and Bluetooth permissions. Prebuild stops with `[clisitef] missing ...` when the JAR or `libclisitef.so` is absent.

Register the adapter once per order, with device storage. Pass `storage` every time: a transaction that debit left open stays visible to credit, and the app can undo it after a restart. Software Express allows one client instance. The adapter already uses the shared one.

```typescript theme={null}
import AsyncStorage from "@react-native-async-storage/async-storage";
import { clisitefPinPadPayments } from "@fire-spark/payments-clisitef-pinpad-rn";

const deviceStorage = {
  get: (key: string) => AsyncStorage.getItem(key),
  set: (key: string, value: string) => AsyncStorage.setItem(key, value),
  remove: (key: string) => AsyncStorage.removeItem(key)
};

order.setPaymentAdapters([
  clisitefPinPadPayments({ storage: deviceStorage })
]);

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. Prompts arrive on `setPaymentUI`. Show the CliSiTef text as it arrives, in Portuguese.

```typescript theme={null}
order.setPaymentUI({
  message: ({ text }) => setTerminalMessage(text),
  select: ({ title, options }) => openPicker(title, options),
  input: ({ label, type }) => openInput(label, type),
  confirm: ({ text }) => openYesNo(text),
  action: ({ type, payload }) => {
    if (type !== "qr") return;
    if (payload) showQr(payload);
    else hideQr();
  }
});
```

| Method | When it arrives | What you return |
| - | - | - |
| `message` | "Insira o cartão", "Digite a senha", "Aguarde" | Nothing. Several arrive in a row: show the latest |
| `select` | The modality, the voucher network, or a SiTef menu the adapter leaves open | A promise of the chosen `value`. Reject it when the customer cancels |
| `input` | A value SiTef asks for, including the supervisor password | A promise of the text. `type: "password"` is masked |
| `confirm` | A yes or no question | A promise of `true` or `false` |
| `action` | The Pix QR | Nothing. See the contract below |

Pix QR contract:

```typescript theme={null}
{ type: "qr", payload: "00020126...", format: "text", expiresAt: null } // show
{ type: "qr", payload: "" } // hide
```

`payload` is the Pix copy-and-paste text. Draw it as a QR code. An empty `payload` hides it, and so does the end of `payIntent`. `expiresAt` is `null`: SiTef does not send an expiry, and the charge window is 180 seconds. Messages keep arriving under the QR. The cancel control rejects the flow promise.

Charge the payment the customer picked:

```typescript theme={null}
await order.setTenders([
  {
    method: "PIN_PAD",
    provider: "clisitef",
    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 CliSiTef 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 180 seconds. It covers pinpad table load, the modality choice, the card, and the PIN. Leave `runtime.timeout_ms` unset to keep that window. A value on the payment replaces it, so set `180000` or higher. To raise the adapter default, pass `timeoutMs`:

```typescript theme={null}
clisitefPinPadPayments({ storage: deviceStorage, timeoutMs: 240_000 });
```

`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 pinpad message, the modality picker when the payment has more than one, and the Pix QR. On `PAID`, print `metadata.receipt.customer` (plain text, the customer copy) and continue the order. On `FAILED` with `CANCELLED_BY_USER`, return to the method list without an error. On `AMBIGUOUS` (`metadata.needs_review`), leave the charge as it is: the card may already have been read, or the QR may already have been shown. Send the customer to the counter.

NSU, authorization code, brand, last 4 digits, and the fiscal coupon are on `result.metadata.payment`. Pix has no brand and no last 4 (`entry_mode: "QR"`). The kiosk does not store them itself.

## Webhooks

None.

## Voids

`order.cancel()` voids an order that was not fulfilled. `order.refund()` refunds one that was. Each one voids the pinpad charges and calls its endpoint once.

| Modality | CliSiTef function |
| - | - |
| Credit | 210 |
| Debit and voucher | 211 |
| Pix | 123 |

The adapter sends the amount, the date, the host NSU, and the supervisor password (`secret_supervisor_password` on the device, otherwise on the store). When neither is set, it asks with `ui.input` (`type: "password"`). Keep `setPaymentUI` mounted for the void.

| Result | What the kiosk does |
| - | - |
| `REFUNDED` or `CANCELLED` | The void finished. Print `metadata.provider.void.receipt.customer` when it is present |
| `PAID` with `needs_review` and a retryable error | The void is queued. Tell the customer to go to the counter. From the kiosk admin screen, run `order.runPaymentTerminal(payment, "retry_pending_reversals")` |
| `PAID` with `REVERSAL_NOT_ALLOWED` or `MANUAL_REVERSAL_REQUIRED` | SiTef refused the void, or a field was missing (host NSU, date, or modality). Void it from the SiTef admin menu |

## Common errors

| Spark code | Provider code | What to do |
| - | - | - |
| `CANCELLED_BY_USER` | `-2`, `-6`, `-15` | The customer cancelled on the pinpad or closed your prompt. Return to the methods |
| `CARD_DECLINED` | `-40` and other positive codes | SiTef or the authorizer declined. Offer a retry or another method |
| `TERMINAL_BUSY` | `-12` | A routine is still open. The next charge aborts it and retries `configure` once |
| `TERMINAL_NOT_CONFIGURED` | — | Store or device fields are missing, or `init` failed (IP, store, or terminal). Check [Activate it](#activate-it) |
| `WALLET_REJECTED` | `-24` | Pix is not enabled for this store in SiTef. Remove `PIX` from `modalities`, or ask operations to enable it |
| `TIMEOUT` | `CLISITEF_TIMEOUT` | The 180 second window ended. Set `runtime.timeout_ms` to `180000` or higher |
| `AMBIGUOUS` | — | The link dropped after the card was read or the QR was shown. Leave it for review. See [Payment errors](https://firespark.cloud/docs/guides/payments/errors.md) |

## Compatibility

| `@fire-spark/payments-clisitef-pinpad-rn` | Provider | `@fire-spark/payments` |
| - | - | - |
| 0.11.0 | CliSiTef (Software Express), Android | Same version as `@fire-spark/payments-clisitef-client` |

## AI agent prompt

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

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

CliSiTef (Software Express) charges debit, credit, voucher, and Pix on a USB pinpad in Brazil (BRL). 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.

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

Charge only through clisitefPinPadPayments. Do not call the native client, finishTransaction, or abortTransaction yourself. The adapter confirms, undoes, and recovers a transaction after a restart. Software Express allows one client instance; the adapter already uses the shared one.

Native setup:
- Expo Go cannot load the module. Use a development build.
- In app.config.ts add the plugin ["@fire-spark/payments-clisitef-client", { binariesDir: process.env.CLISITEF_BINARIES_DIR }].
- Binaries stay outside git (Software Express license). The folder holds clisitef-android.jar and jniLibs/<abi>/libclisitef.so. Do not commit binaries or a production CLSIT file.
- Generate Android with CLISITEF_BINARIES_DIR set: npx expo prebuild --platform android --clean.
- The plugin copies the JAR and .so files, turns on useLegacyPackaging, and adds internet and Bluetooth permissions. Prebuild stops with "[clisitef] missing ..." when the JAR or libclisitef.so is absent.

Register once per order. Always pass device storage (AsyncStorage). Without it, a transaction debit left open is invisible to credit and cannot be undone after a restart.

import AsyncStorage from "@react-native-async-storage/async-storage";
import { clisitefPinPadPayments } from "@fire-spark/payments-clisitef-pinpad-rn";

const deviceStorage = {
  get: (key: string) => AsyncStorage.getItem(key),
  set: (key: string, value: string) => AsyncStorage.setItem(key, value),
  remove: (key: string) => AsyncStorage.removeItem(key)
};

order.setPaymentAdapters([
  clisitefPinPadPayments({ storage: deviceStorage })
]);

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 and show CliSiTef text as it arrives, in Portuguese:
- message: show the latest text ("Insira o cartão", "Digite a senha", "Aguarde"). Return nothing.
- select: modality picker, voucher network, or a SiTef menu. Resolve with the chosen value. Reject when the customer cancels. Title for modalities is "Selecione a forma de pagamento". Options are Débito, Crédito, Voucher, Pix.
- input: resolve with the text. type "password" is masked (supervisor password). type "number" is an amount.
- confirm: resolve with true or false.
- action: Pix QR. { type: "qr", payload, format: "text", expiresAt: null } shows the QR. payload is the Pix copy-and-paste text; draw it as a QR, not an image. payload "" hides it. Also hide it when payIntent finishes. expiresAt is null. The charge window is 180 seconds. Keep showing message text under the QR. The cancel control rejects the flow promise.

Checkout button:
- Several modalities on one payment: the customer picks one in ui.select before the pinpad starts. If select rejects, the pinpad does not start.
- Pix on its own button: a second payment with modalities: ["PIX"]. The template treats that payment as Pix via isPixOnlyPayment and shows the Pix illustration. Any other PIN_PAD payment shows the card illustration.
- Pix is a transfer (the customer pays by QR from their bank) but the QR and the result go through the CliSiTef native binaries, the same module as debit and credit. It is a PIX modality of provider "clisitef" and method "PIN_PAD". Do not implement Pix as BANK_TRANSFER or as a separate package.
- Debit and voucher share one CliSiTef function and are separated by restrictions_by_modality. Do not copy a credit restriction list onto voucher.

Charge the payment the customer picked:

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

The charge window is 180 seconds (pinpad table load, modality, card, PIN). Leave runtime.timeout_ms unset. If it is set, use 180000 or higher. Raise the adapter default with clisitefPinPadPayments({ storage: deviceStorage, timeoutMs: 240_000 }).

Results:
- PAID: print metadata.receipt.customer (plain text, customer copy) and continue the order.
- FAILED CANCELLED_BY_USER: return to the method list and do not show an error.
- AMBIGUOUS (metadata.needs_review): do not retry. The card may already have been read or the QR shown. Send the customer to the counter.
- NSU, authorization code, brand, last 4, and the fiscal coupon are on result.metadata.payment. Pix has no brand and no last 4 (entry_mode "QR"). Do not store them yourself.

Voids: order.cancel() for an order that was not fulfilled, order.refund() for one that was. Keep setPaymentUI mounted. CliSiTef functions: credit 210, debit and voucher 211, Pix 123. The adapter sends amount, date, host NSU, and secret_supervisor_password (device value wins over the store). If neither password is set, it asks with ui.input type "password".
- REFUNDED or CANCELLED: print metadata.provider.void.receipt.customer when present.
- PAID with needs_review and a retryable error: the void is queued. From the kiosk admin screen run order.runPaymentTerminal(payment, "retry_pending_reversals").
- PAID with REVERSAL_NOT_ALLOWED or MANUAL_REVERSAL_REQUIRED: a person voids it in the SiTef admin menu.

Errors to handle: CANCELLED_BY_USER (-2, -6, -15), CARD_DECLINED (-40 and other positive codes), TERMINAL_BUSY (-12; the next charge aborts and retries configure once), TERMINAL_NOT_CONFIGURED (missing store or device fields), WALLET_REJECTED (-24; Pix is not enabled for the store), TIMEOUT (CLISITEF_TIMEOUT; the 180 second window ended), AMBIGUOUS (do not retry).

Dashboard values are filled by a person, not invented by you. Provider CliSiTef, method PIN pad. Payment config: modalities (DEBIT, CREDIT, VOUCHER, PIX; at least one), cnpj_enterprise (14 digits), optional operator (default KIOSKO_BR), optional restrictions_by_modality. Per store: sitef_ip, store_code (8 characters), cnpj_store. Per kiosk, settings_overrides.payment_settings[paymentId]: terminal_number (required), optional secret_supervisor_password. pinpad_type is optional and defaults to ANDROID_USB (also ANDROID_BT, ANDROID_AUTO). A payment missing store or device fields is hidden from checkout. order.getMissingPaymentFields(payment) lists what is still empty.
```


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