# PayKeeper: Списать заблокированные деньги

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

Двухстадийная оплата: деньги заблокированы на карте, списываются после сборки заказа.

1. Чтобы списать всю сумму сразу, не дожидаясь автосписания: POST /change/payment/capture/ с id платежа и token.
2. Чтобы списать только часть (часть товара закончилась), используй POST /change/payment/reverse/ с нужной суммой — частичное списание выбирается автоматически по состоянию платежа.
3. Если банк ответил status = queued, запрос лишь принят — проверь итог через несколько минут: GET /info/payments/byid/.

```bash
curl -X POST "$PK/change/payment/capture/" -u "$AUTH" -d id=<id платежа> -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/payments/byid/ — Платёж по идентификатору

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

### 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 | да | Токен безопасности |

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

```json
{
    "result" : "success"
}
```

### POST /change/payment/capture/ — Списание по авторизации

Списывает средства по ранее авторизованному платежу, не дожидаясь автосписания. Для частичного списания используют `/change/payment/reverse/`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `id` | body | string | да | Номер платежа к списанию |
| `token` | body | string | да | Токен безопасности |

## Нюансы

- Параметр `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://mcp-everything.ru/integrations/paykeeper/scenarios/vystavit-schet-i-poluchit-ssylku.md)
- [Принять оповещение об оплате](https://mcp-everything.ru/integrations/paykeeper/scenarios/prinyat-opoveschenie-ob-oplate.md)
- [Вернуть деньги покупателю](https://mcp-everything.ru/integrations/paykeeper/scenarios/vernut-dengi-pokupatelyu.md)
- [Сверить платежи за период](https://mcp-everything.ru/integrations/paykeeper/scenarios/sverit-platezhi-za-period.md)

---

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