Разработка плагина оплаты

Содержание...

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

Во фреймворке Webasyst основа для разработки плагинов оплаты поддерживается на уровне ядра. Фреймворк предоставляет набор методов и определенный формат получения плагинов данных о заказе и обработки обратных запросов со стороны серверов платежных систем. Плагины оплаты реализованы на уровне ядра фреймворка, а не конкретного приложения. Это позволяет использовать функциональность плагинов любым установленным приложениям (например, Shop-Script 5).

В качестве примера посмотрите исходный код плагина оплаты WebMoney (GitHub-репозиторий).

Исходный код плагинов оплаты находится в директории wa-plugins/payment/. Каждый плагин представляет собой отдельную поддиректорию с реализацией класса, унаследованного от базового класса waPayment и реализующего интерфейсы waIPayment, waIPaymentCapture, waIPaymentRefund, waIPaymentCancel, представляющие собой шаблоны публичных методов payment(), capture(), cancel() и refund() ­для обработки соответствующих типов платежных транзакций (если поддерживаются соответствующей платежной системой; в противном случае они должны возвращать код ошибки).

Наименование поддиректории с файлами плагина является его уникальным идентификатором, который используется в формировании правильного имени класса плагина. Ниже приведен пример таких наименований для некоторого плагина с идентификатором YourPayment:

wa-plugins/payment/yourpayment/lib/yourpaymentPayment.class.php

<?php

class yourpaymentPayment extends waPayment
{

...

}

Помимо основного класса, производного от waPayment, для работы плагина также требуются конфигурационные файлы, которые, как в приложениях и плагинах, размещаются в поддиректории lib/config/ (см. ниже описание конфигурационных файлов плагина оплаты).

В целом процесс разработки плагина оплаты сходен с написанием плагина для приложения, но, в отличие от написания плагина приложения, в случае с плагином оплаты часто достаточно реализовать лишь один или несколько основных методов единственного класса.

Методы

В методах основного класса плагина для получения значений полей настроек плагина, описанных в конфигурационном файле lib/config/settings.php, используйте доступ к приватным полям вида $this->field_name. Вместо field_name указывайте идентификатор поля настроек, значение которого необходимо получить.


payment()

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

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

callbackInit()

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

protected function callbackInit($request)
{
    $this->order_id = null; //заменить на логику извлечения номера заказа из параметров запроса
    $this->app_id = null; //аналогично — для получения идентификатора приложения из параметров запроса
    $this->merchant_id = null;//аналогично — для получения идентификатора экземпляра настроек плагина оплаты
    
    return parent::callbackInit($request); //обязательный вызов метода базового класса
}

callbackHandler()

В этом методе описывается алгоритм обработки обратных запросов, полученных от платежной системы. Такие запросы должны направляться по URL вида http://yourdomain.ru/payments.php/[plugin_id]/. Для передачи плагину оплаты дополнительных параметров от платежной системы допускается использование параметров адресной строки, обычно доступных в виде элементов массива $_GET. Устоявшейся практикой является использование переменной transaction_result со следующими значениями:

Пример URL, по которому должен выполняться обратный вызов платежной системой: http://yourdomain.ru/payments.php/[plugin_id]/?transaction_result=result

Основное назначение метода — вызвать обработчик приложения для обработки транзакции:

$this->execAppCallback($state, $transaction_data)

В качестве $state нужно указать статус транзакции с помощью одной из констант системного класса waPayment: CALLBACK_PAYMENT, CALLBACK_REFUND, CALLBACK_CONFIRMATION, CALLBACK_CAPTURE, CALLBACK_DECLINE, CALLBACK_CANCEL, CALLBACK_CHARGEBACK, например:

$result = $this->execAppCallback(self::CALLBACK_PAYMENT, $transaction_data);

Вызов обработчика приложения следует выполнять только после выполнения проверки корректности/валидности полученных данных с использованием контрольной суммы, подписи и т. п. Использование непроверенных данных может привести к нарушению целостности данных о платежах клиентов!

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

formalizeData()

Метод formalizeData() полезно использовать для приведения содержимого запроса, полученного от платежной системы, в формат, пригодный для хранения в базе данных интернет-магазина.

Конфигурационные файлы

plugin.php

Файл plugin.php является главным конфигурационным файлом плагина оплаты и предназначен для хранения базовой информации о плагине: названия, описания, версии и т. д. Формат файла:

<?php
    
return array(
    'name'        => ...,
    'description' => ...,
    'icon'        => ...,
    'logo'        => ...,
    'vendor'      => ...,
    'version'     => ...,
    'type'        => ...,
);

Описания полей

settings.php

Файл settings.php используется для автоматического формирования интерфейса настроек плагина оплаты в бекенде приложения, которое использует такой плагин. См. подробное описание файла настроек плагина.

requirements.php

Файл requirements.php используется для указания дополнительных системных требований, специфичных для работы конкретного плагина (например, наличие дополнительных расширений или отдельных параметров конфигурации PHP, установленных приложений Webasyst). См. подробное описание правил оформления системных требований продукта.

guide.php

Файл guide.php используется для того, чтобы предоставить пользователю в интерфейсе настроек плагина возможность скопировать некоторые параметры, чтобы сохранить их в настройках аккаунта продавца на сайте платежной системы, например: URL для обновления статусов заказов, идентификатор экземпляра настроек плагина, название используемой кодировки символов или метода отправки данных.

Файл guide.php должен представлять собой PHP-файл с массивом параметров для каждого такого поля в настройках плагина оплаты, как показано в примере:

<?php
    
return array(
    array(
        'title'       => '',
        'description' => '',
        'value'       => '',
    ),
    array(
        'title'       => '',
        'description' => '',
        'value'       => '',
    ),
    ...
);

Каждый подмассив соответствует одному из полей. Его элементы имеют следующие значения:

Пример файла guide.php:

<?php
    
return array(
    array(
        'title'       => 'URL для уведомления об успешной оплате',
        'description' => '',
        'value'       => '%HTTPS_RELAY_URL%',
    ),
    array(
        'title'       => 'URL для уведомления об отклоненных транзакциях',
        'description' => '',
        'value'       => '%HTTPS_RELAY_URL%?transaction_result=failure',
    ),
    array(
        'title'       => 'Кодировка, используемая при отправке данных',
        'description' => 'Укажите при настройке нового протокола подключения к платежной системе',
        'value'       => 'UTF-8',
    ),
);

Советы

Различные полезные URL для настройки интеграции между вашим сайтом и платежной системой, можно получить в PHP-коде плагина следующим образом:

Значения переменных, используемых в файле guide.php:

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

$this->getAdapter()->getBackUrl($type, $data);

В качестве $type укажите тип действия в виде одной из констант системного класса waAppPayment: URL_SUCCESS (успешная оплата), URL_DECLINE (отмена платежа), URL_FAIL (неудачная попытка оплаты), URL_CHECKOUT (возврат на страницу оформления заказа), URL_PRINTFORM (отображение печатной формы). В качестве $data нужно передать массив с данными транзакции. Пример:

$return_url = $this->getAdapter()->getBackUrl(waAppPayment::URL_SUCCESS, $transaction_data);
В приложении, использующем плагин оплаты, должна иметься поддержка типа URL возврата покупателя, указанного вами при вызове метода getBackUrl().