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"

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

Запрос для вызова 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.ParamCustomerId, "customer_122")
    // Идентификатор пользователя
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. Использовать сформированный адрес для вызова платёжной формы (подробнее).

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

Рис. 1. Пример формирования адреса для вызова 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.ParamCustomerID, "customer_112")
    // Идентификатор пользователя
payment.SetParam(paymentpage.ParamPaymentDescription, "Тестовый платёж")
    // Описание платежа. Необязательный параметр
payment.SetParam(paymentpage.ParamLanguageCode, "en")
    // Код языка, на котором платёжная форма открывается пользователю. Необязательный параметр
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 проверка подписи в оповещении выполняется автоматически.

Рис. 2. Пример данных из оповещения о проведении оплаты 
{
      "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..."   // Подпись оповещения
  }

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

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