# Kazakhstan

In Kazakhstan the payer sends tenge to the recipient's card number from their bank app. It is a
[card payment](card.md) with two differences: country `KZ` and currency `KZT`. Statuses,
callbacks and retry rules are the same as for [SBP](sbp.md).

| | Russia | Kazakhstan |
| --- | --- | --- |
| `geo_code` | `RU` (default) | `KZ` — **must be set** |
| `currency` | `RUB` (default) | `KZT` — **must be set** |
| `payment_method` | any [method](methods.md) | `card_transfer` |
| `amount` | roubles | tenge |
| `bank_code` | a Russian bank | a Kazakh bank |

SBP, NSPK QR, account transfer and cross-border transfer are Russian methods; they are not
available for `KZ`.

## Create a payment { #create }

`POST /api/v1/payments`, [signed](signing.md) the same way as for SBP.

```json
{
  "merchant_payment_id": "order-kz-1001",
  "amount": "50000",
  "payment_method": "card_transfer",
  "currency": "KZT",
  "geo_code": "KZ",
  "bank_code": "Kaspi"
}
```

- Always send `currency` and `geo_code`: without them the payment is created as a Russian one
  in roubles, and `50000` is taken as roubles.
- `bank_code` is the optional payer bank: a Kazakh bank name from the [directory](banks.md),
  for example `Kaspi`, `Halyk`, `Freedom Bank`. `GET /api/v1/banks?geo_code=KZ` returns the
  list. Empty means any bank.
- `is_intrabank: true` with `bank_code` means the recipient card is in the same bank as the
  payer's (for example, Kaspi → Kaspi).

Other fields and their rules: [SBP payments → Request fields](sbp.md#request-fields).

### Limits in tenge { #limits }

[`GET /api/v1/project/limits`](sbp.md#contract-limits) shows whether your project's contract
accepts payments in Kazakhstan: look for a record with `"geo_code": "KZ"`,
`"currency": "KZT"`, `"payment_method": "card_transfer"`. Its `min_amount` and `max_amount` are
in tenge.

## Response { #response }

`201 Created`:

```json
{
  "id": "5b8e1c2d-3f4a-4b5c-9d6e-7f8091a2b3c4",
  "merchant_payment_id": "order-kz-1001",
  "flow": "runtime_live",
  "status": "processing",
  "amount": 50000,
  "initial_amount": 50000,
  "currency": "KZT",
  "geo_code": "KZ",
  "payment_method": "card_transfer",
  "bank_code": "Kaspi",
  "is_intrabank": false,
  "callback_url": null,
  "is_test": false,
  "merchant_information": {
    "course": 520.00,
    "rate": 9.00,
    "amount_usdt": "96.1538",
    "amount_rate": "4500.0000",
    "amount_usdt_rate": "87.5000"
  },
  "requisite": "4400430212345678",
  "requisite_bank": "Kaspi",
  "holder_name": "Айгерим С.",
  "created_at": "2026-10-14T09:30:00Z",
  "updated_at": "2026-10-14T09:30:01Z"
}
```

- `requisite` is the recipient's card number;
- `amount` and `initial_amount` are in tenge;
- `merchant_information.course` is tenge per 1 USDT; `amount_usdt` = `amount / course`. The
  rest is as in [`merchant_information` calculation](sbp.md#merchant-information).

## What to show the payer { #payer-screen }

- **Card number** from `requisite` in groups of four (`4400 4302 1234 5678`) with a "Copy"
  button that copies it without spaces.
- **Recipient** — `holder_name`; **card bank** — `requisite_bank`.
- **Amount** — exactly `amount` in tenge (`50 000 ₸`), in one transfer.
- **Deadline** — a countdown from `created_at` for your project's payment lifetime (15 minutes by
  default).

## Statuses and result { #result }

As for cards: [Card payments → Statuses and result](card.md#result).

## Common mistakes { #edge-cases }

- **No `geo_code` or `currency`.** The payment goes through as a Russian one in roubles: a Kazakh
  bank in `bank_code` returns `422 cross_border_invalid` or `422 bank_not_found`, and without
  `bank_code` the amount is taken as roubles. Always send `"geo_code": "KZ"` and
  `"currency": "KZT"`.
- **A method other than `card_transfer`.** It is not in the contract for Kazakhstan —
  `422 payment_not_covered`.
- **Bank not found.** The name must come from the Kazakh directory
  (`GET /api/v1/banks?geo_code=KZ`), otherwise `422 bank_not_found`.
- **No cards of the requested bank.** `bank_code` and `is_intrabank` narrow the choice; if
  nothing matches — `422 payment_not_routable`. Try without them.

Everything else: [Card payments → Edge cases](card.md#edge-cases).

## See also { #see-also }

- [Payment methods](methods.md) — all methods, countries and currencies.
- [Banks](banks.md#list) — Kazakh banks in the directory.