SDK для PHP

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

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

GitHub: https://github.com/ITECOMMPAY/paymentpage-sdk-php
Packagist: https://packagist.org/packages/ecommpay/paymentpage-sdk

Возможности

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

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

Состав

SDK для PHP содержит библиотеки и служебные файлы. Для работы могут использоваться:

src — библиотеки для разработки,
tests — библиотеки для автоматизированного тестирования,
composer.json — файл, в котором описаны библиотеки.

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

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

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

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

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

Устанавливать библиотеки, входящие в состав SDK для PHP, в проект с исходным кодом веб-сервиса можно вручную или автоматически с помощью менеджера зависимостей. Менеджер зависимостей Composer обеспечивает загрузку необходимых библиотек из репозитория Packagist и формирование скрипта для подключения загруженных библиотек.

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

Если не установлен Composer — загрузить, установить и настроить (подробнее https://getcomposer.org/).
В командной строке операционной системы перейти в каталог с исходным кодом веб-сервиса и выполнить следующую команду:
```
composer require ecommpay/paymentpage-sdk
```
Эта команда служит для размещения загруженных библиотек в каталоге vendor и создания скрипта autoload.php для одновременного подключения всех библиотек в исходном коде веб-сервиса.
Подключить скрипт autoload.php в исходном коде веб-сервиса:
```
require` __DIR__.'../../vendor.autoload.php';
```

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

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

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

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

Создать объект класса Payment и указать значения параметров платежа.
```
$payment = new ecommpay\Payment('186', '1555943554067');
    // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта
$payment->setPaymentAmount(1000)->setPaymentCurrency('EUR');
    // Сумма (в дробных единицах валюты) и код валюты (в формате ISO-4217 alpha-3)
$payment->setPaymentDescription('Тестовый платёж');
    // Описание платежа. Необязательный параметр
```
Все параметры в данном примере, за исключением описания платежа, являются необходимыми для любой оплаты. Также могут потребоваться и другие параметры, например адрес электронной почты пользователя или его номер телефона для выполнения аутентификации 3‑D Secure. Их необходимо указывать следующим образом.
```
$payment->setCustomerPhone('The customer phone number. Must have from 4 to 24 digits');
$payment->setCustomerEmail('The customer email');
```
Кроме того, для оплат с использованием платёжных карт рекомендуется передавать сведения о платёжном адресе пользователя: код страны в формате ISO 3166-1 alpha-2 (подробнее), индекс, названия города и улицы. Эти сведения указываются следующим образом.
```
$payment->setBillingPostal('The postal code of the customer billing address');
$payment->setBillingCountry('The country of the customer billing address, in ISO 3166-1 alpha-2');
$payment->setBillingCity('The city of the customer billing address');
$payment->setBillingAddress('The street of the customer billing address');
```
Дополнительно можно использовать любые другие параметры из числа доступных для работы с Payment Page. Подробнее о доступных параметрах — в разделе Параметры вызова платёжной формы.
Создать объект класса Gate и указать значение секретного ключа, полученное от ecommpay. Секретный ключ необходим для автоматического подписывания параметров.
```
$gate = new ecommpay\Gate('<secret_key>');
    // Секретный ключ проекта, полученный при интеграции от ecommpay
```
Сформировать запрос для вызова платёжной формы.
```
$url = $gate->getPurchasePaymentPageUrl($payment);
```
Корректный запрос для вызова платёжной формы содержит подпись и параметры платежа:
```
https://paymentpage.ecommpay.com/payment?signature=OEKRlLXKStyoH%2BM36hokU
zLZsuB2gO8JALVnyevcV59akRi29elbheVscAEl0ljcoQVXDE390MwgWg%3D%3D&payment_id=TEST_1555943554067...
```
Использовать сформированный запрос для вызова платёжной формы, например следующим образом:
```
<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

$gate = new ecommpay\Gate('<secret_key>');
    // Секретный ключ проекта, полученный при интеграции
$payment = new ecommpay\Payment('186', '1555943554067');
    // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта
$payment->setPaymentAmount(1000)->setPaymentCurrency('EUR');
    // Сумма (в дробных единицах валюты) и код валюты (в формате ISO-4217 alpha-3)
$payment->setPaymentDescription('Test payment');
    // Описание платежа
$payment->setBestBefore(new \DateTime('2050-01-01 00:00:00 +0000'));
    // Дата и время, до которых платёж должен быть завершён
$payment->setLanguageCode('en');
    // Код языка, на котором Payment Page открывается пользователю
$url = $gate->getPurchasePaymentPageUrl($payment);
    // Готовый запрос с подписью

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

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

Перед началом отладки следует обеспечить возможность отправки HTTP-запросов со стороны серверной части веб-сервиса к ресурсу sdk.ecommpay.com и убедиться в том, что используемый PHP-интерпретатор соответствует хотя бы одному из следующих условий:

поддерживается библиотека curl (подробнее);
поддерживается библиотека sockets c доступом к URL по протоколу HTTP (подробнее);
для директивы allow_fopen_url указано значение true и поддержан доступ к URL по протоколу HTTP (подробнее).

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

$payment = new Payment(<project_id>, '<payment_id_in_your_service>');
$payment->setPaymentAmount(1001)
    ->setPaymentCurrency('EUR')
    ->setPaymentDescription('Тестовый платёж')
$gate = new Gate('<secret_key>');
 
try {
    return $gate->getPaymentPageUrl($payment); 
    // Получение ссылки на открытие платёжной формы
} catch (ValidationException $e) { // Обработка возможных исключений
    error_log($e->getFormattedMessage()); // Запись сообщения об ошибках в журнал
}
 
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-строки, необходимо:

Если ранее, при формировании запроса для вызова Payment Page, не был создан объект класса Gate, создать его и указать значение секретного ключа, полученного от ecommpay.
```
$gate = new ecommpay\Gate('<secret_key>');
```
Создать объект класса Callback, используя JSON-строку с информацией о платеже из оповещения от ecommpay:
```
$callback = $gate->handleCallback($data);
```

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

Callback::getPaymentId();            // Получение идентификатора платежа
Callback::getPaymentStatus();        // Получение текущего статуса платежа
Callback::getPayment();              // Получение всей информации о платеже

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

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

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

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

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