# SDK для PHP {#ru_sdk_php} статья о порядке применения SDK для создания и проверки подписи к данным в рамках веб-сервисов, разработанных на языке PHP SDK для PHP — это набор средств разработки для взаимодействия веб-сервисов, разработанных на PHP, с платёжной платформой Ecommpay при проведении оплат через Payment Page. В этом разделе представлена информация о работе с SDK для PHP с примерами кода на языке программирования PHP. SDK для PHP совместим с PHP версии 7.0 или выше и доступен для загрузкипо следующим ссылкам: - GitHub: [https://github.com/ITECOMMPAY/paymentpage-sdk-php](https://github.com/ITECOMMPAY/paymentpage-sdk-php) - Packagist: [https://packagist.org/packages/ecommpay/paymentpage-sdk](https://packagist.org/packages/ecommpay/paymentpage-sdk) ## Возможности {#section_mdv_1pf_nhb .section} SDK для PHP позволяет: - подписывать набор параметров платежа и формировать адрес для вызова Payment Page, - проверять подлинность оповещений от Ecommpay и получать из них информацию о платеже. ## Состав {#section_rlb_55f_nhb .section} SDK для PHP содержит библиотеки и служебные файлы. Для работы могут использоваться: - **src** — библиотеки для разработки, - **tests** — библиотеки для автоматизированного тестирования, - **composer.json** — файл, в котором описаны библиотеки. ## Порядок работы {#section_ow5_sdb_mhb .section} Для использования SDK для PHP необходимо: 1. Решить организационные вопросы, касающиеся взаимодействия с Ecommpay: - Если у компании нет идентификатора проекта и ключа для взаимодействия с Ecommpay — отправить заявку на подключениепо ссылке [https://ecommpay.com/apply-now/](https://ecommpay.com/apply-now/). - Если у компании есть идентификатор и ключ для взаимодействия с Ecommpay — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK для PHP и согласовать с ними порядок тестирования. 2. Установить библиотеки, входящие в состав SDK для PHP, в каталог с исходным кодом веб-сервиса и подключить их в коде, а также доработать код для использования необходимой функциональности. 3. Протестировать и запустить в работу обновлённый исходный код веб-сервиса. - Для тестирования следует использовать тестовый идентификатор проекта, тестовые значения параметров платежа и пример оповещения из библиотеки **tests**. - Для перевода в рабочий режим необходимо заменить тестовое значение project\_id на рабочее, полученное от Ecommpay. При возникновении вопросов о работе с SDK для PHP следует обращаться в службу технической поддержки Ecommpay по адресу [support@ecommpay.com](mailto:support@ecommpay.com). ## Установка и подключение библиотек {#section_y13_j32_nhb .section} Устанавливать библиотеки, входящие в состав SDK для PHP, в проект с исходным кодом веб-сервиса можно вручную или автоматически с помощью менеджера зависимостей. Менеджер зависимостей Composer обеспечивает загрузку необходимых библиотек из репозитория [Packagist](https://packagist.org/packages/ecommpay/paymentpage-sdk) и формирование скрипта для подключения загруженных библиотек. Чтобы установить библиотеки с помощью Composer и подключить их в исходном коде веб-сервиса, необходимо: 1. Если не установлен Composer — загрузить, установить и настроить \(подробнее [https://getcomposer.org/](https://getcomposer.org/)\). 2. В командной строке операционной системы перейти в каталог с исходным кодом веб-сервиса и выполнить следующую команду: ```language-php composer require ecommpay/paymentpage-sdk ``` Эта команда служит для размещения загруженных библиотек в каталоге **vendor** и создания скрипта **autoload.php** для одновременного подключения всех библиотек в исходном коде веб-сервиса. 3. Подключить скрипт **autoload.php** в исходном коде веб-сервиса: ```php require` __DIR__.'../../vendor.autoload.php'; ``` ## Вызов платёжной формы {#section_bty_ryn_lhb .section} Запрос для вызова Payment Page включает в себя набор параметров, подписываемых для обеспечения защиты данных при передаче запроса в платёжную платформу Ecommpay. SDK для PHP позволяет автоматически подписывать используемые параметры. Для вызова Payment Page с применением SDK для PHP следует: 1. Создать объект класса `Payment` и указать значения параметров платежа. ```language-php $payment = new ecommpay\Payment('186', '1555943554067'); // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта $payment->setPaymentAmount(1000)->setPaymentCurrency('EUR'); // Сумма (в дробных единицах валюты) и код валюты (в формате ISO-4217 alpha-3) $payment->setCustomerId('customer007'); // Идентификатор пользователя $payment->setPaymentDescription('Тестовый платёж'); // Описание платежа. Необязательный параметр ``` Все параметры в данном примере, за исключением описания платежа, являются необходимыми для любой оплаты.Также могут потребоваться и другие параметры, например адрес электронной почты пользователя или его номер телефона для выполнения аутентификации 3‑D Secure. Их необходимо указывать следующим образом. ```language-php $payment->setCustomerPhone('The customer phone number. Must have from 4 to 24 digits'); $payment->setCustomerEmail('The customer email'); ``` Кроме того, для оплат с использованием платёжных карт рекомендуется передавать сведения о платёжном адресе пользователя: код страны в формате ISO 3166-1 alpha-2 \([подробнее](ru_country_codes.md)\), индекс, названия города и улицы. Эти сведения указываются следующим образом. ```language-php $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. Подробнее о доступных параметрах — в разделе [Спецификация Payment Page API](ru_PP_Parameters.md). 2. Создать объект класса `Gate` и указать значение секретного ключа, полученное от Ecommpay. Секретный ключ необходим для автоматического подписывания параметров. ```language-php $gate = new ecommpay\Gate('<*secret\_key*>'); // Секретный ключ проекта, полученный при интеграции от Ecommpay ``` 3. Сформировать адрес для вызова платёжной формы. ```language-php $url = $gate->getPurchasePaymentPageUrl($payment); ``` Корректный адрес для вызова платёжной формы содержит подпись и параметры платежа: ```language-php https://paymentpage.ecommpay.com/payment?signature=OEKRlLXKStyoH%2BM36hokU zLZsuB2gO8JALVnyevcV59akRi29elbheVscAEl0ljcoQVXDE390MwgWg%3D%3D&payment_id=TEST_1555943554067... ``` 4. Использовать сформированный адрес для вызова платёжной формы \([подробнее](ru_PP_Integration.md)\). Далее приведён пример формирования адреса для вызова платёжной формы Payment Page с открытием на английском языке.На странице с выбором платёжных методов обеспечивается отображение информации о платеже: идентификатора, валюты, суммы и описания платежа. На странице с вводом реквизитов, необходимых для проведения платежа, обеспечивается отображение таймера с обратным отсчётом времени. ```language-php $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); // Готовый запрос с подписью ``` ## Использование режима отладки {#section_l2r_2l1_g5b .section} При работе с SDK для PHP поддерживается режим отладки, который позволяет проверять полноту и корректность указанных параметров и получать информацию о допущенных ошибках. Перед началом отладки следует обеспечить возможность отправки HTTP-запросов со стороны серверной части веб-сервиса к ресурсу `sdk.ecommpay.com` и убедиться в том, что используемый PHP-интерпретатор соответствует хотя бы одному из следующих условий: - поддерживается библиотека `curl` \([подробнее](https://www.php.net/manual/ru/book.curl.php)\); - поддерживается библиотека `sockets` c доступом к URL по протоколу HTTP \([подробнее](https://www.php.net/manual/ru/book.sockets.php)\); - для директивы `allow_fopen_url` указано значение `true` и поддержан доступ к URL по протоколу HTTP \([подробнее](https://www.php.net/manual/ru/function.fopen)\). После этого в рамках отладки можно задавать различные параметры вызова платёжной формы \(как тестовые, так и реальные\) и анализировать информацию об ошибках. Для этого используется код следующего вида: ```language-php $payment = new Payment(, ''); $payment->setPaymentAmount(1001) ->setPaymentCurrency('EUR') ->setPaymentDescription('Тестовый платёж') $gate = new Gate(''); try { return $gate->getPaymentPageUrl($payment); // Получение ссылки на открытие платёжной формы } catch (ValidationException $e) { // Обработка возможных исключений error_log($e->getFormattedMessage()); // Запись сообщения об ошибках в журнал } return null; ``` Информация о найденных ошибках, полученная в результате выполнения этих действий, в текстовом формате может выглядеть следующим образом: ```language-php One or more parameters is not valid: Customer_id: Must be not null // Не указан идентификатор пользователя, обязательный для запроса Account_token: Invalid account token // Указан некорректный токен ``` При отсутствии ошибок можно считать полученную ссылку на открытие Payment Page корректной. ## Обработка оповещений {#section_qxm_m24_lhb .section} Информацию о результатах проведения платежей можно получать в оповещениях, отправляемых со стороны Ecommpay на URL, который необходимо сообщить службе технической поддержки Ecommpay. Оповещение представляет собой **HTTP** **POST** запрос с данными в формате **JSON**-строки. Чтобы извлечь информацию о результате проведения платежа из **JSON**-строки, необходимо: 1. Если ранее, при формировании запроса для вызова Payment Page, не был создан объект класса `Gate`, создать его и указать значение секретного ключа, полученного от Ecommpay. ```language-php $gate = new ecommpay\Gate('<*secret\_key*>'); ``` 2. Создать объект класса `Callback`, используя **JSON**-строку с информацией о платеже из оповещения от Ecommpay: ```language-php $callback = $gate->handleCallback($data); ``` 3. Использовать методы, доступные для работы с оповещениями. Можно получить полную информацию о платеже или информацию только об отдельных параметрах платежа: ```language-php 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..." // Подпись оповещения } ``` ## Дополнительные материалы {#section_jzk_ph2_plb .section} Для организации работы с оповещениями также могут быть полезны следующие материалы: - [Работа с оповещениями](ru_platform_callbacks.md) - [Проведение платежей](ru_platform_payment_model.md) **На уровень выше:**[Интеграция с использованием SDK](ru_sdk_overview.md)