Отложенные платежи Яндекс

Недавно передо мной встала задача настроить отложенные (холдированные) платежи для Яндекс.Кассы. Сказать по честному, ранее не приходилось сталкиваться с этим, хотя интеграцию с Яндекс.Кассой штатными средствами 1С-Битрикс, конечно, настраивал не раз.

Поначалу мне было непонятно что это такое, для чего нужно, и чем отличается от обычной оплаты через Яндекс.Кассу. Но постепенно все встало на свои места.

Как работает Яндекс.Касса с отложенными платежами?

Начну с краткого описания принципов работы Яндекс.Кассы. Сначала пользователь на сайте складывает товар в корзину, затем переходит к оформлению заказа, где выбирает способ оплаты через Яндекс.Кассу, затем нажимает кнопку оформления заказа. При этом на сайте создается заказ, и выводится уведомление о том, что заказ успешно оформлен. В зависимости от настройки платежной системы «Открывать в отдельном окне» форма для оплаты либо будет выведена прямо на странице уведомления об успешном заказе, либо будет открыта в новой вкладке (имейте ввиду, что по умолчанию многие браузеры блокируют это окно, хотя и показывают уведомления о блокировке). В форму оплаты уже подставлены все данные по заказу и по магазину (shopId и scid). При нажатии кнопки оплаты в этой форме пользователь переносится на страницу Яндекса с оплатой. После оплаты Яндекс отправляет служебный HTTP-запрос на сайт о том, что заказ либо успешно выполнен, либо что оплата не прошла, и показывает соответствующее уведомление с предложением вернуться на сайт.

Если мы хотим использовать отложенные платежи, то принцип немного меняется: в случае успешной оплаты по карте (отложенные платежи возможны только для банковских карт) у пользователя деньги списываются, но как бы помещаются в буфер (т.е. блокируются), и для дальнейшего управления ими требуется выполнить дополнительный http-запрос либо для подтверждения ( confirmPayment), либо для отмены ( cancelPayment) платежа.

В случае необходимости перехода на систему оплаты с холдированием платежей, необходимо сделать запрос менеджеру Яндекс.Кассы для получения идентификационных данных магазина (shopId и scid). Ранее выданные shopId и scid не подходят здесь, для отложенных платежей нужны именно новые. И в итоге получается, что для холдированных платежей эти два параметра будут одни, а для всех остальных оплат в Яндекс.Кассу – другие. Также важно понимать, что при подключении отложенных платежей все платежи через банковскую карту будут отложенные, т.е. нельзя сделать чтобы часть платежей была обычными платежами, а другие – отложенными.

Технические подробности реализации отложенных платежей можно найти на странице « Формат взаимодействия» помощи Яндекс.Кассы.

С чего начать настройку отложенных платежей?

В начале общения с ТП при настройке Яндекс.Кассы менеджер Яндекса присылает письмо с таким алгоритмом действий:

1. реализовать наш протокол http уведомлений,
   
2. пройти процедуру обмена сертификатами,
3. реализовать функции confirmPayment и cancelPayment.

Реализация протокола HTTP-уведомлений

Первый пункт («реализовать наш протокол http уведомлений») означает что необходимо настроить стандартную интеграцию сайта с Яндекс.Кассой, когда сайт генерирует форму для оплаты, и после оплаты обрабатывает http-запрос от Яндекс.Кассы. С этим все понятно, более подробно описывать не буду, т.к. статья не об этом. Главное, что после интеграции необходимо провести как минимум один тестовый платеж, чтобы менеджер в Яндекс увидел, что настройка произведена.

Процедура обмена сертификатами

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

От себя добавлю, что данный алгоритм, хоть и описан подробно, но все же может вызвать некоторые затруднения. Именно поэтому я разработал специальную программу для Windows, которая все это сделает за вас. Сама программа весит менее одного мегабайта, остальные почти 13 мегабайт - это утилита OpenSSL и вспомогательные утилиты. Также к архиву приложены исходники программы для Delphi (разработано в Delphi Seattle). Программа не содержит вирусов и другого вредоносного или шпионского ПО, не требует прав администратора, не требует доступа в интернет. Пользоваться программой проще простого: нужно заполнить все поля, выбрать папку для сохранения файлов сертификата, и нажать «Готово!». Скачать программу можно по этой ссылке (5.89 МБ).

Программа генерирует четыре файла:

1. request.csr – файл запроса,
2. private.key – приватный ключ,
3. sign.txt - электронная подпись запроса на сертификат,
4. sign_full.txt – дополнительная информация (нигде не требуется).

Для продолжения настройки необходимо скачать файл Запрос на создание сертификата (60.5 КБ) с заполненными демо-данными, заменить данные на свои (не забудьте заменить код электронной подписи из файла sign.txt!), и отправить менеджеру Яндекс, приложив к письму файл request.csr.

Также, во избежание необходимости перевыпуска сертификата из-за неправильно введенных данных, вводите только правильные данные, согласованные с заказчиком. Иначе потом может выясниться, что организация называется немного по-другому, или CN нужен другой. В общем, сначала советую все уточнить.

Реализация функций подтверждения и отмены платежей

Третий пункт («реализовать функции confirmPayment и cancelPayment») заключается в реализации функций подтверждения и отмены платежа. Ссылки для указанных функций смотрите по тексту выше. Добавлю, что также существуют очень полезные функции просмотра списка заказов ( listOrders) и возвратов ( listReturns). Пример PHP-класса для работы с Яндекс.Кассой, а также пример использования функций подтверждения и отмены платежа можете скачать в приложенном файле (3.05 КБ).

Также добавлю, что в моем случае алгоритм подтверждения строился на основе изменения статуса заказа. Т.е. при смене статуса в «Доставлен» выполнялось подтверждение платежа, при смене на «Отменен» - отмена платежа. Для этого я использовал событие «OnSaleBeforeStatusOrder» модуля «Интернет-магазин». Код также имеется в ссылке выше по тексту.

Общие рекомендации по настройке

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

1. понять логику работы отложенных платежей,
2. связать эту логику отложенных платежей с логикой работы сайта,
3. продумать, как эта связка должна работать в коде.

После завершения настройки необходимо провести как минимум одно успешное подтверждение платежа и одну успешную отмену платежа. После этого необходимо опять написать менеджеру Яндекс для получения настроек для боевого режима.

В ходе настройки обнаружилась проблема с SSL: если в phpinfo() в строке «SSL Version» указан NSS (напр., «NSS/3.21 Basic ECC»), то все запросы к Яндексу намертво зависают. Если такое случилось, необходимо заменить используемую на сервере SSL-библиотеку на OpenSSL, тогда в «SSL Version» будет что-то вроде «OpenSSL/1.0.1e». Также необходимо проверить, чтобы запросы к серверам Яндекса не блокировались на уровне файрвола на сервере.

И напоследок

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

В случае возникновения вопросов - обращайтесь, постараюсь помочь.

P.S.: имейте ввиду, мы не несем ответственности за любые действия, которые Вы совершаете в соответствии с данной статьей, в т.ч. при использовании программы генерации запроса на сертификат. Данная статья лишь описывает мой успешный опыт настройки.