SDK for Go

SDK for Go — это набор средств разработки для взаимодействия веб-сервисов, разработанных на Go, с платёжной платформой Benker при проведении оплат через Payment Page. В этом разделе представлена информация о работе с SDK for Go с примерами кода на языке программирования Go.

Возможности

SDK for Go позволяет:

подписывать набор параметров платежа и формировать адрес для вызова Payment Page,
проверять подлинность оповещений от Benker и получать из них информацию о платежах.

Состав

SDK for Go содержит библиотеку для разработки и автоматизированного тестирования, а также служебные файлы.

Порядок работы

Для использования SDK for Go необходимо:

Решить организационные вопросы, касающиеся взаимодействия с платёжной платформой Benker:
- Если у компании нет идентификатора проекта и ключа для взаимодействия с Benker — отправить заявку на подключение.
- Если у компании есть идентификатор и ключ для взаимодействия с Benker — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK for Go и согласовать с ними порядок тестирования.
Установить библиотеки, входящие в состав SDK for Go, в каталог с исходным кодом веб-сервиса и подключить их в коде, а также доработать код для использования необходимой функциональности.
Протестировать и запустить в работу обновлённый исходный код веб-сервиса.

При возникновении вопросов о работе с SDK for Go следует обращаться в службу технической поддержки Benker по адресу help@benker.io.

Установка и подключение библиотек

Устанавливать библиотеки, входящие в состав SDK for Go, в проект с исходным кодом веб-сервиса можно вручную или автоматически с помощью компилятора.

Вызов платёжной формы

Запрос для вызова Payment Page включает в себя набор параметров, подписываемых для обеспечения защиты данных при передаче запроса в платёжную платформу Benker. SDK for Go позволяет автоматически подписывать используемые параметры. Для вызова Payment Page с применением SDK for Go следует:

Создать объект класса payment и указать значения параметров платежа.

payment := paymentpage.NewPayment(186, "1555943554067")
    // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта
payment.SetParam(paymentpage.ParamPaymentCurrency, "EUR")
    // Код валюты в формате ISO-4217 alpha-3
payment.SetParam(paymentpage.ParamPaymentAmount, 1000)
    // Сумма в дробных единицах валюты
payment.SetParam(paymentpage.ParamCustomerId, "customer_122")
    // Идентификатор пользователя
payment.SetParam(paymentpage.ParamPaymentDescription, "Тестовый платёж")
    // Описание платежа. Необязательный параметр

Все параметры в данном примере, за исключением описания платежа, являются необходимыми для любой оплаты.

Дополнительно можно использовать любые другие параметры из числа доступных для работы с Payment Page. Подробнее о доступных параметрах — в разделе Параметры вызова платёжной формы.

Создать объект класса gate и указать значение секретного ключа, полученное от платёжной платформы Benker. Секретный ключ необходим для автоматического подписывания параметров.
```
gate := paymentpage.NewGate("<secret_key>")
    // Секретный ключ проекта, полученный при интеграции от Benker
```
Сформировать адрес для вызова платёжной формы.
```
paymentPageUrl := gate.GetPaymentPageUrl(*payment)
```
Корректный адрес для вызова платёжной формы содержит подпись и параметры платежа:
```
https://paymentpage.benker.io/payment?signature=OEKRtJiKStyoH%M36hokU
zLZsuB2gO8JALVnyevcV59akRi29elbheVscAEl0lXDE390M%3D%3D&payment_id=1555943554067...
```
Использовать сформированный адрес для вызова платёжной формы (подробнее).

Далее приведён пример формирования адреса для вызова платёжной формы Payment Page с открытием на английском языке. На странице с выбором платежных методов обеспечивается отображение информации о платеже: идентификатора, валюты, суммы и описания платежа.

Рис. 1. Пример формирования адреса для вызова Payment Page

payment := paymentpage.NewPayment(186, "payment_id")
    // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта
payment.SetParam(paymentpage.ParamPaymentCurrency, "EUR")
    // Код валюты в формате ISO-4217 alpha-3
payment.SetParam(paymentpage.ParamPaymentAmount, 1000)
    // Сумма в дробных единицах валюты
payment.SetParam(paymentpage.ParamCustomerID, "customer_112")
    // Идентификатор пользователя
payment.SetParam(paymentpage.ParamPaymentDescription, "Тестовый платёж")
    // Описание платежа. Необязательный параметр
payment.SetParam(paymentpage.ParamLanguageCode, "en")
    // Код языка, на котором платёжная форма открывается пользователю. Необязательный параметр
gate := paymentpage.NewGate("<secret_key>")
    // Секретный ключ проекта, полученный при интеграции от Benker
paymentPageUrl := gate.GetPaymentPageUrl(*payment)
    // Готовый запрос с подписью

Обработка оповещений

Информацию о результатах проведения платежей можно получать в оповещениях, отправляемых со стороны Benker на URL, который необходимо сообщить службе технической поддержки Benker. Оповещение представляет собой HTTP POST запрос с данными в формате JSON-строки. Чтобы извлечь информацию о результате проведения платежа из JSON-строки, необходимо:

Создать объект класса gate и указать значение секретного ключа, полученного от Benker.
```
gate := paymentpage.NewGate("<secret_key>")
```
Создать объект класса callback, используя JSON-строку с информацией о платеже из оповещения от Benker:
```
callback, err := gate.HandleCallback(data)
```
Если подпись некорректная или не удаётся извлечь данные из оповещения, возвращается интерфейс error.

Использовать методы, доступные для работы с оповещениями. Можно получить всю информацию о платеже или информацию только об отдельных параметрах платежа:

callback.GetPaymentId()            // Получение идентификатора платежа
callback.GetPaymentStatus()        // Получение текущего статуса платежа
callback.GetPayment()              // Получение всей информации о платеже

Далее приведён пример оповещения, которое включает в себя подпись и информацию о результатах проведения платежа. При использовании SDK for Go проверка подписи в оповещении выполняется автоматически.

Рис. 2. Пример данных из оповещения о проведении оплаты

POST /notify/success HTTP/1.1
Content-Length: 1237
User-Agent: GuzzleHttp/6.3.3 curl/7.47.0 PHP/7.0.32-0ubuntu0.16.04.1
Content-Type: application/json
Host: webservice.com

{
  "project_id": 200,
  "payment": {
    "id": "abc12345",
    "type": "purchase",
    "status": "success",
    "date": "2025-03-20T14:22:06+0000",
    "method": "Greek Banks",
    "sum": {
      "amount": 1000,
      "currency": "EUR"
    },
    "description": "Success"
  },
  "customer": {
    "id": "123"
  },
  "operation": {
    "id": 9529253065607,
    "type": "sale",
    "status": "success",
    "date": "2025-03-20T14:22:06+0000",
    "created_date": "2025-03-20T14:22:00+0000",
    "request_id": "f1de353331a01fd14163fe4226-00009530",
    "sum_initial": {
      "amount": 1000,
      "currency": "EUR"
    },
    "sum_converted": {
      "amount": 1000,
      "currency": "EUR"
    },
    "code": "0",
    "message": "Success",
    "provider": {
      "id": 1914,
      "payment_id": "",
      "auth_code": ""
    }
  },
  "signature": "OBjT3RaJnOWsDXOclvWoC6+CFSCtLprTo8VFbN6BYVQD2tVK/3d9k+RRA/7N9TV6OQqk+0uPUnx4/c8uaUurw=="
}

Дополнительные материалы

Для организации работы с оповещениями также могут быть полезны следующие материалы: