SDK for Python

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

Возможности

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

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

Состав

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

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

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

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

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

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

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

Чтобы установить библиотеки с помощью pip и подключить их в исходном коде веб-сервиса, необходимо:

Если не установлена pip — загрузить, установить и настроить (подробнее https://pip.pypa.io/en/stable/).
В командной строке операционной системы в каталоге с исходным кодом веб-сервиса выполнить следующую команду:
```
pip install benker-sdk
```

Подключить модули в исходном коде веб-сервиса:

from payment_page_sdk.gate import Gate
from payment_page_sdk.payment import Payment

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

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

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

payment = Payment('186', '1555943554067')
    // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта
payment.payment_amount = 1001
    // Сумма в дробных единицах валюты
payment.payment_currency = 'EUR'  
    // Код валюты в формате ISO-4217 alpha-3
payment.customer_id = 'customer_112'  
    // Идентификатор пользователя
payment.payment_description = 'Тестовый платёж'
    // Описание платежа. Необязательный параметр

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

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

Создать объект класса Gate и указать значение секретного ключа, полученное от Benker. Секретный ключ необходим для автоматического подписывания параметров.
```
gate = Gate('<secret_key>')
    // Секретный ключ проекта, полученный при интеграции от Benker
```
Сформировать адрес для вызова платёжной формы.
```
payment_url = gate.get_purchase_payment_page_url(payment)
```
Корректный адрес для вызова платёжной формы содержит подпись и параметры платежа:
```
https://paymentpage.benker.io/payment?signature=OEKRlLXKStyoH%2BM36hokU
zLZsuB2gO8JALVnyevcV59akRi29elbheVscAEl0ljcoQVXDE390MwgWg%3D%3D&payment_id=TEST_1555943554067...
```
Использовать сформированный адрес для вызова платёжной формы (подробнее).

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

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

payment = Payment('186', '1555943554067')
    // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта
payment.payment_amount = 1001
    // Сумма в дробных единицах валюты
payment.payment_currency = 'RUB'  
    // Код валюты в формате ISO-4217 alpha-3
payment.customer_id = 'customer_112'  
    // Идентификатор пользователя
payment.payment_description = 'Тестовый платёж'
    // Описание платежа. Необязательный параметр
payment.language_code = 'en'
    // Код языка, на котором Payment Page открывается пользователю  
gate = Gate('<secret_key>')
    // Секретный ключ проекта, полученный при интеграции от Benker
payment_url = gate.get_purchase_payment_page_url(payment)
    // Готовый запрос с подписью

Использование режима отладки

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

Перед началом отладки следует обеспечить возможность отправки HTTP-запросов со стороны серверной части веб-сервиса к ресурсу sdk.benker.io. После этого в рамках отладки можно задавать различные параметры вызова платёжной формы (как тестовые, так и реальные) и анализировать информацию об ошибках. Для этого используется код следующего вида:

payment = Payment(<project_id>, "<payment_id_in_your_service>")
payment.payment_amount = 1001
payment.payment_currency = 'EUR'
payment.payment_description = 'Тестовый платёж'
 
gate = Gate("<secret_key>")
 
try:  # Попытка выполнения кода
    return gate.get_purchase_payment_page_url(payment)  
    # Получение ссылки на открытие платёжной формы
except ValidationException as e:  # Обработка возможных исключений
    print(e)  # Вывод сообщения об ошибке в консоль
 
return null

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

One or more parameters is not valid:
 
Customer_id:
    Must be not null  // Не указан идентификатор пользователя, обязательный для запроса
Account_token:
    Invalid account token  // Указан некорректный токен

При отсутствии ошибок можно считать полученную ссылку на открытие Payment Page корректной.

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

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

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

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

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

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

Рис. 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=="
}

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

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