Card acquiring in Kazakhstan (Kaspi and Halyk) — Paloma POS 2

This article is about Paloma POS 2 — the new Paloma cash-register app. It covers taking card payments in Kazakhstan through Kaspi and Halyk terminals: connecting a payment device, paying by card and by QR, what Tap2Pay is, choosing a terminal at payment time, and what to do on a decline or timeout. If you are not sure which product you have, start with «How to tell you have Paloma POS 2». The general payment flow is described in «Taking payment».

Overview

Card payment in Kazakhstan runs through a payment device (terminal) bound to the register. Paloma POS 2 supports several Kazakhstani integrations:

• Kaspi — a Kaspi terminal (in settings the variants «Kaspi v2» and «Kaspi v3»).
• Halyk — several connection types: «Halyk PAX» and «Halyk (HTTP)» (a physical terminal), «Halyk QR» (pay by QR code), «Halyk Tap2Pay (SoftPOS)» (accept a card by tapping the phone) and «Halyk restaurant».

The terminal itself is set up once by an administrator in the hardware section. After that the cashier just taps «Card» on the payment screen — the register sends the amount to the terminal. If there is more than one terminal, the register asks which one to use. All amounts are calculated exactly; on a decline or timeout no money is charged and the order stays open.

For the fiscal receipt (OFD, the QR on the receipt), see «Fiscalization in Kazakhstan». For receipt printing, see «Printers and receipt printing».

Connecting a payment terminal

An administrator does this on the device the terminal is attached to:

1. Open «Settings» → «Devices» → «Payment devices».
2. Tap «Add device».
3. Pick a provider — for example «Kaspi v2», «Kaspi v3», «Halyk PAX», «Halyk (HTTP)», «Halyk QR» or «Halyk Tap2Pay (SoftPOS)».
4. Fill in the connection fields (each provider has its own — for example a network terminal needs a terminal address and port, a cloud one needs identifiers and keys from the bank portal).
5. Bind a payment type to the device. If you skip this, the device row reads «Not bound to any payment type» and card payment through it will not work.
6. Tap «Save».

A Kaspi/Halyk terminal is set up once. If you do not know the connection details, take them from the bank portal or message us here — a specialist will join.

Halyk restaurant pairing

For the «Halyk restaurant» variant the bank issues a one-time pairing code:

1. First choose the responsible workplace and bind a payment type to the terminal (otherwise the register prompts you to do this before pairing).
2. In the device card, enter the bank code in the «Pairing code» field (at least 6 characters — a shorter code is rejected).
3. Tap «Save». The register contacts the bank and shows the result; on success — «Pairing established.».

If the bank returns an error, the register tells you what to do: check the code and payment type, sign in again, or request a new pairing code from the bank.

Paying by card on a terminal

1. On the order card tap «Pay order», then «Card».
2. If several terminals are bound, the «Choose a payment terminal» dialog opens — pick the one you need (the default terminal is marked «Default»).
3. The register sends the amount and shows «Insert card / processing...». The customer taps or inserts the card.
4. Wait for the terminal to respond. On success the «Payment complete» screen appears.

Do not remove the card or close the screen while it is processing. If the terminal declines, the order stays open — retry or take another tender.

Paying by QR (Halyk QR)

For the «Halyk QR» variant the customer pays by scanning a QR code in their bank app:

1. Tap «Pay order» → «Card» and, if needed, pick the QR terminal.
2. The register shows «Scan to pay» with the hint «Show the QR to the customer and wait for the payment».
3. The customer scans the QR and confirms in their app.
4. Once the bank confirms, the register closes the check — the «Payment complete» screen appears.

A QR refund works the same way: the register shows «Scan to refund».

Tap-to-pay (Halyk Tap2Pay)

«Halyk Tap2Pay (SoftPOS)» turns the register's own phone or terminal into a contactless card reader — no separate device is needed. The customer taps a card or phone against the register device and the payment goes through like a normal card payment. On the payment screen tap «Card» and present the card when the register shows «Insert card / processing...».

Common problems

• «No terminals available» in the terminal picker — no payment terminal is bound. Connect one in «Settings» → «Devices» → «Payment devices», or take cash.
• «Not bound to any payment type» on a device row — the terminal is added but has no payment type bound. Open it and bind one, or card payment through it will not work.
• «You do not have permission to take card payments.» — the employee lacks the card-payment right. An administrator sets rights.
• «Card terminal error. Please try again.» — the terminal returned an error. No money was charged; retry or take cash.
• «Card declined. Please try a different card or pay cash.» — the bank declined the customer's card. Try another card or cash.
• «Card payment cancelled.» — the operation was cancelled on the terminal. The order stays open — retry.
• «Card terminal timed out. Check the device or batch report before retrying.» — the terminal did not answer in time. Before retrying, check on the terminal or the batch report whether the payment went through, so you do not charge twice.
• «Card payment failed: terminal offline» — the terminal is off or on another network. Check that it is on and on the same network as the register. No money was charged — retry or take cash.
• «Card payment failed: no network» — the register could not resolve the terminal address. Check the register's network connection. No money was charged — retry or take cash.
• «Payments are blocked on the terminal…» — a third-party Kaspi Kassa app is running on top of the integration. Close it, or contact the provider's support.
• «The terminal hasn't finished the previous operation…» — an operation is stuck on the terminal. Finish or cancel it on the device, then retry.

FAQ

What is the difference between Kaspi v2 and Kaspi v3?

They are two versions of the Kaspi terminal integration. Which one you use depends on your terminal and your bank agreement — the administrator picks the right version («Kaspi v2» or «Kaspi v3») when connecting. For the cashier, taking payment is the same: tap «Card».

How is Halyk QR different from a normal card payment?

With «Halyk QR» the customer does not tap a card on a terminal — they scan a QR code in their bank app and confirm on the phone. No separate physical terminal is needed.

What is Tap2Pay and does it need a terminal?

«Halyk Tap2Pay (SoftPOS)» accepts a contactless card with the register device itself, without a separate terminal. The customer taps a card or phone against the register device and it goes through like a normal card payment.

I have several terminals. How do I choose one at payment time?

After you tap «Card», the register shows the «Choose a payment terminal» dialog with the bound devices; the default is marked «Default». Pick one and the payment goes to it.

The terminal hung or did not respond. Was the card charged?

On a timeout or decline the register does not charge and keeps the order open. But if you see «Card terminal timed out…», first check the terminal or batch report for whether the payment went through, and only then retry — so you do not charge twice.

Can I take part by card and part in cash?

Yes. That is an ordinary mixed payment and works the same for Kaspi and Halyk. The steps are in «Taking payment».