SDK для PHP
SDK для PHP — это набор средств разработки для взаимодействия веб-сервисов, разработанных на PHP, с платёжной платформой ecommpay при проведении оплат через Payment Page. В этом разделе представлена информация о работе с SDK для PHP с примерами кода на языке программирования PHP.
SDK для PHP совместим с PHP версии 7.0 или выше и доступен для загрузки по следующим ссылкам:
Возможности
- подписывать набор параметров платежа и формировать адрес для вызова 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';
Вызов платёжной формы
Запрос для вызова 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->setCustomerId('customer007'); // Идентификатор пользователя $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...
- Использовать сформированный адрес для вызова платёжной формы (подробнее).
Далее приведён пример формирования адреса для вызова платёжной формы 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->setCustomerId('customer007'); // Идентификатор пользователя $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(подробнее); - поддерживается библиотека
socketsc доступом к 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..." // Подпись оповещения
}