# SDK для Java {#ru_sdk_java} статья о порядке применения SDK для создания и проверки подписи к данным в рамках веб-сервисов, разработанных на языке Java SDK для Java — это набор средств разработки для взаимодействия веб-сервисов, разработанных на Java, с платёжной платформой Ecommpay при проведении оплат через Payment Page. В этом разделе представлена информация о работе с SDK для Java с примерами кода на языке программирования Java. SDK для Java совместим с Java SE Development Kit версии 8 или выше и доступен для загрузки на GitHub по следующей ссылке: [https://github.com/ITECOMMPAY/paymentpage-sdk-java](https://github.com/ITECOMMPAY/paymentpage-sdk-java). ## Возможности {#section_mdv_1pf_nhb .section} SDK для JavaSDK для Java позволяет: - подписывать набор параметров платежа и формировать адрес для вызова Payment Page, - проверять подлинность оповещений от Ecommpay и получать из них информацию о платежах. ## Состав {#section_rlb_55f_nhb .section} SDK для Java содержит библиотеки для разработки и автоматизированного тестирования, а также служебные файлы. ## Порядок работы {#section_ow5_sdb_mhb .section} Для использования SDK для Java необходимо: 1. Решить организационные вопросы, касающиеся взаимодействия с Ecommpay: - Если у компании нет идентификатора проекта и ключа для взаимодействия с Ecommpay — отправить заявку на подключениепо ссылке [https://ecommpay.com/apply-now/](https://ecommpay.com/apply-now/). - Если у компании есть идентификатор и ключ для взаимодействия с Ecommpay — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK для Java и согласовать с ними порядок тестирования. 2. Установить библиотеки, входящие в состав SDK для Java, в каталог с исходным кодом веб-сервиса и подключить их в коде, а также доработать код для использования необходимой функциональности. 3. Протестировать и запустить в работу обновлённый исходный код веб-сервиса. - Для тестирования следует использовать тестовый идентификатор проекта, тестовые значения параметров платежа и пример оповещения из библиотеки **test/java**. - Для перевода в рабочий режим необходимо заменить тестовое значение project\_id на рабочее, полученное от Ecommpay. При возникновении вопросов о работе с SDK для Java следует обращаться в службу технической поддержки Ecommpay по адресу [support@ecommpay.com](mailto:support@ecommpay.com). ## Установка и подключение библиотек {#section_y13_j32_nhb .section} Устанавливать библиотеки, входящие в состав SDK для Java, в проект с исходным кодом веб-сервиса можно вручную или автоматически. Способы установки и подключения библиотек могут отличаться в зависимости от среды разработки. Чтобы установить библиотеки вручную и подключить их в исходном коде веб-сервиса, необходимо: 1. Загрузить SDK для Java и сформировать JAR-архив из файлов, входящих в SDK. 2. Если в каталоге проекта с исходных кодом веб-сервиса не создан каталог **libs**, необходимо создать его. Поместить в каталог **libs** JAR-архив. 3. Подключить файл в проекте с исходным кодом веб-сервиса. ## Вызов платёжной формы {#section_bty_ryn_lhb .section} Запрос для вызова Payment Page включает в себя набор параметров, подписываемых для обеспечения защиты данных при передаче запроса в платёжную платформу Ecommpay. SDK для Java позволяет автоматически подписывать используемые параметры. Для вызова Payment Page с применением SDK для Java следует: 1. Создать объект класса `Payment` и указать значения параметров платежа. ```language-java Payment payment = new Payment('186', "1555943554067"); // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта payment .setParam(Payment.PAYMENT_AMOUNT, 1001) // Сумма в дробных единицах валюты .setParam(Payment.PAYMENT_CURRENCY, "EUR") // Код валюты в формате ISO-4217 alpha-3 .setParam(Payment.CUSTOMER_ID, "customer_112") // Идентификатор пользователя .setParam(Payment.PAYMENT_DESCRIPTION, "Тестовый платёж"); // Описание платежа. Необязательный параметр ``` Все параметры в данном примере, за исключением описания платежа, являются необходимыми для любой оплаты.Также могут потребоваться и другие параметры, например адрес электронной почты пользователя или его номер телефона для выполнения аутентификации 3‑D Secure. Их необходимо указывать следующим образом. ```language-java .setParam(Payment.CUSTOMER_PHONE, "The customer's phone number. Must have from 4 to 24 digits") .setParam(Payment.CUSTOMER_EMAIL, "The customer's email") ``` Кроме того, для оплат с использованием платёжных карт рекомендуется передавать сведения о платёжном адресе пользователя: код страны в формате ISO 3166-1 alpha-2 \([подробнее](ru_country_codes.md)\), индекс, названия города и улицы. Эти сведения указываются следующим образом. ```language-java .setParam(Payment.BILLING_POSTAL, "The postal code of the customer's billing address") .setParam(Payment.BILLING_COUNTRY, "The country of the customer's billing address, in ISO 3166-1 alpha-2t") .setParam(Payment.BILLING_CITY, "The city of the customer's billing address") .setParam(Payment.BILLING_ADDRESS, "The street of the customer's billing address") ``` Дополнительно можно использовать любые другие параметры из числа доступных для работы с Payment Page. Подробнее о доступных параметрах — в разделе [Спецификация Payment Page API](ru_PP_Parameters.md). 2. Создать объект класса `Gate` и указать значение секретного ключа, полученное от Ecommpay. Секретный ключ необходим для автоматического подписывания параметров. ```language-java Gate gate = new Gate("<*secret\_key*>"); // Секретный ключ проекта, полученный при интеграции от Ecommpay ``` 3. Сформировать адрес для вызова платёжной формы. ```language-java String paymentUrl = gate.getPurchasePaymentPageUrl(payment); ``` Корректный адрес для вызова платёжной формы содержит подпись и параметры платежа: ```language-java https://paymentpage.ecommpay.com/payment?signature=OEKRlLoH%2BM36hokU zLZsuB2gO8JALVnyevcV59akRi29elb390MwgWg%3D%3D&payment_id=TEST_1555943554067... ``` 4. Использовать сформированный адрес для вызова платёжной формы \([подробнее](ru_PP_Integration.md)\). Далее приведён пример формирования адреса для вызова платёжной формы Payment Page с открытием на английском языке.На странице с выбором платежных методов обеспечивается отображение информации о платеже: идентификатора, валюты, суммы и описания платежа. ```language-java Payment payment = new Payment('186', "1555943554067"); // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта payment .setParam(Payment.PAYMENT_AMOUNT, 1001) // Сумма в дробных единицах валюты .setParam(Payment.PAYMENT_CURRENCY, "EUR") // Код валюты в формате ISO-4217 alpha-3 .setParam(Payment.CUSTOMER_ID, "customer_112") // Идентификатор пользователя .setParam(Payment.PAYMENT_DESCRIPTION, "Тестовый платёж") // Описание платежа. Необязательный параметр .setParam(Payment.LANGUAGE_CODE, ("en") // Код языка, на котором Payment Page открывается пользователю Gate gate = new Gate("<*secret\_key*>"); // Секретный ключ проекта, полученный при интеграции от Ecommpay String paymentUrl = gate.getPurchasePaymentPageUrl(payment); // Готовый запрос с подписью ``` ## Использование режима отладки {#section_xv4_3k1_g5b .section} При работе с SDK для Java поддерживается режим отладки, который позволяет проверять полноту и корректность указанных параметров и получать информацию о допущенных ошибках. Перед началом отладки следует обеспечить возможность отправки HTTP-запросов со стороны серверной части веб-сервиса к ресурсу `sdk.ecommpay.com`. После этого в рамках отладки можно задавать различные параметры вызова платёжной формы \(как тестовые, так и реальные\) и анализировать информацию об ошибках. Для этого используется код следующего вида: ```language-java Payment payment = new Payment(, ""); payment.payment_amount = 1001; payment.payment_currency = "EUR"; payment.customer_id = "customer_112"; payment.payment_description = "Тестовый платёж"; Gate gate = new Gate(''); try { return gate.getPurchasePaymentPageUrl(payment); // Получение ссылки на открытие платёжной формы } catch (ValidationException e) { // Обработка возможных исключений System.out.println(e); // Вывод сообщения об ошибках } return null; ``` Информация о найденных ошибках, полученная в результате выполнения этих действий, в текстовом формате может выглядеть следующим образом: ```language-java 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-java Gate gate = new Gate("<*secret\_key*>"); ``` 2. Создать объект класса `Callback`, используя **JSON**-строку с информацией о платеже из оповещения от Ecommpay: ```language-java Callback callback = gate.handleCallback(data); ``` 3. Использовать методы, доступные для работы с оповещениями. Можно получить всю информацию о платеже или информацию только об отдельных параметрах платежа: ```language-java callback.getPaymentId(); // Получение идентификатора платежа callback.getPaymentStatus(); // Получение текущего статуса платежа callback.getPayment(); // Получение всей информации о платеже ``` Далее приведён пример данных из оповещения, которое включает в себя подпись и информацию о результатах проведения платежа. При использовании SDK для Java проверка подписи в оповещении выполняется автоматически. ``` { "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_e3f_qh2_plb .section} Для организации работы с оповещениями также могут быть полезны следующие материалы: - [Работа с оповещениями](ru_platform_callbacks.md) - [Проведение платежей](ru_platform_payment_model.md) **На уровень выше:**[Интеграция с использованием SDK](ru_sdk_overview.md)