SDK для PHP

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

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

Возможности

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

Состав

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

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

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

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

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

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

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

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

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

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

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

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

  1. Создать объект класса Payment и указать значения параметров платежа.
    $payment = new jetpay\Payment('186', '1555943554067');
    // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта
$payment->setPaymentAmount(1000)->setPaymentCurrency('RUB');
    // Сумма (в дробных единицах валюты) и код валюты (в формате ISO-4217 alpha-3)
$payment->setPaymentDescription('Тестовый платеж');
    // Описание платежа. Необязательный параметр

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

  2. Создать объект класса Gate и указать значение секретного ключа, полученное от JetPay. Секретный ключ необходим для автоматического подписывания параметров.
    $gate = new jetpay\Gate('<secret_key>');
    // Секретный ключ проекта, полученный при интеграции от JetPay
  3. Сформировать запрос для вызова платежной формы.
    $url = $gate->getPurchasePaymentPageUrl(<pp_host>, $payment);

    Корректный запрос для вызова платежной формы содержит подпись и параметры платежа:

    https://paymentpage.jetpay.kz/payment?signature=OEKRlLXKStyo
...%3D%3D&payment_id=1555943554067...123
  4. Использовать сформированный запрос для вызова платежной формы.

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

Рис.: Пример формирования запроса на открытие Payment Page

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

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

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

  1. Если ранее, при формировании запроса для вызова Payment Page, не был создан объект класса Gate, создать его и указать значение секретного ключа, полученного от JetPay.
    $gate = new jetpay\Gate('<secret_key>');
  2. Создать объект класса Callback, используя JSON-строку с информацией о платеже из оповещения от JetPay:
    $callback = $gate->handleCallback($data);
  3. Использовать методы, доступные для работы с оповещениями. Можно получить полную информацию о платеже или информацию только об отдельных параметрах платежа:
    Callback::getPaymentId();            // Получение идентификатора платежа
Callback::getPaymentStatus();        // Получение текущего статуса платежа
Callback::getPayment();              // Получение всей информации о платеже

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

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

{
      "project_id": 186,       // Идентификатор проекта
      "payment": {             // Информация о платеже
          "id": "1555943554067",        // Идентификатор платежа
          "type": "purchase",  // Тип платежа
          "status": "success", // Статус платежа
          "date": "2018-08-28T09:11:28+0000",  // Дата и время проведения платежа
          "method": "card", 
          "sum": {           // Сумма и валюта платежа
            "amount": 1000,
            "currency": "RUB"
          },
          "description": "Тестовый платеж"  // Описание платежа
      },
      "account": {           // Информация о платежном средстве
          "number": "431422******0056",
          "token": "9cb38282187b7a5b5b91b5814c6b814162741b29c0c486fbbc500cd451abb8b2",
          "type": "visa",
          "card_holder": "ADA LOVELACE",
          "id": 778804,
          "expiry_month": "11",
          "expiry_year": "2022"
      },
      "operation": {     // Информация о последней операции в рамках платежа
        "id": 17839000001150,  // Идентификатор операции
        "type": "sale",        // Тип операции
        "status": "success",   // Статус операции
        "date": "2018-08-28T09:11:28+0000", // Дата и время проведения операции
        "created_date": "2018-08-28T09:10:50+0000",
        "request_id": "2c8af331519833f2c96c4a1aaf60edfcffb...", // Идентификатор запроса
        "sum_initial": {    // Сумма и валюта операции, указанные в запросе
          "amount": 1000,
          "currency": "RUB"
        },
        "sum_converted": {
          // Сумма и валюта операции с учетом настроенных для проекта правил конвертации
            "amount": 1000,
            "currency": "RUB"
        },
        "provider": {     // Информация о проведении платежа в платежной системе
          "id": 6,
          "payment_id": "15354474886323",
          "date": "2018-02-07T08:34:24+0000",
          "auth_code": "563253",
          "endpoint_id": 6
        },
        "code": "0",          // Унифицированный код ответа
        "message": "Success", // Расшифровка кода ответа
        "eci": "05"           // Код индикатора ECI, отображающий результат 3D-Secure проверки  
      },
      "signature": "22YlUIIgoppli/JX8w5F5+c2h12RXi81WLmgDx..."   // Подпись оповещения
  }

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

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