arrow_back_iosВопросы
help

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

check_circle
Вы можете подключить к Bukza любой сервис платежей через API платежей. API платежей доступно на тарифе Бизнес. Для подключения вам нужен свой сервер — промежуточное звено между Bukza и вашим сервисом платежей. Также конечно же потребуются навыки программирования.
Данное API находится в beta-режиме и может претерпевать в будущем некоторые изменения и дополнения. Если для реализации подключения к вашей системе платежей нашего API недостаточно, напишите нам на support@bukza.com и мы постараемся его доработать.

Варианты интеграции

Вы можете реализовать один из двух вариантов взаимодействия:
  1. «С предавторизацией средств» — вариант, исключающий перебронирования. При завершении заказа сначала сумма замораживается на карте, и затем мы дополнительно проверяем, что заказ доступен и цена не изменилась. Если заказ больше не доступен, то средства на карте сразу размораживаются.

    Вы можете использовать этот вариант интеграции, чтобы снимать замороженные средства отложено вручную. Вы сможете сами проверить заказ и либо снять средства, либо отменить заморозку. Но если через 3 дня средства так и не будут сняты, то Bukza отправит запрос на отмену заморозки.

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

    Этот вариант стоит использовать, если ваш платежный сервис не поддерживает предварительную заморозку средств.

Как подключить API?

Напишите нам на support@bukza.com о необходимости подключения API платежей. Мы запросим у вас URL адрес вашего сервера, на который Bukza будет слать запросы. Также мы отправим ваш ID в Bukza и ключ для формирования подписи запросов (например: 7kd9sl8s0bsm409rdsk3jn20).

Как формируется подпись запроса?

В запросах всегда присутствуют следующие параметры:
  • 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 строку:
hash = base64(hmacSha256(userId + orderNumber + command + data + amount + timestamp), key);
Примеры реализации для разных языков программирования: 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.1. В момент завершения заказа Bukza отправляет на ваш URL сервера POST запрос с телом:
{
    userId:11223,
    orderNumber:"574285869",
    command: "GetPaymentData",
    data: "",
    amount: 99.75,
    timestamp: 1596706182,
    hash: "p2t1xcpBiXLPPDdB129vUctRAgGbzQgRcnX4IiZ0bNE="
}
В ответ на этот запрос вам следует отправить данные:
{
    url: "https://money.yandex.ru/quickpay/shop-widget?writer=seller&default-sum=99.75&button-text=11&payment-type-choice=on&&quickpay=shop&account=410015219149437",
    redirect: false
}
  • url — это сформированный адрес платежной страницы. Эта страница может располагаться как на вашем сервере, так и на сервере вашего платежного сервиса.
  • redirect — параметр, который определяет, нужно ли полностью перекинуть пользователя на указанный URL. Если значение false, то платежная форма покажется внутри виджета в iframe. Размеры iframe вы можете изменить с помощью css в настройках виджета.
1.2 Пользователю показывается ваша платежная форма, и он совершает платеж. Соответственно вы должны получить уведомление на свой сервер от вашего платежного сервиса. После получения такого уведомления вам следует сразу отправить POST запрос на адрес https://public.bukza.com/api/pay. Тело запроса:
{
    userId:11223,
    orderNumber:"574285869",
    command: "AuthorizeCallback",
    data: "18493853499",
    amount: 99.75,
    timestamp: 1596706182,
    hash: "2kkjjx/grcar6B9yknqUMP6eOdMw4yJwa60Uc8fisNA=",
    comment: "Любой комментарий к платежу. Он будет виден в интерфейсе управляющего. Он не участвует в подписи запроса."
}
1.3 Затем Bukza в зависимости от доступности заказа и параметров обработки заказов может сделать одно из действий: отменить платеж, сразу снять замороженные средства или просто оформить заказ, оставив средства замороженными. В последнем случае вы можете самостоятельно в интерфейсе управляющего отменить или подтвердить платеж. В любом из вариантов Bukza будет отправлять на ваш сервер запросы, которые вам следует отправить в вашу платежную систему.
Для отмены заморозки средств Bukza шлет вам запрос с телом:
{
    userId:11223,
    orderNumber:"574285869",
    command: "Cancel",
    data: "18493853499",
    amount: 99.75,
    timestamp: 1596706182,
    hash: "ejIS+AiPRSH9qXV/bBcAf7OSViCVUtj/hYPsL4aYpNM="
}
А для снятия замороженных средств Bukza отправит вам такой запрос:
{
    userId:11223,
    orderNumber:"574285869",
    command: "Capture",
    data: "18493853499",
    amount: 99.75,
    timestamp: 1596706182,
    hash: "JE4fRRLObEzCYk7aRFaW81DZw3sTXTOXsEcq3r8zm+Y="
}
В ответ на эти запросы вам следует отправить любой ответ с HTTP статусом 200 (SUCCESS).

Вариант #2 «Упрощенный режим»

2.1 В момент завершения заказа Bukza также отправляет на ваш URL сервера POST запрос, как в пункте 1.1.
2.2 Пользователю показывается ваша платежная форма, и он совершает платеж. Соответственно вы должны получить уведомление на свой сервер от вашего платежного сервиса. После получения уведомления вам следует сразу отправить запрос на адрес https://public.bukza.com/api/pay. Тело запроса:
{
    userId:11223,
    orderNumber:"574285869",
    command: "CaptureCallback",
    data: "18493853499",
    amount: 99.75,
    timestamp: 1596706182,
    hash: "eUKOwld1sEK3axhF9ZAy0WugXMJW+9nrs4BRlvnCeb0=",
    comment: "Любой комментарий к платежу. Он будет виден в интерфейсе управляющего. Он не участвует в подписи запроса."
}

Возврат средств

Через интерфейс управляющего вы можете оформить возврат средств по конкретному платежу. Возврат может быть полный или частичный. При выполнении возврата Bukza отправляет на ваш сервер запрос. Вы в свою очередь должны отправить соответствующий запрос в свой платежный сервис. Тело запроса от Bukza:
{
    userId:11223,
    orderNumber:"574285869",
    command: "Refund",
    data: "18493853499",
    amount: 50.75,
    timestamp: 1596706182,
    hash: "E62WH04cKUjAvQ0dmirYMc16mCGN96YyQfrft8vLj0A="
}
В ответ на этот запрос вам следует отправить любой ответ с HTTP статусом 200 (SUCCESS).
Не нашли ответа на ваш вопрос?
Задайте его нам на
mail_outline support@bukza.com