Медицинский центр

Коротко

В медицинском центре Qut Pay работает в трёх местах: при записи (предоплата или бронь), на стойке регистрации (оплата приёма) и при готовности результата (оплата исследования). Всё сводится к одному действию: вы создаёте счёт, пациент платит через Kaspi, вам приходит webhook. Есть одно особое правило, и оно жёсткое: не пишите в описание счёта диагноз, фамилию врача или что-либо о состоянии пациента. В описании — только название услуги, внутренние данные остаются в metadata.

Конфиденциальность: чего не должно быть в описании

Поле description видит пациент: в уведомлении Kaspi, на странице оплаты и потом в истории Kaspi. Этот текст открыто висит на экране, а телефон в этот момент может держать кто угодно.

Так нельзя	Так правильно
«Приём гинеколога, Иванова А.»	«Приём специалиста»
«Анализ на ВИЧ»	«Лабораторное исследование»
«Консультация нарколога»	«Консультация»
«Психиатр, сеанс 2»	«Консультация, сеанс 2»
ИИН, дата рождения, номер карты	В `metadata`

Правильная структура:

POST /api/v1/invoices
{
  "amount": 12000,
  "kind": "qr",
  "description": "Приём специалиста",
  "externalOrderId": "V-2026-09-4471",
  "metadata": {
    "patient_id": "4471",
    "service_code": "A01.20",
    "doctor_id": "d-17",
    "branch": "center"
  }
}

metadata пациенту не показывается и возвращается в вашу систему вместе с webhook — по нему вы и находите пациента. Подробнее: Metadata и номер заказа и Данные и конфиденциальность.

Ещё два момента:

Заполнять customer.name полным ФИО не требуется, поле необязательное.
Администраторы, которые смотрят отчёты в кабинете, видят описания счетов. Если описания нейтральны, ни один сотрудник с доступом в кабинет не узнает, с чем пациент приходил.

Оплата приёма на регистратуре

Регистратор оформляет приём в МИС, подтягивается услуга и её стоимость.
Система создаёт счёт с нейтральным описанием.
На экране регистратуры появляется QR, пациент сканирует и платит.
Приходит invoice.paid — приём помечается оплаченным, печатается талон.

Окно сканирования QR — около трёх минут, точное время в поле expiresAt. Если очередь задержалась и пациент не успел, выставляете новый счёт.

Если пациент не хочет стоять у стойки — отправьте счёт на телефон: kind: "phone", customer.phone в формате 7XXXXXXXXXX. Ему придёт push в Kaspi, и он оплатит сидя в холле. Здесь description не длиннее 60 символов.

Предоплата и бронирование

При удалённой записи — с сайта, из колл-центра, из WhatsApp — оплату можно взять заранее. Это заметно снижает число неявок.

Полная оплата. Вся стоимость услуги. Если пациент не пришёл, действуете по своим правилам записи: возвращаете или переносите.
Бронирующий взнос. Например, 3 000 ₸. Остаток оплачивается на приёме вторым счётом.

В обоих случаях фиксируйте время только по invoice.paid. Пока счёт не оплачен, слот должен считаться свободным, иначе неоплатившие забьют всё расписание.

Освобождайте зависшие слоты: счёт стал expired или cancelled — время снова открыто. Но помните про поздние оплаты: деньги по уже закрытому счёту могут прийти позже, и invoice.paid придёт с пометкой late: true. Тогда либо предлагаете другое время, либо возвращаете деньги: Поздняя оплата.

Оплата анализов

В лаборатории порядок обычно другой: сначала забор материала, результат готов позже.

В момент забора создаёте счёт, в externalOrderId кладёте лабораторный номер.
Когда результат готов, сообщаете пациенту и отправляете счёт на его телефон.
По invoice.paid открываете результат — в личном кабинете, письмом или на руки.

Не выдавайте результат до подтверждения оплаты. События invoice.created и invoice.pending — это не оплата, а только факт создания счёта.

Если панель состоит из нескольких исследований, соберите их в один счёт. Отдельные счета на каждое исследование путают пациента и быстро съедают месячный лимит тарифа.

Чеки

Kaspi показывает своё уведомление об оплате, а чек с вашей стороны — отдельная история. Что есть:

Наша страница чека по счёту, ссылку можно отдать пациенту.
Email — если заполнен customer.email, чек можно отправить туда.
Фискальный чек — отдельная тема, и Qut Pay её не решает. Когда он обязателен и как работать с ОФД: Фискальный чек.

На странице чека описание тоже видно — ещё один повод держать его нейтральным. Подробнее: Чеки и доставка их покупателю.

Возвраты

В медицине возвраты частые: пациент не пришёл, услуга не оказана, врач заболел, часть панели не выполнена.

POST /api/v1/invoices/{id}/refund
{ "amount": 5000, "reason": "Услуга не оказана" }

Без amount возвращается вся сумма, с ним — часть. Частично возвращённый счёт переходит в статус partially_refunded.
reason — ваша внутренняя запись, она видна в отчётах. Диагноз туда тоже писать не нужно.
Если ответ по возврату пришёл в неопределённом состоянии (refund_unknown), не отправляйте запрос повторно вслепую — сначала прочитайте статус счёта: Как не вернуть деньги дважды.

Полный справочник: API возвратов.

Вариант без кода

Счёт вручную из кабинета. Регистратор вводит сумму и нейтральное описание, получает QR. Интеграция с МИС для старта не нужна.
Постоянные ссылки на оплату для частых услуг: «Консультация», «Лабораторное исследование». Их можно разместить на сайте и отправлять в WhatsApp: Ссылки на оплату.
Telegram-бот: /invoice 12000 Приём специалиста, /today — выручка за день.
Когда дойдёт до интеграции с МИС, API уже готов: Создание счёта: все поля.

Что учесть заранее

В описании никогда нет диагноза, фамилии врача и вида анализа. Одно правило, но самое важное.
Не заходите в приложение Kaspi Pay с номера кассира — привязка оборвётся, и регистратура перестанет выставлять счета: Привязка кассира оборвалась.
Номер кассира виден пациенту в уведомлении о счёте. Поэтому это должен быть рабочий номер центра, а не личный номер сотрудника.
Не открывайте результат до оплаты. Доступ должен открывать только invoice.paid.
Тариф считайте по числу приёмов. 40 приёмов в день — это около 1 200 счетов в месяц: Какой тариф выбрать.

Вопросы и ответы

Можно ли писать ФИО пациента в счёт? В этом нет необходимости. Для внутреннего сопоставления достаточно metadata.patient_id, а это поле пациенту не показывается.

Что выдать пациенту, если он просит чек? Ссылку на страницу чека по счёту либо письмо на customer.email. Фискальный чек — отдельный вопрос.

Обязательно ли возвращать предоплату? Это регулируют ваши правила записи, Qut Pay сюда не вмешивается. Технически возможен и полный, и частичный возврат.

У нас несколько филиалов, можно разделить отчётность? Да, каждому филиалу свой API-ключ, привязанный к кассиру: Раздельная отчётность по точкам.

Увидит ли регистратор в кабинете счета других пациентов? Зависит от его роли в кабинете. Но если описания нейтральные, из увиденного всё равно ничего не узнать о пациенте — ради этого правило и существует: Роли и права в кабинете.

Qut Pay — независимый сервис, не аффилирован с АО «Kaspi Bank». Kaspi и Kaspi Pay — товарные знаки их правообладателя.