Приём POST оповещений

При каждом принятом платеже PayKeeper может отправлять POST-запрос на указанный URL предприятия.
Для этого необходимо включить данную функцию в личном кабинете предприятия.

В запросе от PayKeeper будут передаваться следующие данные:

  Параметр Назначение Обязательный
1 id Уникальный номер платежа Да
2 sum Сумма платежа Да
3 clientid Фамилия Имя Отчество Нет
4 orderid Номер заказа Нет
5 key Цифровая подпись запроса, строка из символов a-f и 0-9 Да

Поле key — цифровая подпись запроса. Она является md5-хешем, который вычисляется от конкатенации параметров 1-4 с добавлением в конец секретного слова. Секретное слово также настраивается в личном кабинете

Обязательно нужно проверять, что sum  , clientid и orderid соответствуют друг другу в вашей информационной системе. То есть если было получено оповещение об успешном платеже по заказу номер orderid , нужно проверить, что он действительно есть, что его сумма действительно совпадает с полученной суммой оплаты sum , что он принадлежит пользователю clientid . Если ваша система не использует идентификацию заказов или пользователей, проверяйте только релевантные для вашего случая параметры.

Помимо вышеуказанных дополнительно в POST-оповещении передаются следующие дополнительные параметры:

  Параметр Назначение Обязательный
1 service_name Наименование услуги Нет
2 client_email Адрес электронной почты Нет
3 client_phone Телефон Нет
4 ps_id Идентификатор платежной системы Да
5 batch_date Дата списания авторизованного платежа Нет
6 fop_receipt_key Код страницы чека 54-ФЗ Нет
7 bank_id Идентификатор привязки карты Нет
8 card_number Маскированный номер карты Нет
9 card_holder Держатель карты Нет
10 card_expiry Срок действия карты Нет

Если параметр отмечен как необязательный, то в запросе он может отсутствовать, либо быть пустым. Поля clientid , orderid , service_name , client_email , client_phone  будут те же, что и при инициализации платежа.

ps_id  устанавливается в зависимости от платежной системы, через которую проходит платеж (например, через Qiwi, Яндекс.Деньги или WebMoney) либо в зависимости от банка Эквайера, через который принимается оплата.

batch_date  передается в том случае, если платежная платформа PayKeeper работает в двухстадийном режиме оплаты (режим «авторизация + списание»). В этом режиме успешная оплата является операцией авторизации денежных средств, которые по прошествии заданного периода времени должны быть списаны с карты плательщика. batch_date  в этом случае представляет собой дату запланированного списания платежа.

fop_receipt_key  передается в том случае, если платежная платформа интегрирована с онлайн-кассой. С помощью fop_receipt_key  формируется постоянный адрес страницы с чеком 54-ФЗ по данному платежу.

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

Параметры  card_number , card_holder , card_expiry , могут быть заполнены соответственно маскированным номером карты, именем держателя карты и сроком действия карты плательщика, если использующийся шлюз банка эти данные передаёт.

В ответ на данный запрос должна быть отправлена строка вида:

OK hash

где hash вычисляется как md5-хеш от конкатенации поля id запроса и того же секретного слова, а слово «OK» состоит из английских букв O и K. Такой ответ считается подтверждением того, что информационная система предприятия приняла данный платёж. Пример составления ответа на PHP:

В случае, если на запрос не будет получен корректный ответ, PayKeeper будет продолжать попытки сообщить о платеже, повторяя запрос каждую минуту. Если через определённое число попыток (50 по умолчанию) не будет получен корректный ответ, платёж в PayKeeper получит статус «Совершён без оповещения». Такой платёж можно повторно провести через веб-интерфейс администратора.

Например, на языке PHP приём оповещений можно реализовать так:

Ваша система должна корректно обрабатывать ситуацию, когда уведомление об успешном платеже отправляется несколько раз — не должно происходить повторных зачислений одного и того же платежа. Проще всего это сделать, запоминая id принятого платежа в базе данных и проверяя его уникальность. 

Другие типы уведомлений

Существует, так же, возможность настроить уведомления о произведённых возвратах и неуспешных платежах (в статусе «Не состоялся»). Для настройки таких уведомлений необходимо обратиться в службу поддержки.