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/ru/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', 'ECT_TEST_1555943554067') // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта payment.payment_amount = 1001 // Сумма в минорных единицах валюты payment.payment_currency = 'RUB' // Валюта в формате ISO-4217 alpha-3 payment.payment_description = 'Тестовый платёж' // Описание платежа. Необязательный параметр
Все параметры в данном примере, за исключением описания платежа, являются необходимыми для любой оплаты. Дополнительно можно использовать любые другие параметры из числа доступных для работы с Payment Page. Подробнее о доступных параметрах — в разделе Параметры открытия платежной формы Payment Page.
- Создать объект класса
Gate
и указать значение секретного ключа, полученное от ECommPay. Секретный ключ необходим для автоматического подписывания параметров.gate = Gate('<secret_key>') // Секретный ключ проекта, полученный при интеграции от ECommPay
- Сформировать запрос для вызова платёжной формы.
payment_url = gate.get_purchase_payment_page_url(payment)
Корректный запрос для вызова платёжной формы содержит подпись и параметры платежа:https://paymentpage.ecommpay.com/payment?signature=OEKRlLXQsa2ntJiKStyoH%2BM36hokU zLZsuB2gO8JALVnyevcV59akRi29elbheVscAEl0ljcoQVXDE390MwgWg%3D%3D&payment_id=ECT_TEST_1555943554067...
- Использовать сформированный запрос для вызова платёжной формы.
Далее приведён пример формирования запроса для вызова платёжной формы Payment Page с открытием на английском языке. На странице с выбором платежных методов обеспечивается отображение информации о платеже: идентификатора, валюты, суммы и описания платежа.
Рис.: Пример формирования запроса на открытие Payment Page
payment = Payment('186', 'ECT_TEST_1555943554067') // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта payment.payment_amount = 1001 // Сумма в минорных единицах валюты payment.payment_currency = 'RUB' // Валюта в формате ISO-4217 alpha-3 payment.payment_description = 'Тестовый платёж' // Описание платежа. Необязательный параметр payment.language_code = 'en' // Код языка, на котором Payment Page открывается пользователю gate = Gate('<secret_key>') // Секретный ключ проекта, полученный при интеграции от ECommPay payment_url = gate.get_purchase_payment_page_url(payment) // Готовый запрос с подписью
Обработка оповещений
Информацию о результатах проведения платежей можно получать в оповещениях, отправляемых со стороны 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 проверка подписи в оповещении выполняется автоматически.
Рис.: Пример оповещения о проведении оплаты
{
"project_id": 186, // Идентификатор проекта
"payment": { // Информация о платеже
"id": "ECT_TEST_1555943554067", // Идентификатор платежа
"type": "purchase", // Тип платежа
"status": "success", // Статус платежа
"date": "2018-08-28T09:11:28+0000", // Дата и время проведения платежа
"method": "card", // Платёжный метод
"sum": { // Сумма и валюта платежа
"amount": 1000,
"currency": "RUB"
},
"description": "Тестовый платёж" // Описание платежа
},
"account": { // Информация о платёжном средстве
"number": "431422******0056",
"token": "9cb38282187b7a5b5b91b5814c6b814162741b29c0c486fbbc500cd451abb8b2",
"type": "visa",
"card_holder": "ADA LOVELACE",
"id": 778804,
"expiry_month": "11",
"expiry_year": "2021"
},
"operation": { // Информация о последней операции в рамках платежа
"id": 17839000001150, // Идентификатор операции
"type": "sale", // Тип операции
"status": "success", // Статус операции
"date": "2018-08-28T09:11:28+0000", // Дата и время проведения операции
"created_date": "2018-08-28T09:10:50+0000",
"request_id": "2c8af331519833f2c96c4a1aaf60edfcffb...", // Идентификатор запроса
"sum_initial": { // Сумма и валюта операции, указанные в запросе
"amount": 1000,
"currency": "RUB"
},
"sum_converted": {
// Сумма и валюта операции с учётом настроенных для проекта правил конвертации
"amount": 1000,
"currency": "RUB"
},
"provider": { // Информация о проведении платежа в платёжной системе
"id": 6,
"payment_id": "15354474886323",
"date": "2018-02-07T08:34:24+0000",
"auth_code": "563253",
"endpoint_id": 6
},
"code": "0", // Унифицированный код ответа
"message": "Success", // Расшифровка кода ответа
"eci": "05" // Код индикатора ECI, отображающий результат 3D-Secure проверки
},
"signature": "22YlUIIgoppli/JX8w5F5+c2h12RXi81WLmgDx..." // Подпись оповещения
}