PayKeeper: Вернуть деньги покупателю

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

Полный или частичный возврат по платежу, в том числе с чеком возврата по 54-ФЗ.

1. Получи токен: GET /info/settings/token/.
2. Отправь возврат: POST /change/payment/reverse/ с id платежа, amount (разделитель — точка) и partial — строго true или false, значения 1 и 0 не принимаются. Для чека возврата передай refund_cart — JSON-строку с товарами.
3. Ответ success означает только постановку в очередь. Через несколько минут проверь результат: GET /info/refunds/bypaymentid/.
4. Возвраты доступны пользователям, у которых включена эта функция.

curl -X POST "$PK/change/payment/reverse/" -u "$AUTH" \
  -d id=<id платежа> -d amount=500.00 -d partial=true -d token=$TOKEN

Базовые 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/settings/token/ — Получить токен безопасности

Токен нужен для всех POST-запросов (защита от CSRF). Меняется раз в 24 часа.

Пример ответа:

{
    "token" : "fd50e47596cff6c63c7ea0a633c0d2a8"
}

GET /info/refunds/bypaymentid/ — Возвраты по платежу

Информация по возвратам для платежа.

POST /change/payment/reverse/ — Возврат платежа

Полный возврат, отмена авторизации, частичный возврат или частичное списание — выбирается автоматически по состоянию платежа. Доступно пользователям с включённой функцией возврата.

Параметр	Где	Тип	Обяз.	Описание
id	body	string	да	Идентификатор платежа в PayKeeper
amount	body	string	да	Возвращаемая сумма, разделитель точка
partial	body	string	да	Частичный возврат: только true или false
refund_cart	body	string	нет	JSON-строка товаров к возврату (для чека 54-ФЗ)
token	body	string	да	Токен безопасности

Пример ответа:

{
    "result" : "success"
}

Нюансы

• Параметр 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