Как подключить свой сервис платежей через API?

API платежей доступно на тарифе Бизнес. Стоимость использования API платежей - 25 ₽ за транзакцию. Эта сумма будет списываться с вашего баланса Bukza.

Вы можете подключить к Bukza любой сервис платежей через API платежей. Для подключения вам нужен свой сервер — промежуточное звено между Bukza и вашим сервисом платежей. Также потребуются навыки программирования.

Данное API может претерпевать в будущем некоторые изменения и дополнения.

Напишите нам на support@bukza.com о необходимости подключения API платежей. В письме укажите URL адрес вашего сервера, на который Bukza будет слать запросы. В ответ мы отправим ваш UserId в Bukza и ключ для формирования подписи запросов.

Вы можете посмотреть исходный код примера на JavaScript в сервисе онлайн редактирования кода здесь.

Для тестирования этого примера на своем аккаунте проделайте следующее:

1. Зарегистрируйтесь в Glitch.
2. Создайте ремикс нашего примера интеграции здесь, нажав кнопку «Remix». В результате будет создано ваше собственное приложение с тем же исходным кодом.
3. Напишите нам на support@bukza.com адрес созданного приложения. Мы установим его в качестве URL адреса вашего сервера и вышлем вам bukza_user_id и bukza_key.
4. Откройте .env файл вашего приложения и вставьте туда значения bukza_user_id и bukza_key. Этот файл не виден другим пользователям Glitch.
5. Перейдите в Bukza аккаунт. На вкладке приема платежей включите «Заказы с автоматической обработкой платежа» и установите требуемый размер предоплаты.
6. Завершите заказ с виджета, используя e-mail своего аккаунта. Если использовать при завершении заказа свой e-mail, плата за использование API платежей браться не будет.
7. При тестировании проверьте вкладку «Logs» в Glitch. Там вы увидите логи полученных и отправленных запросов.
8. Реализуйте отображение вашей платежной формы и обработку ответов от вашей платежной системы в файлах server.js и index.hbs. Не вставляйте ваши ключи и пароли ни в один файл, кроме файла .env. Файлы проекта и вся история их изменений доступна другим пользователям Glitch.

Вы можете реализовать один из двух вариантов взаимодействия:

1. «С предавторизацией средств» — вариант, исключающий перебронирования. При завершении заказа сначала сумма замораживается на карте, и затем мы дополнительно проверяем, что заказ доступен и цена не изменилась. Если заказ больше не доступен, то средства на карте сразу размораживаются.
   
   Вы можете использовать этот вариант интеграции, чтобы снимать замороженные средства отложено вручную. Вы сможете сами проверить заказ и либо снять средства, либо отменить заморозку. Но если через 3 дня средства так и не будут сняты, то Bukza отправит запрос на отмену заморозки.
   
   
2. «Упрощенный режим» — это вариант без предварительной заморозки средств на карте. То есть в момент завершения заказа средства уже сняты. При этом мы по-прежнему проверяем доступность и сумму заказа, и в случае проблемы мы добавим предупреждение для управляющего в сообщение о новом заказе.
   
   Этот вариант стоит использовать, если ваш платежный сервис не поддерживает предварительную заморозку средств.

В запросах всегда присутствуют следующие параметры:

• userId — ваш ID в системе Bukza, например: 11223.
• orderNumber — номер заказа в Bukza, например: "574285869".
• command — название выполняемой команды. Одно из значений: "GetPaymentData", "CaptureCallback", "AuthorizeCallback", "Cancel", "Capture" или "Refund".
• data — дополнительные данные команды, например номер транзакции в вашей системе платежей: "18493853499".
• amount — сумма платежа, например: 99.75.
• timestamp — число секунд Unix времени. Например: 1596706182. Примеры получения на разных языках программирования: https://www.epochconverter.com.

Чтобы создать или проверить подпись запроса, требуется соединить строку из этих параметров (без пробелов и плюсов), посчитать hmac sha256 с вашим ключом и перевести результат в base64 строку:

Примеры реализации для разных языков программирования: https://www.jokecamp.com/blog/examples-of-creating-base64-hashes-using-hmac-sha256-in-different-languages/

Проверить расчет вы можете здесь: http://jsfiddle.net/dwyrk513/1/

Важные моменты:

• При переводе в строку значения amount используйте точку в качестве разделителя при наличии дробной части числа.
• При получении ваших запросов Bukza проверяет, чтобы timestamp соответствовал текущему серверному времени и не отставал больше, чем на 5 минут.
• При получении запросов от Bukza мы рекомендуем проверять hash и timestamp аналогичным образом.

1.1. В момент завершения заказа Bukza отправляет на ваш URL сервера POST запрос с телом: В ответ на этот запрос вам следует отправить данные, например:

• url — это сформированный адрес платежной страницы. Эта страница может располагаться как на вашем сервере, так и на сервере вашего платежного сервиса.
• redirect — параметр, который определяет, нужно ли полностью перекинуть пользователя на указанный URL. Если значение false, то платежная форма покажется внутри виджета в iframe. Размеры iframe вы можете изменить с помощью css в настройках виджета.
• В url был добавлен сheckStateToken с названием параметра bukzaCheckStateToken. Этот параметр поможет вам проверять состояние заказа на вашей платежной странице. Подробнее об этом читайте здесь.

1.2 Пользователю показывается ваша платежная форма, и он совершает платеж. Соответственно вы должны получить уведомление на свой сервер от вашего платежного сервиса. После получения такого уведомления вам следует сразу отправить POST запрос на адрес https://public.bukza.com/api/pay. Тело запроса:

1.3 Затем Bukza в зависимости от доступности заказа и параметров обработки заказов может сделать одно из действий: отменить платеж, сразу снять замороженные средства или просто оформить заказ, оставив средства замороженными. В последнем случае вы можете самостоятельно в интерфейсе управляющего отменить или подтвердить платеж. В любом из вариантов Bukza будет отправлять на ваш сервер запросы, которые вам следует отправить в вашу платежную систему.

Для отмены заморозки средств Bukza шлет вам запрос с телом:

А для снятия замороженных средств Bukza отправит вам такой запрос:

В ответ на эти запросы вам следует отправить любой ответ с HTTP статусом 200 (SUCCESS).

2.1 В момент завершения заказа Bukza также отправляет на ваш URL сервера POST запрос, как в пункте 1.1.

2.2 Пользователю показывается ваша платежная форма, и он совершает платеж. Соответственно вы должны получить уведомление на свой сервер от вашего платежного сервиса. После получения уведомления вам следует сразу отправить запрос на адрес https://public.bukza.com/api/pay. Тело запроса:

Через интерфейс управляющего вы можете оформить возврат средств по конкретному платежу. Возврат может быть полный или частичный. При выполнении возврата Bukza отправляет на ваш сервер запрос. Вы в свою очередь должны отправить соответствующий запрос в свой платежный сервис. Тело запроса от Bukza:

В ответ на этот запрос вам следует отправить любой ответ с HTTP статусом 200 (SUCCESS).