Connect Kaspi Pay with an AI assistant

Pick your agent: Claude Code, Codex, Claude or ChatGPT. It takes you from the sandbox to your first real payment: it prepares the account and keys, writes the integration code and checks payments, webhooks and refunds.

The plugin's skills work in Claude (claude.ai, the app, Cowork), Claude Code and Codex. ChatGPT in a browser gets only the xPayment tools, no skills.

Get started

Pick your agent and say whether you have a Kaspi Pay cashier. The page shows your path and a ready message for your assistant.

No Kaspi cashier

Claude, Claude Code, Codex

Connect payments through xPayment. I don't have a Kaspi Pay cashier yet, so start in the sandbox: a test key, the test cashbox, a test webhook. Write the integration in my project and run payments, every outcome, webhooks and refunds. Keep keys in .env and never print them in your reply.

ChatGPT

Help me accept Kaspi Pay payments through xPayment. Use the xPayment tools and start with whoami. I don't have a Kaspi Pay cashier yet, so work only in the sandbox (environment: sandbox): issue a test key xapi_test_…, create a test webhook subscription, create a test payment, set the outcomes paid, declined, expired and failed with simulate_test_payment, and check refunds. Show the result as a table. Do nothing on live. Ask one question at a time.

Another agent

Connect Kaspi Pay through the xPayment API v2 in my project. The documentation in one file: https://xpayment.kz/llms-full.txt, the API description: https://xpayment.kz/openapi/xpayment-api-v2.json. I don't have a Kaspi Pay cashier yet, so we work in the sandbox: I will take the test key xapi_test_… and the cashbox test in the cabinet (Sandbox → Keys) and put the key into .env myself, so don't ask me to paste it into the chat. Write the client and the webhook handler (signature check, idempotency) and check payments, every outcome and refunds with POST /v2/sandbox/payments/PAYMENT_ID/simulate.

With a Kaspi cashier

Claude, Claude Code, Codex

Connect payments through xPayment. I already have a Kaspi Pay cashier. First run the full cycle in the sandbox, then take me to live: the cashbox, the webhook and the key. Live keys and secrets only through one-time links, live actions only after my yes.

ChatGPT

Help me accept Kaspi Pay payments through xPayment. Use the xPayment tools and start with whoami. I already have a Kaspi Pay cashier. First run the full cycle in the sandbox (environment: sandbox), then help me connect the cashbox and set up the live webhook and key. Hand over live keys and secrets only through a one-time link and never show them in the chat. Deleting, revoking and refunding a real payment only after my explicit yes. Never create live payments. Ask one question at a time.

Another agent

Connect Kaspi Pay through the xPayment API v2 in my project. The documentation in one file: https://xpayment.kz/llms-full.txt, the API description: https://xpayment.kz/openapi/xpayment-api-v2.json. My Kaspi Pay cashbox is already connected in the xPayment cabinet. First check everything in the sandbox with a test key xapi_test_…, then prepare the switch to live: the key, device_name and the webhook secret. I will put the keys into .env myself, so don't ask me to paste them into the chat. Write the client and the webhook handler (signature check, idempotency).

Two paths to a working integration

Without a Kaspi cashier you start right away, in the sandbox. With one you run the same sandbox and then go live. The badges show who does what.

No Kaspi cashier: The sandbox: build and test without money

Free and open right after sign-up. No Kaspi cashier, plan or money needed; the addresses, requests and answers are the same as on live.

  1. Sign up for xPayment (You do it): Registration by SMS is on the «Войти через xPayment» page. The sandbox needs no plan and no Kaspi cashier.
  2. Connect the assistant (You do it): Sign in with xPayment and press Allow on the consent page: it lists the rights the assistant asks for.
  3. A test key and a webhook (The AI does it): The assistant issues a key xapi_test_… and a test webhook subscription. In your project it writes the values to .env without printing them.
  4. The integration code (The AI does it): A client and a webhook handler in your stack: X-Idempotency-Key, a signature check on the raw body, a repeated delivery_id is not processed twice, the payment is fetched after each event.
  5. Payments and outcomes (The AI does it): A payment is created the way your customers will create it. An outcome is set for each case: paid, declined, expired, failed.
  6. Webhooks (The AI does it): The whole delivery is checked: a valid signature gets a 2xx answer, a wrong one gets 401; the order in your project changes status.
  7. Refunds and errors (The AI does it): A test refund completes by itself; a refund of exactly 13.13 is always declined; the phones …7000000001 and …7000000002 give Kaspi errors.
  8. The report (The AI does it): A short table of what was checked and fixed. For live you only need to connect the cashbox.

Without a public address, webhooks cannot reach a server on your computer: the assistant suggests a tunnel (recommended) or locally signed checks.

The sandbox has no static QR, online booking, recurring payments or subscriptions. The limit is 60 test writes a minute and 1000 a day. Test payments are kept for 30 days.

With a Kaspi cashier: From the sandbox to the first real payment

First the same cycle in the sandbox, then the live cashbox, webhook and key. What only you can do is marked.

  1. A cashier in the Kaspi Pay app (You do it): A separate cashier with restricted rights: accepting payments and its own history only, no transfers. It needs its own phone number. The assistant cannot do this for you.
  2. The plan (You do it): The assistant checks the plan; you choose and pay. The first 3 days are free, then a fixed plan.
  3. The cashbox in xPayment (The AI does it, You do it, Needs your yes): The assistant starts the connection, Kaspi sends an SMS code to the cashier's phone, and you give the code. A cashbox beyond your plan is paid: the assistant names the price and waits for your yes.
  4. The sandbox (The AI does it): The same cycle as on the first path: payments, outcomes, webhooks and refunds with test keys.
  5. The live webhook (The AI does it, You do it): The assistant creates a subscription for your server's address and gives you a one-time link (valid for an hour). You open it and save the secret on the server. Then a test event is sent.
  6. The live key and the switch (The AI does it, You do it): The key also arrives through a one-time link. Three values change in the code: the key (xapi_test_… → xapi_…), device_name (test → your cashbox's name) and the webhook secret. The rest of the code stays.
  7. The first real payment (You do it, Needs your yes): You pay a small amount yourself: the assistant does not create live payments. A refund on a real payment only after your yes.

No website or developer? Instead of code the assistant creates a payment page in the cabinet. Publishing only after your yes.

Try the sandbox

This is the cycle your assistant runs: a payment, an outcome, a webhook, a refund.

The webhook body has no amount and no status: after the event your code fetches GET /v2/payments/PAYMENT_ID and relies on the payment's status.

Who does what

Four columns: what the assistant does by itself, what only after your yes, what only you can do and what it never does.

The assistant does by itself

Without extra questions, within the rights you granted.

Only after your yes

The assistant names the action exactly and waits for a yes to that action.

Only you

The assistant cannot do these.

The assistant never does

The plugin's rules forbid these.

Seven access rights

On the consent page you see what the assistant asks for and allow or deny it. A tool without the right it needs answers SCOPE_REQUIRED: connect again and allow that right.

The journal of the assistant's actions and revoking access: «Настройки» → «Подключённые AI» (Settings → Connected AI).

Safety

Everything runs in the sandbox first, with test keys: no money, no Kaspi. The AI cannot create a real payment.

  1. You sign in through xPayment. You sign in on xPayment's own page, «Войти через xPayment» (Sign in with xPayment). Then a consent page lists the rights the AI asks for, and you allow or deny them.
  2. Dangerous actions need your yes in the chat. Removing a cashbox, revoking a key, deleting a webhook subscription or replacing its secret, archiving or publishing a payment page, a refund on a real payment, and a cashbox beyond your plan are done only after you say yes to that exact action. A general «do everything» does not count.
  3. Live keys and webhook secrets never pass through the chat. The AI gives you a one-time link (valid for an hour); you open it, see the value once and save it yourself, for example in .env. If you paste a key into the chat anyway, the AI tells you to replace it.
  4. You can see what the AI did, and stop it. The journal of actions and revoking access are in the cabinet: «Настройки» → «Подключённые AI» (Settings → Connected AI).

Your data goes to the AI service you chose. What the AI reads from your account, including payers' phone numbers and email addresses, is sent to that service (Claude, ChatGPT or Codex).

Install

Choose where you work with AI. A quick version for your agent is above, in «Get started».

Claude (claude.ai, the app, Cowork)

The plugin is installed from a marketplace. These steps were checked on claude.ai in a browser; the desktop app and Cowork follow the same path, but we did not run them separately.

  1. Open Customize → Plugins → + Add, choose «Добавить маркетплейс» (Add a marketplace), then «Добавить из репозитория» (Add from a repository).

  2. In the search box type the repository address and press «Синхронизация» (Sync).

    xpayment-kz/xpayment-ai
  3. A card «xPayment» (author xpayment-ai) appears. Press «Добавить» (Add). If a warning dialog appears, read it and press «Продолжить» (Continue).

  4. On the plugin page the list «Коннекторы · 2» (Connectors, 2) holds two connectors; connect both. For each: «Подключить» (Connect) → «Добавить пользовательский коннектор» (Add a custom connector) → «Продолжить», then «Добавить» and «Подключить» again. xpayment-docs is the documentation and needs no sign-in.

  5. For xpayment your browser opens xpayment.kz/login: sign in with «Войти через xPayment» and press «Разрешить» (Allow) on the consent page. The connector then shows as connected.

The first time, Claude asks for permission for each tool: «Разрешить один раз» (Allow once). The plugin holds no scripts and no hooks; the note «Может отправлять данные в другие сервисы» (It can send data to other services) is about the two MCP servers.

How to call it. Press «Попробовать в чате» (Try in chat) on the plugin page: a chat opens with /integrate already typed. A skill also starts by itself when your request matches it.

How to update. Customize → Plugins → + Add → Manage marketplaces → xpayment-ai → ⋯ → Check for updates.

Claude Code (terminal)

Needs Claude Code 2.1.319 or later.

  1. Install the plugin in a terminal (it is installed for your user):

    claude plugin marketplace add xpayment-kz/xpayment-ai
    claude plugin install xpayment@xpayment

    The same inside a session: /plugin marketplace add xpayment-kz/xpayment-ai, then /plugin install xpayment@xpayment. Start a new session afterwards.

  2. Check that everything is there: the plugin xpayment with four skills (xpayment:ask, xpayment:check, xpayment:integrate, xpayment:migrate-v2). The server xpayment-docs is connected, the server xpayment waits for the sign-in.

  3. Sign in to your account: in a session run /mcp, pick plugin:xpayment:xpayment and choose Authenticate. It needs an interactive terminal. Your browser opens «Войти через xPayment».

    This step comes from the plugin's own instructions; our check did not run the account sign-in from Claude Code.

    The same with one command in a terminal:

    claude mcp login plugin:xpayment:xpayment

How to call it. Type /xpayment:ask, /xpayment:integrate, /xpayment:migrate-v2 or /xpayment:check, or just describe the task.

How to update. Run the two commands, then /reload-plugins or start a new session.

claude plugin marketplace update xpayment
claude plugin update xpayment@xpayment

ChatGPT (chatgpt.com in a browser)

ChatGPT in a browser gets the xPayment tools but no skills: there is no ask or integrate to call, so describe the task in plain words.

  1. On chatgpt.com open Plugins → «Добавить» (Add) → «Добавить пользовательский сервер MCP» (Add custom MCP server).

  2. «Название» (Name): xPayment. «Описание» (Description): your own words.

  3. «Подключение» (Connection) → «URL-адрес сервера» (Server URL): enter the address.

    https://api.xpayment.kz/mcp
  4. «Аутентификация» (Authentication): OAuth. Under «Расширенные настройки OAuth» (Advanced OAuth settings) ChatGPT finds the client details itself, so there is nothing to type.

  5. Tick «Я понимаю и хочу продолжить» (I understand and want to continue) and press «Создать в виде плагина» (Create as a plugin). This is your own decision.

  6. Sign in with «Войти через xPayment» and press «Разрешить» (Allow).

How to call it. In a chat type @xPayment and your request, or press «Попробовать в чате» (Try in chat).

How to update. Nothing to do: the server is remote, so changes reach you without a new install.

For the ChatGPT desktop app, see the README of the plugin repository. The plugin on GitHub

Codex (Codex CLI)

Checked with Codex CLI 0.167.0.

  1. Install the plugin:

    codex plugin marketplace add xpayment-kz/xpayment-ai
    codex plugin add xpayment@xpayment
  2. Sign in to your account:

    codex mcp login xpayment

    Codex identifies itself to xPayment, so there is nothing to fill in. Your browser opens «Войти через xPayment»: approve, and Codex reports that you are logged in.

    If your default browser is signed in to xPayment with another account, open the link Codex prints in the browser where you use the right account.

  3. Check: codex mcp list shows xpayment and xpayment-docs (until you sign in, xpayment says «Not logged in»), and the skills are listed as xpayment:ask, xpayment:check, xpayment:integrate, xpayment:migrate-v2.

How to call it. Name a skill or describe the task.

How to update. Run the command, then start a new session.

codex plugin marketplace upgrade xpayment

Another agent (other clients and IDEs)

We checked only Claude, Claude Code, Codex and ChatGPT. These options were not checked: the button names in your client may differ.

  1. The «documentation» MCP server needs no sign-in if your client supports MCP over HTTP. The address:

    https://api.xpayment.kz/mcp/docs
  2. The «account» MCP server signs in to your account by OAuth («Войти через xPayment») if your client supports OAuth for MCP. The address:

    https://api.xpayment.kz/mcp
  3. Without MCP: take a test key xapi_test_… in the cabinet (Sandbox → Keys) and save it to .env yourself. Live keys are also issued in the cabinet.

  4. Give the agent the documentation in one file: it holds every endpoint of API v1 and v2.

    https://xpayment.kz/llms-full.txt

How to call it. Describe the task in your own words, or use the ready message from «Get started».

How to update. Nothing to update: the servers are remote.

Steps checked on 10 November 2026: Claude Code 2.1.319, Codex CLI 0.167.0, claude.ai and chatgpt.com in a browser (Russian interface). Where a button has no English name here, it is quoted in Russian as it appears, with the English meaning after it. Claude and ChatGPT change their screens from time to time, so a label may differ from what you see.

Connector only, no plugin

You can connect only the xPayment MCP servers, without the plugin. You get the tools and the documentation, but not the skills: the step-by-step instructions of ask, integrate, migrate-v2 and check are not loaded.

In Claude: Customize → Connectors → + Add → «Добавить пользовательский коннектор» (Add a custom connector). Add two connectors.

Documentation. No sign-in.

https://api.xpayment.kz/mcp/docs

Account. OAuth: sign in with «Войти через xPayment» and press «Разрешить» (Allow).

https://api.xpayment.kz/mcp

We checked only the menu path of this variant.

Two MCP servers

MCP gives an assistant tools. The plugin connects both xPayment servers and adds skills: ready-made instructions.

«documentation»: no sign-in

Five tools: the API passport, the list of sections, a section, search and the description of an endpoint. The assistant answers from the current documentation. https://api.xpayment.kz/mcp/docs

«account»: sign in with xPayment

The tools of your account: cashboxes, keys, webhooks, payment pages, test payments and refunds. Only within your rights and the rights granted to the assistant. https://api.xpayment.kz/mcp

Four skills

Skills are ready-made instructions for your AI. The plugin has no scripts and no hooks.

Frequently asked questions

Can I start without a Kaspi Pay cashier?

Yes. The sandbox is free and open right after sign-up: the test cashbox test, test keys xapi_test_…, no plan, no Kaspi and no money. The whole path, from a payment to a webhook and a refund, runs in it. Real payments start once you connect a cashbox.

Will the assistant see my keys?

The assistant issues a test key itself and writes it to your project's .env without printing it. It does not see live keys or webhook secrets: it gives you a one-time link valid for an hour, and you save the value yourself. If a key still ends up in the chat, the assistant tells you to replace it.

Can the assistant create a real payment?

No. The assistant neither creates nor cancels live payments: you make the first real payment. It refunds a real payment only after your yes to that action.

How does this work in ChatGPT?

ChatGPT in a browser connects the xPayment MCP server: there are tools but no skills, so describe the task in words or send the ready message from «Get started». chatgpt.com accepted the plugin archive, but we did not test it in the ChatGPT desktop app.

How do I see what the assistant did and revoke its access?

In the cabinet: «Настройки» → «Подключённые AI» (Settings → Connected AI). It holds the journal of actions and the button that revokes access.

API v1 or v2?

For a new integration we recommend API v2: it is in beta now and may change. API v1 is stable and fully supported.

I use another agent or IDE. Will it work?

Yes, but we did not check these options. Give the agent the llms-full.txt documentation file and the API v2 description, and take a test key in the cabinet (Sandbox → Keys). If your client supports MCP, you can connect both servers.

Resources and links

Start in the sandbox

The sandbox is free and open right after sign-up. Choose your agent above and send it the ready message.