KASSA Merchant API v1¶

KASSA — платёжный агрегатор для интернет-магазинов и сервисов в России и Казахстане: приём оплаты картами, через СБП и Kaspi, возвраты, платёжные ссылки, чеки, события и расчёты — через один REST API.

Состав /v1 заморожен

Контракт имеет версию 1.0.0: поля и коды ответов в /v1 не удаляются и не переименовываются. Допускаются только совместимые добавления — новое необязательное поле, новое значение справочника, новая операция; каждое отражается в changelog. Поэтому клиент обязан игнорировать неизвестные поля и неизвестные значения перечислений.

Базовый адрес и формат¶


Базовый адрес	`https://api.kassa.example/v1`
Протокол	только HTTPS (TLS 1.2+)
Формат	JSON, UTF-8; `Content-Type: application/json`
Аутентификация	HTTP Basic: имя пользователя — `shop_id`, пароль — `secret_key`
Версия	в пути: `/v1`. Несовместимые изменения — только `/v2` с параллельной поддержкой `/v1` ≥ 12 месяцев
Справочник	Reference (Redoc) — все операции и схемы из `openapi.yaml`

Ключевые правила¶

Ключи и режимы. Ключ вида test_ru_…, test_kz_… — тестовый режим (песочница, деньги не двигаются, объекты с test: true); live_ru_…, live_kz_… — боевой. Один и тот же URL и контракт; тестовые и боевые данные не смешиваются. Секрет показывается один раз при создании и хранится у нас только в виде хеша. Подробнее — в быстром старте.
Идемпотентность. Каждый POST (и PATCH) требует заголовок Idempotency-Key (8–128 символов, рекомендуется UUID v4). Ключ действует 24 часа: повтор с тем же ключом и телом возвращает исходный ответ; с другим телом — 409 idempotency_conflict; параллельный повтор — 409 idempotency_in_progress. Повторяйте запрос после сетевой ошибки с тем же ключом — платёж не задвоится.
Деньги. Суммы — объект amount: { "value": "1500.00", "currency": "RUB" }; value — строка с двумя знаками после точки, никаких чисел с плавающей точкой. Валюты: RUB, KZT, USD, EUR.
Идентификаторы. Строки с префиксом типа: sh_ (магазин), pay_ (платёж), rf_ (возврат), pl_ (платёжная ссылка), dsp_ (спор), evd_ (файл доказательства), evt_ (событие), whe_ (адрес вебхука), set_ (расчёт), po_ (выплата); далее 26 символов [0-9A-Z].
Время. Все метки — ISO 8601 в UTC с суффиксом Z: 2026-09-10T10:00:00Z.
Списки. Курсорная пагинация: limit (1–100, по умолчанию 20) и cursor; в ответе items и next_cursor (null, когда данных больше нет). Сортировка — по created_at по убыванию.
Ошибки. Единый объект { "type": "error", "code", "description", "parameter", "request_id" }; code — из закрытого справочника, см. справочник ошибок. Опирайтесь на code и HTTP-статус, не на текст description.
Модель расчётов. Получатель платежа — касса, магазин — субмерчант (Shop.settlement_model: "agent"). Это меняет поведение возврата, выплат, дескриптора в выписке и чека — Модель расчётов KASSA.
X-Request-Id. Приходит в каждом ответе и дублируется в объекте ошибки — указывайте его в обращениях в поддержку.
Совместимость. Игнорируйте неизвестные поля ответов и неизвестные значения справочников — контракт расширяется без смены версии.
Лимиты по умолчанию. 600 запросов в минуту на ключ и 120 созданий платежей в минуту; при превышении — 429 too_many_requests с заголовком Retry-After. metadata — до 16 ключей, ключ ≤ 64 символов, значение ≤ 512; возвращается без изменений во всех объектах и событиях.

Статусы платежа¶

pending ──► waiting_for_capture ──► succeeded
   │                 │
   └─────────────────┴──────────► canceled

Статус	Смысл	Что можно сделать
`pending`	платёж создан, плательщик ещё не завершил оплату	`cancel` (закрыть чекаут); ждать событий
`waiting_for_capture`	деньги захолдированы (двухстадийная схема, `capture: false`)	`capture` (полностью или частично), `cancel` (снять холд)
`succeeded`	деньги списаны; финальный статус	возвраты через `POST /refunds`
`canceled`	платёж не состоялся; причина в `cancellation_details.reason`; финальный статус	создать новый платёж

Финальные статусы не меняются. Возврат: pending → succeeded | canceled.

Как узнавать о результате¶

Вебхуки — основной канал: KASSA присылает подписанные события payment.succeeded, payment.canceled, refund.succeeded и другие на ваш HTTPS-адрес; тип вложенного объекта определяется полем data.object_type. См. Вебхуки и подпись.
Запрос объекта — GET /payments/{payment_id} в любой момент; обязательно при возврате плательщика на return_url и при сомнениях в порядке событий.
GET /events — журнал событий магазина для сверки и повторной обработки.

Возврат плательщика на return_url не означает успех оплаты: подтверждайте заказ только по событию или по статусу из API.

Разделы¶

Быстрый старт — создать платёж, отправить плательщика на чекаут, получить статус, сделать возврат.
Модель расчётов KASSA — почему возврат может быть отклонён по балансу, когда замораживаются выплаты, кто задаёт строку в выписке и кто пробивает чек.
Вебхуки и подпись — формат события, разбор по object_type, проверка X-Kassa-Signature на PHP, Python и Node.js, ротация секрета, повторы, идемпотентная обработка.
Споры и чарджбэки — жизненный цикл спора, дедлайн доказательств, загрузка файлов, удержания на балансе.
Тестовый режим — песочница, POST /test/payments/{payment_id}/simulate, тестовые исходы, чек-лист выхода в боевой режим.
Ошибки — таблица кодов и HTTP-статусов.
Changelog — изменения контракта.
Справочник API — Redoc по openapi.yaml.