# SDK для Python {#ru_sdk_python}

статья о порядке применения SDK для создания и проверки подписи к данным в рамках веб-сервисов, разработанных на языке Python

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

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

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

## Возможности {#section_mdv_1pf_nhb .section}

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

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

## Состав {#section_rlb_55f_nhb .section}

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

## Порядок работы {#section_ow5_sdb_mhb .section}

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

1.  Решить организационные вопросы, касающиеся взаимодействия с Ecommpay:
    -   Если у компании нет идентификатора проекта и ключа для взаимодействия с Ecommpay — отправить заявку на подключениепо ссылке [https://ecommpay.com/apply-now/](https://ecommpay.com/apply-now/).
    -   Если у компании есть идентификатор и ключ для взаимодействия с Ecommpay — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK для Python и согласовать с ними порядок тестирования.
2.  Установить библиотеки, входящие в состав SDK для Python, и подключить их в коде, а также доработать код для использования необходимой функциональности.
3.  Протестировать и запустить в работу обновлённый исходный код веб-сервиса.
    -   Для тестирования следует использовать тестовый идентификатор проекта, тестовые значения параметров платежа.
    -   Для перевода в рабочий режим необходимо заменить тестовое значение project\_id на рабочее, полученное от Ecommpay.

При возникновении вопросов о работе с SDK для Python следует обращаться в службу технической поддержки Ecommpay по адресу [support@ecommpay.com](mailto:support@ecommpay.com).

## Установка и подключение библиотек {#section_y13_j32_nhb .section}

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

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

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

    ```language-python
    pip install ecommpay-sdk
    ```

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

    ```language-python
    from payment_page_sdk.gate import Gate
    from payment_page_sdk.payment import Payment
    ```


## Вызов платёжной формы {#section_bty_ryn_lhb .section}

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

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

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

    Все параметры в данном примере, за исключением описания платежа, являются необходимыми для любой оплаты.Также могут потребоваться и другие параметры, например адрес электронной почты пользователя или его номер телефона для выполнения аутентификации 3‑D Secure. Их необходимо указывать следующим образом.

    ```language-python
    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 \([подробнее](ru_country_codes.md)\), индекс, названия города и улицы. Эти сведения указываются следующим образом.

    ```language-python
    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. Подробнее о доступных параметрах — в разделе [Спецификация Payment Page API](ru_PP_Parameters.md).

2.  Создать объект класса `Gate` и указать значение секретного ключа, полученное от Ecommpay. Секретный ключ необходим для автоматического подписывания параметров.

    ```language-python
    gate = Gate('<*secret\_key*>')
        // Секретный ключ проекта, полученный при интеграции от Ecommpay
    ```

3.  Сформировать адрес для вызова платёжной формы.

    ```language-python
    payment_url = gate.get_purchase_payment_page_url(payment)
    ```

    Корректный адрес для вызова платёжной формы содержит подпись и параметры платежа:

    ```language-python
    https://paymentpage.ecommpay.com/payment?signature=OEKRlLXKStyoH%2BM36hokU
    zLZsuB2gO8JALVnyevcV59akRi29elbheVscAEl0ljcoQVXDE390MwgWg%3D%3D&payment_id=TEST_1555943554067...
    ```

4.  Использовать сформированный адрес для вызова платёжной формы \([подробнее](ru_PP_Integration.md)\).

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

```language-python
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*>')
    // Секретный ключ проекта, полученный при интеграции от Ecommpay
payment_url = gate.get_purchase_payment_page_url(payment)
    // Готовый запрос с подписью
```

## Использование режима отладки {#section_s5f_rq1_g5b .section}

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

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

```language-python
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
```

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

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

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

## Обработка оповещений {#section_qxm_m24_lhb .section}

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

1.  Если ранее, при формировании запроса для вызова Payment Page, не был создан объект класса `Gate`, создать объект и указать значение секретного ключа, полученного от Ecommpay.

    ```language-python
    gate = Gate('<*secret\_key*>')
    ```

2.  Создать объект класса `Сallback`, используя **JSON**-строку с информацией о платеже из оповещения от платёжной платформы Ecommpay:

    ```language-python
    callback = gate.handle_callback(data)
    ```

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

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


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

```language-json
{
      "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..."   // Подпись оповещения
  }
```

## Дополнительные материалы {#section_j2l_4h2_plb .section}

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

-   [Работа с оповещениями](ru_platform_callbacks.md)
-   [Проведение платежей](ru_platform_payment_model.md)

**На уровень выше:**[Интеграция с использованием SDK](ru_sdk_overview.md)