SDK для Python

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

SDK для Python совместим с Python версии 3.5 или выше и доступен для загрузки по следующим ссылкам:

GitHub: https://github.com/ITECOMMPAY/paymentpage-sdk-python,
PyPI: https://pypi.org/project/ecommpay-sdk/.

Возможности

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

подписывать набор параметров платежа и формировать запрос для вызова 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.PaymentPage.SDK
```

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

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

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

Внимание: С 12 августа 2024 года в связи с вступлением в силу новых требований платёжной системы Visa расширяется набор параметров, необходимых для аутентификации 3‑D Secure при проведении оплат с использованием карт этой платёжной системы. Для таких случаев становится обязательным передавать номер телефона пользователя или адрес его электронной почты. По крайней мере один их этих параметров необходимо указывать при создании объекта класса Payment.

Вместе с тем, рекомендуется передавать эти и ряд других параметров (с информацией о платёжном адресе пользователя) для проведения оплат с использованием карт всех платёжных систем, поскольку по данным платёжной системы Visa полноценное использование таких параметров может существенно (вплоть до 6 %) повышать проходимость платежей и кардинально (вплоть до 65 %) снижать число операций, признаваемых мошенническими после их выполнения.

Запрос для вызова 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 с открытием на английском языке. На странице с выбором платежных методов обеспечивается отображение информации о платеже: идентификатора, валюты, суммы и описания платежа.

Рис.: Пример формирования запроса на открытие Payment Page

payment = Payment('186', '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)
    // Готовый запрос с подписью

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

При работе с 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 проверка подписи в оповещении выполняется автоматически.

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

{
      "project_id": 186,       // Идентификатор проекта
      "payment": {             // Информация о платеже
          "id": "1555943554067",        // Идентификатор платежа
          "type": "purchase",  // Тип платежа
          "status": "success", // Статус платежа
          "date": "2021-08-28T09:11:28+0000",  // Дата и время проведения платежа
          "method": "card",  // Платёжный метод
          "sum": {           // Сумма и валюта платежа
            "amount": 1000,
            "currency": "EUR"
          },
          "description": "Тестовый платёж"  // Описание платежа
      },
      "account": {           // Информация о платёжном средстве
          "number": "431422******0056",
          "token": "9cb38282187b7a5b5b91b5814c6b814162741b29c0c486fbbc500cd451abb8b2",
          "type": "visa",
          "card_holder": "ADA LOVELACE",
          "id": 778804,
          "expiry_month": "11",
          "expiry_year": "2024"
      },
      "operation": {     // Информация о последней операции в рамках платежа
        "id": 17839000001150,  // Идентификатор операции
        "type": "sale",        // Тип операции
        "status": "success",   // Статус операции
        "date": "2021-08-28T09:11:28+0000", // Дата и время проведения операции
        "created_date": "2021-08-28T09:10:50+0000",
        "request_id": "2c8af331519833f2c96c4a1aaf60edfcffb...", // Идентификатор запроса
        "sum_initial": {    // Сумма и валюта операции, указанные в запросе
          "amount": 1000,
          "currency": "EUR"
        },
        "sum_converted": {
          // Сумма и валюта операции с учётом настроенных для проекта правил конвертации
            "amount": 1000,
            "currency": "EUR"
        },
        "provider": {     // Информация о проведении платежа в платёжной системе
          "id": 6,
          "payment_id": "15354474886323",
          "date": "2021-02-07T08:34:24+0000",
          "auth_code": "563253",
          "endpoint_id": 6
        },
        "code": "0",          // Унифицированный код ответа
        "message": "Success", // Расшифровка кода ответа
        "eci": "05"           // Код индикатора ECI, отображающий результат 3D-Secure проверки  
      },
      "signature": "22YlUIIgoppli/JX8w5F5+c2h12RXi81WLmgDx..."   // Подпись оповещения
  }

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

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