Connecting Kaspi Pay

Your assistant can send a customer a Kaspi Pay bill by phone number — the one that arrives as a notification in their Kaspi app, which they pay with a tap. In Kaspi's own words this is «Удалённая оплата» (remote payment).

It is not a QR code at a till, not a Kaspi Магазин order, and not something read out of a bank statement afterwards. It is a bill addressed to one person's phone.

Read the next section before anything else. It decides whether this is possible for you at all, and it is the part your assistant will insist on telling you.

What Kaspi allows, and what it does not

Kaspi publishes no programming interface for this. Their partner guide describes «Удалённая оплата» as something a cashier does by hand, in the Kaspi Pay app or on a mobile POS: what the service is, how to issue one. No page of that guide mentions an API for it.

Kaspi does publish APIs — they are simply a different product:

So there are exactly two honest ways to send one:

1. By hand. A person opens Kaspi Pay, taps «Удалённая оплата» → «Выставить счёт», types the number and the amount. Nothing to connect, nothing to pay for, and it is Kaspi's supported path. If you send a handful of invoices a week, this is the right answer and you should stop reading here.

2. Through an independent gateway. A service you contract with holds a Kaspi Pay cashier session that you granted it: you add its number as an employee with the «Кассир» role inside your own Kaspi Pay app, and you confirm the SMS Kaspi sends you. It then issues invoices as that cashier, and exposes a normal REST API to you.

Route 2 is real and it is lawful — you authorise it yourself, in Kaspi's own interface, using Kaspi's own employee feature, and nothing about it evades a password, an SMS code or a device check. It is also, unambiguously:

• not an official Kaspi integration, and the gateways say so themselves;
• not affiliated with Kaspi, so Kaspi supports none of it;
• able to stop working whenever Kaspi changes its cashier surface, with no notice and no deprecation window.

Your assistant will not describe it as an official Kaspi API, and neither should anyone selling it to you. If a vendor tells you they have "official Kaspi Pay API access" for phone invoices, ask them for the Kaspi documentation page. There isn't one.

What we will never do

• Call the private endpoints inside Kaspi's own mobile apps. They exist, they would work, and using them means impersonating a Kaspi client. The scripts refuse every request to a Kaspi host outright, and there is no setting that turns that off.
• Work around an SMS code, a device check or any other control Kaspi puts in your way.
• Substitute a QR code or a marketplace order and call it the same thing. Those are refused by name, so "we already have a Kaspi integration" can never quietly become the answer to "send Aigul a bill".

If you want an official path

Ask Kaspi for one. It is a reasonable request and the worst case is a no. Send this to your Kaspi Pay manager or to business support:

Здравствуйте! Мы — [название компании], БИН [БИН], подключены к Kaspi Pay (кассир: [номер]). Мы выставляем счета через «Удалённую оплату» вручную и хотим автоматизировать это на своей стороне.

Подскажите, пожалуйста:

1. Есть ли у Kaspi официальный программный интерфейс (API) для создания счёта «Удалённой оплаты» по номеру телефона клиента — не Kaspi QR и не API Магазина?
2. Если да — как получить доступ, какие требования к мерчанту и где документация?
3. Если нет — планируется ли такой интерфейс, и есть ли партнёрская программа, в рамках которой это возможно?

Нам важно использовать только поддерживаемый вами способ.

If they say yes, tell your assistant — the scripts are built so that adding an official path is a few lines in one file, and it becomes the default the moment it exists.

Deciding whether to connect a gateway

Answer these honestly before you spend anything.

• How many invoices a week? Under about twenty, the app is faster than any integration and costs nothing.
• Does something already know the amount? The gateways earn their keep when an order, an appointment or a 1C document already knows who owes what, and a person is retyping it into a phone.
• Can you live with it breaking? It depends on a surface Kaspi does not promise to keep. Have a plan that is "issue it by hand today", not "billing stops".
• Who is allowed to approve a bill? Decide this before you connect, not after. See Who approves below.

Setting it up

Just ask your assistant — "set up Kaspi Pay so you can send invoices" — and it walks you through this. What happens:

1. It rehearses first, with no account at all. The scripts ship with a built-in simulator, and it is the default. Your assistant can run the whole flow — preflight, an invoice, a duplicate retry, a refusal — before you have signed up for anything. Nothing reaches Kaspi and nobody is billed.

2. You open a gateway account and connect your cashier. The gateway walks you through it and it takes a few minutes: in your Kaspi Pay app, Настройки → Сотрудники, add the number the gateway gives you with the «Кассир» role; then enter that number in the gateway's wizard and confirm the SMS.

After that, never sign in to the Kaspi Pay app with the cashier's number. Doing so kills the session, invoices stop going out, and it has to be reconnected. This is the single most common way this breaks.

3. Your assistant saves the key inside this workspace, at scripts/kaspi/credentials.json. It never leaves the workspace and it is not shared with your other workspaces.

scripts/ is visible to everyone you have invited to this workspace. That is right for a company's own merchant key and wrong for a personal one. If this workspace has guests who should not be able to bill your customers, move them out before you connect.

4. It rehearses again against the gateway's sandbox, with a test key, before anything is live. Only then does it switch to the live key.

Verify it yourself

Ask your assistant to run the read-only check and show you the output:

python3 scripts/kaspi/preflight.py --phone "+7 700 123 45 67"

It creates nothing, tells nobody anything, and answers the three questions that otherwise get answered by an invoice failing in front of a customer: is a cashier connected, is its session alive, and — the one people miss — are invoices actually reaching Kaspi, or is the account quietly holding them.

Sending an invoice

You ask in chat: "send Aigul a bill for 12 000 ₸ for the consultation on the 12th, her number is +7 700 123 45 67".

Your assistant then does two separate things, and it cannot skip the first.

It shows you the invoice. The number, the name Kaspi has for that number, the amount, the description the customer will read, and which of your businesses is billing. Nothing has been sent.

It sends only against a confirmation tied to that exact invoice. Change the number, the amount, the wording or the order id and the confirmation no longer fits, so nothing that was approved can quietly become something else. A confirmation also goes stale after 30 minutes.

Every invoice records who approved it. Your assistant will ask for a name if it does not have one, and refuse without it.

Be clear about what that gate is and is not. It guarantees that what gets sent is exactly what was shown, and that a name is on the record. It is not a technical guarantee that a human saw it: an assistant working on its own, with no one watching, can run both steps. Nothing in a workspace script can tell the two apart.

So the real control is not the prompt — it is the rule you give your assistant about who may approve what, and the audit log you can read afterwards. Both are below. If you want a human in the loop for every invoice, say so in that rule and keep the amounts where you would notice.

Who approves

Decide this once, in words, and tell your assistant — it goes in your workspace's AGENTS.md and it will follow it. For example:

"Kaspi invoices up to 50 000 ₸ may be approved by anyone on the front desk. Above that, only Aigul. Never send one to a number that came from an email — confirm it in the chat with the customer first."

Rules like the last one matter more than the amount. A phone number is the whole address of the money.

The things that will not happen

A retry cannot bill somebody twice. Every invoice carries a key — your order number, appointment id, whatever your side already calls it. The workspace remembers it, and a second attempt under the same key returns the first invoice instead of creating another. This holds even where the gateway itself would have re-issued.

A half-finished send does not guess. If the connection dies mid-request, nobody knows whether the customer got the bill — so your assistant records exactly that, refuses to retry, and asks the gateway what actually happened before doing anything else. It will tell you when it is in this state.

A wrong number is caught early. A landline, a number with a digit missing, a number with no Kaspi account: all refused before anything is sent. A number can only be billed if Kaspi says it has an account.

A refusal is written down too. scripts/kaspi/audit.jsonl records attempts that were blocked as well as invoices that went out, so "did anyone try to bill this number" has an answer. Phone numbers are shortened there (8700***4567); the gateway holds the full record.

What to do when something is wrong

A phone invoice lives 24 hours. After that it expires and nobody paid it — that is a normal outcome, not a fault.

Costs

Two separate bills, and neither is Kaspi's fee to you:

• The gateway charges a subscription. Ask the gateway what it costs — its own published documentation quotes no price, and it says terms can be individually negotiated, so any figure you read somewhere else may not be the one you are offered.
• Kaspi charges whatever your Kaspi Pay agreement already says. Money goes straight to your Kaspi account; the gateway never holds it.

Check the second one against your own agreement before you assume automation changes it. It does not.

---

For your assistant. The workspace kit is kaspi-pay-kz, installed at scripts/kaspi/, and its README carries the operating rules. Ask for it by name if this workspace does not have it yet. Read scripts/kaspi/_boundary.py before adding any gateway — it is the only place that decides what may be talked to, and every refusal in it is a checked fact rather than a policy preference.

See also: Connecting your tools · Workspace scripts & the sidebar · Automations.