SDK для Go

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

SDK для Go совместим с Go версии 1.8 или выше и доступен для загрузки на GitHub по следующей ссылке: https://github.com/ITECOMMPAY/paymentpage-sdk-go.

Возможности

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

Состав

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

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

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

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

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

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

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

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

  1. Если не настроена переменная окружения $GOPATH — настроить. Поиск внешних библиотек и их зависимостей выполняется в каталогах, прописанных в переменную $GOPATH.
  2. В командной строке компилятора выполнить следующую команду:
    go get github.com/ITECOMMPAY/paymentpage-sdk-go
    Эта команда служит для размещения загруженных библиотек в каталоге, указанном в переменной $GOPATH.
  3. Подключить SDK для Go в исходном коде веб-сервиса в секции import, выполнив команду:
    import "github.com/ITECOMMPAY/paymentpage-sdk-go"

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

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

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

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

  1. Создать объект класса payment и указать значения параметров платежа.
    payment := paymentpage.NewPayment(186, "1555943554067")
    // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта
payment.SetParam(paymentpage.ParamPaymentCurrency, "EUR")
    // Код валюты в формате ISO-4217 alpha-3
payment.SetParam(paymentpage.ParamPaymentAmount, 1000)
    // Сумма в дробных единицах валюты
payment.SetParam(paymentpage.ParamPaymentDescription, "Тестовый платёж")
    // Описание платежа. Необязательный параметр

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

    payment.SetParam(paymentpage.ParamCustomerPhone, "The customer's phone number. Must have from 4 to 24 digits")
payment.SetParam(paymentpage.ParamCustomerEmail, "The customer's email")

    Кроме того, для оплат с использованием платёжных карт рекомендуется передавать сведения о платёжном адресе пользователя: код страны в формате ISO 3166-1 alpha-2 (подробнее), индекс, названия города и улицы. Эти сведения указываются следующим образом.

    payment.SetParam(paymentpage.ParamBillingPostal, "The postal code of the customer's billing address")
payment.SetParam(paymentpage.ParamBillingCountry, "The country of the customer's billing address, in ISO 3166-1 alpha-2")
payment.SetParam(paymentpage.ParamBillingCity, "The city of the customer's billing address")
payment.SetParam(paymentpage.ParamBillingAddress, "The street of the customer's billing address")

    Дополнительно можно использовать любые другие параметры из числа доступных для работы с Payment Page. Подробнее о доступных параметрах — в разделе Параметры вызова платёжной формы.

  2. Создать объект класса gate и указать значение секретного ключа, полученное от платёжной платформы ecommpay. Секретный ключ необходим для автоматического подписывания параметров.
    gate := paymentpage.NewGate("<secret_key>")
    // Секретный ключ проекта, полученный при интеграции от ecommpay
  3. Сформировать запрос для вызова платёжной формы.
    paymentPageUrl := gate.GetPaymentPageUrl(*payment)
    Корректный запрос для вызова платёжной формы содержит подпись и параметры платежа:
    https://paymentpage.ecommpay.com/payment?signature=OEKRtJiKStyoH%M36hokU
zLZsuB2gO8JALVnyevcV59akRi29elbheVscAEl0lXDE390M%3D%3D&payment_id=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 := paymentpage.NewPayment(186, "payment_id")
    // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта
payment.SetParam(paymentpage.ParamPaymentCurrency, "EUR")
    // Код валюты в формате ISO-4217 alpha-3
payment.SetParam(paymentpage.ParamPaymentAmount, 1000)
    // Сумма в дробных единицах валюты
payment.SetParam(paymentpage.ParamPaymentDescription, "Тестовый платёж")
    // Описание платежа. Необязательный параметр
payment.SetParam(paymentpage.ParamLanguageCode, "en")
    // Код языка, на котором Payment Page открывается пользователю. Необязательный параметр
gate := paymentpage.NewGate("<secret_key>")
    // Секретный ключ проекта, полученный при интеграции от ecommpay
paymentPageUrl := gate.GetPaymentPageUrl(*payment)
    // Готовый запрос с подписью

Обработка оповещений

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

  1. Создать объект класса gate и указать значение секретного ключа, полученного от ecommpay.
    gate := paymentpage.NewGate("<secret_key>")
  2. Создать объект класса callback, используя JSON-строку с информацией о платеже из оповещения от ecommpay: 
    callback, err := gate.HandleCallback(data)

    Если подпись некорректная или не удаётся извлечь данные из оповещения, возвращается интерфейс error.

  3. Использовать методы, доступные для работы с оповещениями. Можно получить всю информацию о платеже или информацию только об отдельных параметрах платежа:
    callback.GetPaymentId()            // Получение идентификатора платежа
callback.GetPaymentStatus()        // Получение текущего статуса платежа
callback.GetPayment()              // Получение всей информации о платеже

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

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

{
      "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, отображающий результат аутентификации  
      },
      "signature": "22YlUIIgoppli/JX8w5F5+c2h12RXi81WLmgDx..."   // Подпись оповещения
  }

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

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