# Bankemes for AI agents

> How an AI coding agent connects a customer’s application to Kaspi Pay through Bankemes: MCP server, setup key or OAuth, guided onboarding, sandbox, then live.

## What Bankemes does

Bankemes lets a seller accept Kaspi Pay (Kaspi QR, remote invoices by phone) on their own website or app through one REST API with signed webhooks. It also supports recurring buyer invoices using Bankemes-managed schedules or seller-managed subscriptions through the Merchant API. One Kaspi cashier = one seller subscription (4 990 ₸ per month, renewed on its billing anniversary; first 2 days free once per account, then 3 days of grace). Buyer and seller invoices are confirmed manually in Kaspi; there is no automatic bank debit.

## Connect the agent

1. The customer opens the Bankemes cabinet page “AI agents” and either connects the client through OAuth (preferred) or creates an MCP key (`bms_agent_…`, with limited permissions, an expiry date and the ability to revoke it; the owner can view and copy it again after re-entering the password).
2. The key is configured as a Bearer credential of the MCP server `https://bankemes.kz/mcp` (see below). Alternatively the MCP client uses OAuth and the customer approves in the browser.
3. The agent calls `bankemes_get_next_setup_action` and follows it until the state is `ready`.

Use a client that supports MCP Streamable HTTP. Client-specific configuration differs; the examples below show the URL and Bearer header to enter in that client and do not claim compatibility with a particular product.

Shell:

```
export BANKEMES_AGENT_KEY='bms_agent_…'   # from the Bankemes dashboard; copy it after re-entering your password
```

JSON example (syntax depends on the MCP client):

```
{
  "mcpServers": {
    "bankemes": {
      "url": "https://bankemes.kz/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BANKEMES_AGENT_KEY}"
      }
    }
  }
}
```

Clients with MCP OAuth support can add only the URL `https://bankemes.kz/mcp` without a header: they discover the authorization server, open the Bankemes consent page in the browser, and the customer approves there.

Pasting a key into an ordinary chat does not install or authorize anything: the MCP client must be configured as above (or connected through OAuth) and restarted.

## The guided workflow

Bankemes decides the next step server-side; the agent never has to infer it. Each answer says who acts (`customer`, `agent`, `bankemes`), the URL to give the customer, instructions in English and Russian, and which tool to call next (or when to poll).

- `manual_review_required` (bankemes) — A subscription payment needs a manual check by Bankemes. Wait; do not retry payments.
- `subscription_required` (customer) — Issue/reuse the Bankemes Kaspi invoice with bankemes_get_subscription_payment_link; the customer pays in Kaspi and can check status on the returned subscriptions page.
- `subscription_payment_pending` (customer) — An invoice is open; the customer pays it in Kaspi. Poll; activation happens only after bank confirmation.
- `cashier_connection_required` (customer) — Send the Kaspi connection URL (bankemes_start_cashier_connection).
- `cashier_connection_pending` (customer) — The customer is entering the SMS code on the Bankemes page. Poll.
- `cashier_reconnection_required` (customer) — The Kaspi session expired; send the reconnection URL.
- `project_access_required` (customer) — You cannot edit the application; ask for access or hand over BANKEMES_INTEGRATION.md.
- `resource_setup_required` (agent) — Create (or select) the resource for the application URL.
- `integration_configuration_required` (agent) — Provision the test token, the live token (after confirmation) and the webhook; implement the code.
- `sandbox_verification_required` (agent) — Run a test payment end to end and verify the webhook.
- `owner_approval_required` (customer) — Only the live token is missing and its request waits for the owner: send the approval url, wait, then repeat bankemes_provision_integration with the same arguments.
- `ready` (customer) — Sandbox verified. Live payments need one small real payment approved and made by the customer.

## Rules for agents

- Never ask the customer for Kaspi passwords, SMS codes, API tokens or webhook secrets, and never print secrets you handle.
- The customer acts only on official Bankemes pages: send the exact `url` returned by the tools; never invent links.
- Never mark anything paid yourself: subscriptions and payments become paid only after the bank confirms them.
- If the account has several cashiers, ask the customer which one receives the payments; never guess.
- Ask before changing a production application or making a real payment.
- Live credentials and real recurring or bulk invoices need the account owner’s approval in the Bankemes cabinet: a tool answers `approval_required` with `approval_url`; send it, wait, then repeat the same call. Your own flags (such as `confirm_live`) are never consent.
- Test mode proves the integration code only. Do not report a live Kaspi integration as working until a real, customer-approved payment succeeded.

## More

- [Start here](https://bankemes.kz/for-agents/start)
- [Workflow: subscription payment](https://bankemes.kz/for-agents/workflows/connect-payments)
- [Workflow: Kaspi cashier](https://bankemes.kz/for-agents/workflows/connect-cashier)
- [Workflow: set up the project](https://bankemes.kz/for-agents/workflows/setup-project)
- [Workflow: test the integration](https://bankemes.kz/for-agents/workflows/test-integration)
- [MCP server reference](https://bankemes.kz/docs/mcp)
- [Quickstart](https://bankemes.kz/docs/quickstart)
- [OpenAPI](https://bankemes.kz/openapi.json)
- [SKILL.md](https://bankemes.kz/SKILL.md)
- [manifest.json](https://bankemes.kz/for-agents/manifest.json)
- [llms.txt](https://bankemes.kz/llms.txt)

Source: https://bankemes.kz/for-agents
