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.
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.
Activate it
- In the dashboard, open your merchant, go to Payments, and create a payment with the provider CliSiTef and the method PIN pad.
- In Connection Settings, fill in:
- In Store settings, fill in each store. The API sends the kiosk only its own store row.
- 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.
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 endpoint.
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 fromservices.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 titleSelecione a forma de pagamentoand the optionsDébito,Crédito,Voucher, andPix. 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 isPIXas Pix (isPixOnlyPaymentin the checkout helpers) and shows the Pix illustration. Any otherPIN_PADpayment shows the card illustration.
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.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.
@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:
binariesDir is absolute, or relative to the app root. Point it at a folder outside git:
.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.
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.
Pix QR contract:
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:
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.
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:
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. OnPAID, 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.
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.
Common errors
Compatibility
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.Integration prompt