PayKeeper: Принять оповещение об оплате

Сценарий из mcp-everything. Актуально на 2026-10-24.

Узнать об оплате с сервера и отметить заказ оплаченным.

1. Укажи в личном кабинете адрес оповещений и секретное слово. О каждом платеже PayKeeper пришлёт POST с id, sum, clientid, orderid и key.
2. Проверь подпись: key должен совпасть с md5 от id + sum (ровно два знака после точки) + clientid + orderid + секретное слово.
3. Защитись от повторов: оповещение может прийти несколько раз — не зачисляй платёж с тем же id дважды.
4. Ответь строкой OK и md5 от id + секретное слово. Без правильного ответа PayKeeper повторяет оповещение каждую минуту (по умолчанию до 50 раз).
5. Если нужно перепроверить платёж, запроси его: GET /info/payments/byid/ с id.

import hashlib

SECRET = "<секретное слово>"

def handle(form: dict) -> str:
    sum_str = f"{float(form['sum']):.2f}"
    expected = hashlib.md5(f"{form['id']}{sum_str}{form['clientid']}{form['orderid']}{SECRET}".encode()).hexdigest()
    if expected != form["key"]:
        return "Error! Hash mismatch"
    mark_paid_once(order_id=form["orderid"], payment_id=form["id"])  # идемпотентно по id платежа
    return "OK " + hashlib.md5(f"{form['id']}{SECRET}".encode()).hexdigest()

Базовые URL

• Боевой: https://<адрес вашего сервера PayKeeper>

Авторизация

Тип: Basic Auth

Каждый запрос отправляется с заголовком Authorization: Basic — логин и пароль от личного кабинета PayKeeper в base64. Запросы на чтение выполняются GET, изменения — POST с заголовком Content-Type: application/x-www-form-urlencoded. Каждый POST-запрос дополнительно должен содержать параметр token — токен безопасности, полученный методом /info/settings/token/.

Методы сценария

GET /info/payments/byid/ — Платёж по идентификатору

Параметр	Где	Тип	Обяз.	Описание
id	query	string	да	Идентификатор платежа в PayKeeper
advanced	query	string	нет	true — вернуть дополнительные опции платежа

Нюансы

• Параметр token обязателен в каждом POST-запросе, хотя в описании методов его часто не упоминают; токен меняется раз в 24 часа.
• В partial передавайте именно true/false — значения 1/0 система не воспринимает.
• Возврат выполняется асинхронно: успешный ответ означает только постановку в очередь. Результат проверяют через /info/refunds/bypaymentid/ или реестр платежей со статусом refunding, обычно через несколько минут.
• При ответе status = queued на capture (Промсвязьбанк) запрос лишь принят банком; итог проверяют через несколько минут.
• POST-оповещение о платеже содержит id, sum, clientid, orderid, key и доп. поля. key — md5 от конкатенации id, sum (2 знака после точки), clientid, orderid и секретного слова из личного кабинета.
• На оповещение нужно ответить строкой OK <md5(id + секретное слово)>. Без корректного ответа PayKeeper повторяет запрос каждую минуту, по умолчанию до 50 раз, после чего платёж получает статус «Совершён без оповещения».
• Оповещение может прийти несколько раз — обработчик должен защищаться от повторного зачисления по id платежа.
• К ссылке счёта можно добавить ?pstype=sbp_default, чтобы показать QR-код СБП, и &returnFormat=json, чтобы получить содержимое QR-кода.

Другие сценарии

• Выставить счёт и получить ссылку на оплату
• Вернуть деньги покупателю
• Списать заблокированные деньги
• Сверить платежи за период

---

Если этого недостаточно — официальная документация: https://docs.paykeeper.ru/dokumentatsiya-json-api/ Вся интеграция одним документом: https://mcp-everything.ru/integrations/paykeeper.md