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.

Возможности

SDK для JavaSDK для Java позволяет:
  • подписывать набор параметров платежа и формировать запрос для вызова Payment Page,
  • проверять подлинность оповещений от ecommpay и получать из них информацию о платежах.

Состав

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

Порядок работы

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

  1. Решить организационные вопросы, касающиеся взаимодействия с ecommpay:
    • Если у компании нет идентификатора проекта и ключа для взаимодействия с ecommpay — отправить заявку на подключение по ссылке https://ecommpay.com/apply-now/.
    • Если у компании есть идентификатор и ключ для взаимодействия с ecommpay — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK для Java и согласовать с ними порядок тестирования.
  2. Установить библиотеки, входящие в состав SDK для Java, в каталог с исходным кодом веб-сервиса и подключить их в коде, а также доработать код для использования необходимой функциональности.
  3. Протестировать и запустить в работу обновлённый исходный код веб-сервиса.
    • Для тестирования следует использовать тестовый идентификатор проекта, тестовые значения параметров платежа и пример оповещения из библиотеки test/java.
    • Для перевода в рабочий режим необходимо заменить тестовое значение project_id на рабочее, полученное от ecommpay.

При возникновении вопросов о работе с SDK для Java следует обращаться в службу технической поддержки ecommpay по адресу support@ecommpay.com.

Установка и подключение библиотек

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

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

  1. Загрузить SDK для Java и сформировать JAR-архив из файлов, входящих в SDK.
  2. Если в каталоге проекта с исходных кодом веб-сервиса не создан каталог libs, необходимо создать его. Поместить в каталог libs JAR-архив.
  3. Подключить файл в проекте с исходным кодом веб-сервиса.

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

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

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

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

  1. Создать объект класса Payment и указать значения параметров платежа.
    Payment payment = new Payment('186', "1555943554067");
        // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта
payment
    .setParam(Payment.PAYMENT_AMOUNT, 1001)
        // Сумма в дробных единицах валюты
    .setParam(Payment.PAYMENT_CURRENCY, "EUR")
        // Код валюты в формате ISO-4217 alpha-3
    .setParam(Payment.PAYMENT_DESCRIPTION, "Тестовый платёж");
       // Описание платежа. Необязательный параметр

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

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

    .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. Подробнее о доступных параметрах — в разделе Параметры вызова платёжной формы.

  2. Создать объект класса Gate и указать значение секретного ключа, полученное от ecommpay. Секретный ключ необходим для автоматического подписывания параметров.
    Gate gate = new Gate("<secret_key>");
    // Секретный ключ проекта, полученный при интеграции от ecommpay
  3. Сформировать запрос для вызова платёжной формы.
    String paymentUrl = gate.getPurchasePaymentPageUrl(payment);
    Корректный запрос для вызова платёжной формы содержит подпись и параметры платежа:
    https://paymentpage.ecommpay.com/payment?signature=OEKRlLoH%2BM36hokU
zLZsuB2gO8JALVnyevcV59akRi29elb390MwgWg%3D%3D&payment_id=TEST_1555943554067...
  4. Использовать сформированный запрос для вызова платёжной формы, например следующим образом:
    <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 = new Payment('186', "1555943554067");
        // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта
payment
    .setParam(Payment.PAYMENT_AMOUNT, 1001)
        // Сумма в дробных единицах валюты
    .setParam(Payment.PAYMENT_CURRENCY, "EUR")
        // Код валюты в формате ISO-4217 alpha-3
    .setParam(Payment.PAYMENT_DESCRIPTION, "Тестовый платёж")
       // Описание платежа. Необязательный параметр
    .setParam(Payment.LANGUAGE_CODE, ("en")
    // Код языка, на котором Payment Page открывается пользователю  
Gate gate = new Gate("<secret_key>");
    // Секретный ключ проекта, полученный при интеграции от ecommpay
String paymentUrl = gate.getPurchasePaymentPageUrl(payment);
    // Готовый запрос с подписью

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

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

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

Payment payment = new Payment(<project_id>, "<payment_id_in_your_service>");
payment.payment_amount = 1001;
payment.payment_currency = "EUR";
payment.payment_description = "Тестовый платёж";
 
Gate gate = new Gate('<secret_key>');
 
try {
    return gate.getPurchasePaymentPageUrl(payment);  
    // Получение ссылки на открытие платёжной формы
} catch (ValidationException e) { // Обработка возможных исключений
    System.out.println(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-строки, необходимо:

  1. Если ранее, при формировании запроса для вызова Payment Page, не был создан объект класса Gate, создать его и указать значение секретного ключа, полученного от ecommpay.
    Gate gate = new Gate("<secret_key>");
  2. Создать объект класса Callback, используя JSON-строку с информацией о платеже из оповещения от ecommpay:
    Callback callback = gate.handleCallback(data);
  3. Использовать методы, доступные для работы с оповещениями. Можно получить всю информацию о платеже или информацию только об отдельных параметрах платежа:
    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..."   // Подпись оповещения
  }

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

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