SDK для Python
SDK для Python — это набор средств разработки для взаимодействия веб-сервисов, разработанных на Python, с платёжной платформой ecommpay при проведении оплат через Payment Page. В этом разделе представлена информация о работе с SDK для Python с примерами кода на языке программирования Python.
SDK для Python совместим с Python версии 3.5 или выше и доступен для загрузки по следующим ссылкам:
Возможности
- подписывать набор параметров платежа и формировать запрос для вызова Payment Page,
- проверять подлинность оповещений от ecommpay и получать из них информацию о платежах.
Состав
SDK для Python содержит библиотеку для разработки и автоматизированного тестирования, а также служебные файлы.
Порядок работы
Для использования SDK для Python необходимо:
- Решить организационные вопросы, касающиеся взаимодействия с ecommpay:
- Если у компании нет идентификатора проекта и ключа для взаимодействия с ecommpay — отправить заявку на подключение по ссылке https://ecommpay.com/apply-now/.
- Если у компании есть идентификатор и ключ для взаимодействия с ecommpay есть — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK для Python и согласовать с ними порядок тестирования.
- Установить библиотеки, входящие в состав SDK для Python, и подключить их в коде, а также доработать код для использования необходимой функциональности.
- Протестировать и запустить в работу обновлённый исходный код веб-сервиса.
- Для тестирования следует использовать тестовый идентификатор проекта, тестовые значения параметров платежа.
- Для перевода в рабочий режим необходимо заменить тестовое значение project_id на рабочее, полученное от ecommpay.
При возникновении вопросов о работе с SDK для Python следует обращаться в службу технической поддержки ecommpay по адресу support@ecommpay.com.
Установка и подключение библиотек
Устанавливать библиотеки, входящие в состав SDK для Python, в проект с исходным кодом веб-сервиса можно вручную или автоматически с помощью системы управления пакетами pip, которая обеспечивает загрузку необходимых библиотек из репозитория.
Чтобы установить библиотеки с помощью pip и подключить их в исходном коде веб-сервиса, необходимо:
- Если не установлена pip — загрузить, установить и настроить (подробнее https://pip.pypa.io/en/stable/).
- В командной строке операционной системы в каталоге с исходным кодом веб-сервиса выполнить следующую команду:
pip install ecommpay-sdk
- Подключить модули в исходном коде веб-сервиса:
from payment_page_sdk.gate import Gate from payment_page_sdk.payment import Payment
Вызов платёжной формы
Запрос для вызова Payment Page формируется из набора параметров, подписываемых для обеспечения защиты данных при передаче запроса в платёжную платформу ecommpay. SDK для Python позволяет автоматически подписывать параметры и формировать из них запрос. Для вызова Payment Page с использованием SDK для Python следует:
- Создать объект класса
Payment
и указать значения параметров платежа.payment = Payment('186', '1555943554067') // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта payment.payment_amount = 1001 // Сумма в дробных единицах валюты payment.payment_currency = 'EUR' // Код валюты в формате ISO-4217 alpha-3 payment.payment_description = 'Тестовый платёж' // Описание платежа. Необязательный параметр
Все параметры в данном примере, за исключением описания платежа, являются необходимыми для любой оплаты. Также могут потребоваться и другие параметры, например адрес электронной почты пользователя или его номер телефона для выполнения аутентификации 3‑D Secure. Их необходимо указывать следующим образом.
payment.customer_phone = 'The customer phone number. Must have from 4 to 24 digits' payment.customer_email = 'The customer email'
Кроме того, для оплат с использованием платёжных карт рекомендуется передавать сведения о платёжном адресе пользователя: код страны в формате ISO 3166-1 alpha-2 (подробнее), индекс, названия города и улицы. Эти сведения указываются следующим образом.
payment.billing_postal = 'The postal code of the customer billing address' payment.billing_country = 'The country of the customer billing address, in ISO 3166-1 alpha-2' payment.billing_city = 'The city of the customer billing address' payment.billing_address = 'The street of the customer billing address'
Дополнительно можно использовать любые другие параметры из числа доступных для работы с Payment Page. Подробнее о доступных параметрах — в разделе Параметры вызова платёжной формы.
- Создать объект класса
Gate
и указать значение секретного ключа, полученное от ecommpay. Секретный ключ необходим для автоматического подписывания параметров.gate = Gate('<secret_key>') // Секретный ключ проекта, полученный при интеграции от ecommpay
- Сформировать запрос для вызова платёжной формы.
payment_url = gate.get_purchase_payment_page_url(payment)
Корректный запрос для вызова платёжной формы содержит подпись и параметры платежа:https://paymentpage.ecommpay.com/payment?signature=OEKRlLXKStyoH%2BM36hokU zLZsuB2gO8JALVnyevcV59akRi29elbheVscAEl0ljcoQVXDE390MwgWg%3D%3D&payment_id=TEST_1555943554067...
- Использовать сформированный запрос для вызова платёжной формы, например следующим образом:
<link rel="stylesheet" href="https://paymentpage.ecommpay.com/shared/merchant.css" /> <script type="text/javascript" src="https://paymentpage.ecommpay.com/shared/merchant.js"></script> <script type="text/javascript"> EPayWidget.run({ baseUrl: '<URL, полученный на предыдущем шаге>'}, 'get'); </script>
Другие варианты вызова платёжной формы описаны в разделе Способы открытия платёжной формы.
Далее приведён пример формирования запроса для вызова платёжной формы Payment Page с открытием на английском языке. На странице с выбором платежных методов обеспечивается отображение информации о платеже: идентификатора, валюты, суммы и описания платежа.
Использование режима отладки
При работе с SDK для Python поддерживается режим отладки, который позволяет проверять полноту и корректность указанных параметров и получать информацию о допущенных ошибках.
Перед началом отладки следует обеспечить возможность отправки HTTP-запросов со стороны серверной части веб-сервиса к ресурсу sdk.ecommpay.com
. После этого в рамках отладки можно задавать различные параметры вызова платёжной формы (как тестовые, так и реальные) и анализировать информацию об ошибках. Для этого используется код следующего вида:
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 корректной.
Обработка оповещений
Информацию о результатах проведения платежей можно получать в оповещениях, отправляемых со стороны ecommpay на URL, который необходимо сообщить службе технической поддержки ecommpay. Оповещение представляет собой HTTP POST запрос с данными в формате JSON-строки. Чтобы извлечь информацию о результате проведения платежа из JSON-строки, необходимо:
- Если ранее, при формировании запроса для вызова Payment Page, не был создан объект класса
Gate
, создать объект и указать значение секретного ключа, полученного от ecommpay.gate = Gate('<secret_key>')
- Создать объект класса
Сallback
, используя JSON-строку с информацией о платеже из оповещения от платёжной платформы ecommpay:callback = gate.handle_callback(data)
- Использовать методы, доступные для работы с оповещениями. Можно получить всю информацию о платеже или информацию только об отдельных параметрах платежа:
callback.get_payment_id() // Получение идентификатора платежа callback.get_payment_status() // Получение текущего статуса платежа callback.get_payment() // Получение всей информации о платеже
Далее приведён пример данных из оповещения, которое включает в себя подпись и информацию о результатах проведения платежа. При использовании SDK для Python проверка подписи в оповещении выполняется автоматически.