payneteasy-payneteasyapi 0.1.0

data/doc/library-internals/01-payment-processor.md

@@ -0,0 +1,163 @@
+# Фронтенд библиотеки, PaymentProcessor
+
+Фронтенд библиотеки представляет класс **[PaynetEasy\PaynetEasyApi\PaymentProcessor](../../source/PaynetEasy/PaynetEasyApi/PaymentProcessor.php)**. Класс предоставляет следующие возможности:
+* **[executeQuery()](#executeQuery)**: простое выполнение запроса к PaynetEasy
+* **[processCustomerReturn()](#processCustomerReturn)**: простая обработка данных, полученных от PaynetEasy при возвращении пользователя с платежного шлюза
+* **[processPaynetEasyCallback()](#processPaynetEasyCallback)**: простая обработка данных, полученных от PaynetEasy при поступлении коллбэка от PaynetEasy
+* **[setHandlers()](#setHandlers)**: установка обработчиков для различных событий, происходящих при обработке платежной транзакции
+
+### <a name="executeQuery"></a>executeQuery(): простое выполнение запроса к PaynetEasy
+
+Некоторые сценарии обработки платежа имеют асинхронную природу и состоят из нескольких запросов. Так, некоторые запросы не возвращают результат платежа сразу и требуют многократного выполнения запроса **status**, после которого клиент может быть отправлен на шлюз PaynetEasy для проведения дополнительных шагов авторизации. После возвращения клиента на сервис мерчанта необходима обработка данных, полученных от шлюза.
+<a name="async_queries_list"></a>Cписок асинхронных запросов:
+* sale
+* preauth
+* capture
+* return
+* make-rebill
+* transfer-by-ref
+
+Ознакомиться с обработкой таких запросов можно в следующих файлах:
+* [Пример выполнения запроса sale](../../example/sale.php)
+* [Пример выполнения запроса preauth](../../example/preauth.php)
+* [Пример выполнения запроса capture](../../example/capture.php)
+* [Пример выполнения запроса return](../../example/return.php)
+* [Пример выполнения запроса make-rebill](../../example/make-rebill.php)
+* [Пример выполнения запроса transfer-by-ref](../../example/transfer-by-ref.php)
+
+Отдельный сценарий обработки необходим и при интеграции платежной формы. Запрос к шлюзу возвращает ссылку на платежную форму, на которую должен быть отправлен клиент. После заполнения и отправки данных шлюз обрабатывает платежную форму и возвращает клиента на сервис мерчанта. После возвращения клиента на сервис мерчанта необходима обработка данных, полученных от шлюза.
+<a name="form_queries_list"></a>Список запросов для интеграции платежной формы:
+* sale-form
+* preauth-form
+* transfer-form
+
+Ознакомиться с обработкой таких запросов можно в следующих файлах:
+* [Пример выполнения запроса sale-form](../../example/sale-form.php)
+* [Пример выполнения запроса preauth-form](../../example/preauth-form.php)
+* [Пример выполнения запроса transfer-form](../../example/transfer-form.php)
+
+Некоторые операции с платежами не требуют сложных сценариев обработки и выполняются с помощью одного запроса.
+Список простых операций над платежом:
+* create-card-ref
+* get-card-info
+* status
+
+Ознакомиться с обработкой таких запросов можно в следующих файлах:
+* [Пример выполнения запроса create-card-ref](../../example/create-card-ref.php)
+* [Пример выполнения запроса get-card-info](../../example/get-card-info.php)
+* [Пример выполнения запроса status](../../example/status.php)
+
+Для удобного выполнения запросов к PaynetEasy в **PaymentProcessor** реализован метод **[executeQuery()](../../source/PaynetEasy/PaynetEasyApi/PaymentProcessor.php#L114)**.
+Метод принимает два параметра:
+* Название запроса
+* Платежная транзакция для обработки
+
+### <a name="processCustomerReturn"></a>processCustomerReturn(): простая обработка данных, полученных от PaynetEasy
+
+Каждый [асинхронный запрос](#async_queries_list) может завершиться перенаправлением пользователя на платежный шлюз для выполнения дополнительных действий, а каждый [запрос для интеграции платежной формы](#form_queries_list) обязательно содержит такое перенаправление. Каждый раз при возвращении пользователя на сервис мерчанта передаются данные с результатом обработки платежа. Также, если в [конфигурации стартового запроса](../00-basic-tutorial.md#stage_1_step_3) был задан ключ **server_callback_url**, то через некоторое время PaynetEasy вызовет этот url и передаст ему данные, описанные в wiki PaynetEasy в разделе [Merchant Callbacks](http://wiki.payneteasy.com/index.php/PnE:Merchant_Callbacks). Для удобной обработки этих данных в **PaymentProcessor** реализован метод **[executeCallback()](../../source/PaynetEasy/PaynetEasyApi/PaymentProcessor.php#L161)**.
+Метод принимает два параметра:
+* Объект с данными, полученными при возвращении пользователя от PaynetEasy
+* Платежная транзакция для обработки
+
+Ознакомиться с использованием данного метода можно в следующих файлах:
+* [Базовый пример использования библиотеки](../00-basic-tutorial.md#stage_2)
+* [Пример выполнения запроса sale](../../example/sale.php#L91)
+* [Пример выполнения запроса preauth](../../example/preauth.php#L91)
+* [Пример выполнения запроса sale-form](../../example/sale-form.php#L70)
+* [Пример выполнения запроса preauth-form](../../example/preauth-form.php#70)
+* [Пример выполнения запроса transfer-form](../../example/transfer-form.php#70)
+
+### <a name="processPaynetEasyCallback"></a>processPaynetEasyCallback(): простая обработка данных, полученных от PaynetEasy
+
+После выполнения [асинхронного запроса](#async_queries_list) или [запроса для интеграции платежной формы](#form_queries_list), если в [конфигурации стартового запроса](../00-basic-tutorial.md#stage_1_step_3) был задан ключ **server_callback_url**, то через некоторое время PaynetEasy вызовет этот url и передаст ему данные, описанные в wiki PaynetEasy в разделе [Merchant Callbacks](http://wiki.payneteasy.com/index.php/PnE:Merchant_Callbacks). Для удобной обработки этих данных в **PaymentProcessor** реализован метод **[processPaynetEasyCallback()](../../source/PaynetEasy/PaynetEasyApi/PaymentProcessor.php#L176)**.
+Метод принимает два параметра:
+* Объект с данными, полученными при возвращении пользователя от PaynetEasy
+* Платежная транзакция для обработки
+
+Ознакомиться с использованием данного метода можно в следующих файлах:
+* [Пример выполнения запроса sale](../../example/sale.php#L102)
+* [Пример выполнения запроса preauth](../../example/preauth.php#L102)
+* [Пример выполнения запроса sale-form](../../example/sale-form.php#L81)
+* [Пример выполнения запроса preauth-form](../../example/preauth-form.php#81)
+* [Пример выполнения запроса transfer-form](../../example/transfer-form.php#81)
+
+### <a name="setHandlers"></a> setHandlers(): установка обработчиков для различных событий, происходящих при обработке заказа
+
+**PaymentProcessor** скрывает от конечного пользователя алгоритм обработки заказа в методах **[executeWorkflow()](#executeWorkflow)**, **[executeQuery()](#executeQuery)** и **[executeCallback()](#executeCallback)**. При этом во время обработки заказа возникают ситуации, обработка которых должна быть реализована на стороне сервиса мерчанта. Для обработки таких ситуаций в **PaymentProcessor** реализована система событий и их обработчиков. Обработчики могут быть установлены тремя разными способами:
+* Передача массива обработчиков в [конструктор класса **PaymentProcessor**](../../source/PaynetEasy/PaynetEasyApi/PaymentProcessor.php#L101)
+* Передача массива обработчиков в метод [**setHandlers()**](../../source/PaynetEasy/PaynetEasyApi/PaymentProcessor.php#L273)
+* Установка обработчиков по одному с помощью метода **[setHandler()](../../source/PaynetEasy/PaynetEasyApi/PaymentProcessor.php#L249)**
+
+Список обработчиков событий:
+* **HANDLER_SAVE_CHANGES** - обработчик для сохранения платежной транзакции. Вызывается, если данные платежной транзакции изменены. Должен реализовывать сохранение платежной транзакции в хранилище. Принимает следующие параметры:
+    * Платежная транзакция
+    * Ответ от PaynetEasy (опционально, не доступен, если произошла ошибка на этапе формирования или выполнения запроса к PaynetEasy)
+* **HANDLER_STATUS_UPDATE** - обработчик для обновления статуса платежной транзакции. Вызывается, если статус платежной транзакции не изменился с момента последней проверки. Должен реализовывать запуск проверки статуса платежной транзакции. Принимает следующие параметры:
+    * Ответ от PaynetEasy
+    * Платежная транзакция
+* **HANDLER_SHOW_HTML** - обработчик для вывода HTML-кода, полученного от PaynetEasy. Вызывается, если необходима 3D-авторизация пользователя. Должен реализовывать вывод HTML-кода из ответа от PaynetEasy в браузер клиента. Принимает следующие параметры:
+    * Ответ от PaynetEasy
+    * Платежная транзакция
+* **HANDLER_REDIRECT** - обработчик для перенаправления клиента на платежную форму PaynetEasy. Вызывается после выполнения запроса [sale-form, preauth-form или transfer-form](../payment-scenarios/05-payment-form-integration.md). Должен реализовывать перенаправление пользователя на URL из ответа от PaynetEasy. Принимает следующие параметры:
+    * Ответ от PaynetEasy
+    * Платежная транзакция
+* **HANDLER_FINISH_PROCESSING** - обработчик для дальнейшей обработки платежной транзакции сервисом мерчанта после завершения обработки библиотекой. Вызывается, если нет необходимости в дополнительных шагах для обработки транзакции. Принимает следующие параметры:
+    * Платежная транзакция
+    * Ответ от PaynetEasy (опционально, не доступен, если обработка платежной транзакции уже была завершена ранее)
+* **HANDLER_CATCH_EXCEPTION** - обработчик для исключения. Вызывается, если при обработке платежной транзакции произошло исключение. **Внимание!** Если этот обработчик не установлен, то исключение будет брошено из библиотеки выше в сервис мерчанта. Принимает следующие параметры:
+    * Исключение
+    * Платежная транзакция
+    * Ответ от PaynetEasy (опционально, не доступен, если произошла ошибка на этапе формирования или выполнения запроса к PaynetEasy)
+
+Метод принимает один параметр:
+* Массив с обработчиками событий. Ключами элементов массива являются названия обработчиков, заданные в константах класса, значениями - любые значения типа [callable](http://php.net/manual/en/language.types.callable.php)
+
+Пример вызова метода с простейшими обработчиками:
+
+```php
+use PaynetEasy\PaynetEasyApi\PaymentProcessor;
+use PaynetEasy\PaynetEasyApi\PaymentData\PaymentTransaction;
+use PaynetEasy\PaynetEasyApi\Transport\Response;
+use Exception;
+
+$paymentProcessor = new PaymentProcessor;
+$paymentProcessor->setHandlers(array
+(
+    PaymentProcessor::HANDLER_SAVE_CHANGES      => function(PaymentTransaction $paymentTransaction)
+    {
+        start_session();
+        $_SESSION['payment_transaction'] = serialize($paymentTransaction);
+    },
+    PaymentProcessor::HANDLER_STATUS_UPDATE     => function()
+    {
+        header("Location: http://{$_SERVER['HTTP_HOST']}/{$_SERVER['REQUEST_URI']}?stage=updateStatus");
+        exit;
+    },
+    PaymentProcessor::HANDLER_SHOW_HTML         => function(Response $response)
+    {
+        print $response->getHtml();
+        exit;
+    },
+    PaymentProcessor::HANDLER_REDIRECT          => function(Response $response)
+    {
+        header("Location: {$response->getRedirectUrl()}");
+        exit;
+    },
+    PaymentProcessor::HANDLER_FINISH_PROCESSING => function(PaymentTransaction $paymentTransaction)
+    {
+        print "<pre>";
+        print "Payment processing finished.\n";
+        print "Payment status: '{$paymentTransaction->getPayment()->getStatus()}'.\n";
+        print "Payment transaction status: '{$paymentTransaction->getStatus()}'.\n";
+        print "</pre>";
+    },
+    PaymentProcessor::HANDLER_CATCH_EXCEPTION   => function(Exception $exception)
+    {
+        print "<pre>";
+        print "Exception catched.\n";
+        print "Exception message: '{$exception->getMessage()}'.\n";
+        print "Exception traceback: \n{$exception->getTraceAsString()}\n";
+        print "</pre>";
+    }
+));
+```

data/doc/library-internals/02-validator.md

@@ -0,0 +1,55 @@
+# Валидатор данных, Validator
+
+Статический класс **[PaynetEasy\PaynetEasyApi\Util\Validator](../../source/PaynetEasy/PaynetEasyApi/Util/Validator.php)** предоставляет следующие методы для валидации данных:
+* **[validateByRule()](#validateByRule)**: валидация с помощью предопределенного правила или регулярного выражения
+
+### <a name="validateByRule"></a>validateByRule(): валидация с помощью предопределнного правила
+
+Для удобной валидации данных в **[Validator](../../source/PaynetEasy/PaynetEasyApi/Util/Validator.php)** реализован метод **[validateByRule()](../../source/PaynetEasy/PaynetEasyApi/Util/Validator.php#L126)** и набор констант с правилами валидации. Список доступных правил:
+
+Константа                       |Правило валидации          |Описание
+--------------------------------|---------------------------|--------
+Validator::EMAIL                |[FILTER_VALIDATE_EMAIL](http://www.php.net/manual/en/filter.filters.validate.php)|Validate value as email
+Validator::IP                   |[FILTER_VALIDATE_IP](http://www.php.net/manual/en/filter.filters.validate.php)|Validate value as IP address
+Validator::URL                  |[FILTER_VALIDATE_URL](http://www.php.net/manual/en/filter.filters.validate.php)|Validate value as URL
+Validator::MONTH                |0 < month < 13             |Validate value as month
+Validator::YEAR                 |#^[0-9]{1,2}$#i            |Validate value as year
+Validator::PHONE                |#^[0-9\-\+\(\)\s]{6,15}$#i |Validate value as phone number
+Validator::AMOUNT               |#^[0-9\.]{1,11}$#i         |Validate value as payment amount
+Validator::CURRENCY             |#^[A-Z]{1,3}$#i            |Validate value as currency
+Validator::CVV2                 |#^[\S\s]{3,4}$#i           |Validate value as card verification value
+Validator::ZIP_CODE             |#^[\S\s]{1,10}$#i          |Validate value as zip code
+Validator::COUNTRY              |#^[A-Z]{1,2}$#i            |Validate value as two-letter country or state code
+Validator::DATE                 |#^[0-9]{6}$#i              |Validate value as date in format MMDDYY
+Validator::SSN                  |#^[0-9]{1,4}$#i            |Validate value as last four digits of social security number
+Validator::CREDIT_CARD_NUMBER   |#^[0-9]{1,20}$#i           |Validate value as credit card number
+Validator::ID                   |#^[\S\s]{1,20}$#i          |Validate value as ID (client, paynet, card-ref, etc.)
+Validator::LONG_STRING          |#^[\S\s]{1,128}$#i         |Validate value as long string
+Validator::MEDIUM_STRING        |#^[\S\s]{1,50}$#i          |Validate value as medium string
+
+Метод принимает три параметра:
+* Значение для валидации
+* Имя правила или регулярное выражение для валидации
+* Флаг, определяющий поведение метода в том случае, если значение не прошло валидацию
+    * **true** - будет брошено исключение
+    * **false** - будет возвращен булевый результат проверки
+Пример использования метода:
+
+```php
+use PaynetEasy\PaynetEasyApi\Util\Validator;
+use PaynetEasy\PaynetEasyApi\Exception\ValidationException;
+
+var_dump(Validator::validateByRule('test@mail.com', Validator::EMAIL, false));  // true
+var_dump(Validator::validateByRule('some string', '#\d#', false));              // false
+
+// prints 'invalid'
+try
+{
+    Validator::validateByRule('test[at]mail.com', Validator::EMAIL);
+    print 'valid';
+}
+catch (ValidationException $e)
+{
+    print 'invalid';
+}
+```

data/doc/library-internals/03-property-accessor.md

@@ -0,0 +1,76 @@
+# Класс для работы с цепочками свойств, PropertyAccessor
+
+В процессе работы с данными платежа возникает необходимость читать и изменять свойства объектов, хранящихся в Payment. Например, для чтения email клиента необходимо вызвать `$payment->getCustomer()->getEmail()`, а для записи - `$payment->getCustomer()->setEmail()`. Для удобного выполнения этих операций в классе **[PaynetEasy\PaynetEasyApi\Util\PropertyAccessor](../../source/PaynetEasy/PaynetEasyApi/Util/PropertyAccessor.php)** реализованы следующие методы:
+* **[getValue()](#getValue)**: удобное чтение данных по цепочке свойств
+* **[setValue()](#setValue)**: удобная запись данных по цепочке свойств
+
+### <a name="getValue"></a> getValue(): удобное чтение данных по цепочке свойств
+
+Метод предназначен для чтения данных из цепочки свойств. Цепочка свойств описывает порядок получения свойств из переданного объекта. Так, для цепочки `billingAddress.firstLine` будет получено значение свойства `firstLine` из объекта, хранящегося в свойстве `billingAddress`. Для получения свойств используются методы-геттеры, названия которых образованы добавлением префикса `get` к имени свойства. Таким образом, получение данных для цепочки `billingAddress.firstLine` приведет к вызову кода `$payment->getBillingAddress()->getFirstLine()`.
+Метод принимает три параметра:
+* Объект, цепочку свойств которого можно прочитать
+* Цепочка свойств
+* Флаг, определяющий поведение метода в том случае, если геттер для свойства не был найден или если свойство, в котором ожидался объект, пустое:
+    * **true** - будет брошено исключение
+    * **false** - будет возвращен `null`
+
+Пример использования метода:
+```php
+use PaynetEasy\PaynetEasyApi\Util\PropertyAccessor;
+use PaynetEasy\PaynetEasyApi\PaymentData\Payment;
+use PaynetEasy\PaynetEasyApi\PaymentData\CreditCard;
+use RuntimeException;
+
+$creditCard = (new CreditCard)->setExpireYear(2014);
+$payment    = (new Payment)->setCreditCard($creditCard);
+
+var_dump(PropertyAccessor::getValue($payment, 'creditCard.expireYear')); // 2014
+var_dump(PropertyAccessor::getValue($payment, 'creditCard.expireMonth', false)); // null
+
+// prints 'empty'
+try
+{
+    PropertyAccessor::getValue($payment, 'creditCard.expireMonth');
+}
+catch (RuntimeException $e)
+{
+    print 'empty';
+}
+```
+
+### <a name="setValue"></a> setValue(): удобное изменение данных по цепочке свойств
+
+Метод предназначен для изменения данных по цепочке свойств. Цепочка свойств описывает порядок получения свойств из переданного объекта. Так, для цепочки `billingAddress.firstLine` будет изменено значение свойства `firstLine` из объекта, хранящегося в свойстве `billingAddress`. Для получения свойств используются методы-геттеры, названия которых образованы добавлением префикса `get` к имени свойства, для изменения - методы-сеттеры, названия которых образованы добавлением префикса `set` к имени свойства. Таким образом, изменение данных для цепочки `billingAddress.firstLine` приведет к вызову кода `$payment->getBillingAddress()->setFirstLine($firstLine)`.
+Метод принимает четыре параметра:
+* Объект, цепочку свойств которого можно прочитать
+* Цепочка свойств
+* Новое значение
+* Флаг, определяющий поведение метода в том случае, если геттер или сеттер для свойства не был найден или если свойство, в котором ожидался объект, пустое:
+    * **true** - будет брошено исключение
+    * **false** - будет возвращен `null`
+
+Пример использования метода:
+```php
+use PaynetEasy\PaynetEasyApi\Util\PropertyAccessor;
+use PaynetEasy\PaynetEasyApi\PaymentData\Payment;
+use PaynetEasy\PaynetEasyApi\PaymentData\CreditCard;
+use RuntimeException;
+
+$creditCard = (new CreditCard)->setExpireYear(2014);
+$payment    = (new Payment)->setCreditCard($creditCard);
+
+PropertyAccessor::setValue($payment, 'creditCard.expireYear', 2015);
+var_dump(PropertyAccessor::getValue($payment, 'creditCard.expireYear')); // 2015
+
+PropertyAccessor::setValue($payment, 'creditCard.nonExistentProperty', 'value', false); // nothing will happen
+
+// prints 'nonexistent property'
+try
+{
+    PropertyAccessor::setValue($payment, 'creditCard.nonExistentProperty', 'value');
+}
+catch (RuntimeException $e)
+{
+    print 'nonexistent property';
+}
+```

data/doc/payment-scenarios/00-sale-transactions.md

@@ -0,0 +1,90 @@
+# Sale transactions
+
+Список запросов сценария:
+* [Запрос "sale"](#sale)
+* [Запрос "status"](#status)
+
+## Общие положения
+
+* В данной статье описывается исключительно работа с библиотекой. Полная информация о выполнении Sale transactions расположена в [статье в wiki PaynetEasy](http://wiki.payneteasy.com/index.php/PnE:Sale_Transactions).
+* Описание правил валидации можно найти в описании метода **[Validator::validateByRule()](../library-internals/02-validator.md#validateByRule)**.
+* Описание работы с цепочками свойств можно найти в описании класса **[PropertyAccessor](../library-internals/03-property-accessor.md)**
+
+## <a name="sale"></a> Запрос "sale"
+
+Запрос применяется для оплаты с помощью кредитной карты. При этом информация о карте вводится на стороне сервиса мерчанта и передается в запросе к PaynetEasy. После выполнения данного запроса необходимо выполнить серию запросов "**status**" для обновления статуса платежа. Для этого сервис мерчанта может вывести самообновляющуюся страницу, каждая перезагрузка которой будет выполнять запрос "**status**".
+
+[Пример самообновляющейся страницы](../../example/common/waitPage.html)
+
+##### Обязательные параметры запроса
+
+Поле запроса        |Цепочка свойств платежа            |Правило валидации
+--------------------|-----------------------------------|-----------------
+client_orderid      |payment.clientId                   |Validator::ID
+order_desc          |payment.description                |Validator::LONG_STRING
+amount              |payment.amount                     |Validator::AMOUNT
+currency            |payment.currency                   |Validator::CURRENCY
+address1            |payment.billingAddress.firstLine   |Validator::MEDIUM_STRING
+city                |payment.billingAddress.city        |Validator::MEDIUM_STRING
+zip_code            |payment.billingAddress.zipCode     |Validator::ZIP_CODE
+country             |payment.billingAddress.country     |Validator::COUNTRY
+phone               |payment.billingAddress.phone       |Validator::PHONE
+ipaddress           |payment.customer.ipAddress         |Validator::IP
+email               |payment.customer.email             |Validator::EMAIL
+card_printed_name   |payment.creditCard.cardPrintedName |Validator::LONG_STRING
+credit_card_number  |payment.creditCard.creditCardNumber|Validator::CREDIT_CARD_NUMBER
+expire_month        |payment.creditCard.expireMonth     |Validator::MONTH
+expire_year         |payment.creditCard.expireYear      |Validator::YEAR
+cvv2                |payment.creditCard.cvv2            |Validator::CVV2
+redirect_url        |queryConfig.redirectUrl            |Validator::URL
+
+##### Необязательные параметры запроса
+
+Поле запроса        |Цепочка свойств платежа            |Правило валидации
+--------------------|-----------------------------------|-----------------
+first_name          |payment.customer.firstName         |Validator::MEDIUM_STRING
+last_name           |payment.customer.lastName          |Validator::MEDIUM_STRING
+ssn                 |payment.customer.ssn               |Validator::SSN
+birthday            |payment.customer.birthday          |Validator::DATE
+state               |payment.billingAddress.state       |Validator::COUNTRY
+cell_phone          |payment.billingAddress.cellPhone   |Validator::PHONE
+destination         |payment.destination                |Validator::LONG_STRING
+site_url            |queryConfig.siteUrl                |Validator::URL
+server_callback_url |queryConfig.callbackUrl            |Validator::URL
+
+[Пример выполнения запроса sale](../../example/sale.php)
+
+## <a name="status"></a> Запрос "status"
+
+Запрос применяется для проверки статуса платежа. Обычно требуется серия таких запросов из-за того, что обработка платежа занимает некоторое время. В зависимости от типа авторизации клиента (необходима 3D-авторизация или нет) и статуса платежа обработка результата этого запроса может происходить несколькими путями.
+
+##### Необходимо обновление платежа
+
+В том случае, если статус платежа не изменился (значение поля **status** - **processing**) и нет необходимости в дополнительных шагах авторизации, то запустить проверку статуса еще раз.
+
+##### Необходима 3D-аторизация
+
+В ответе на запрос будет передано поле **html**, содержимое которого необходимо вывести на экран браузера клиента. Содержимое поля представляет собой форму, которая переадресует пользователя для выполнения 3D-авторизации.
+
+##### Обработка платежа завершена
+
+В ответе на запрос поле **status** содержит результат обработки платежа - **approved**, **filtered**, **declined**, **error**
+
+##### Обязательные параметры запроса
+
+Поле запроса        |Цепочка свойств платежа|Правило валидации
+--------------------|-----------------------|-----------------
+client_orderid      |payment.clientId       |Validator::ID
+orderid             |payment.paynetId       |Validator::ID
+login               |queryConfig.login      |Validator::MEDIUM_STRING
+
+[Пример выполнения запроса status](../../example/status.php)
+
+## <a name="3d-redirect"> Обработка результата платежа после 3D-авторизации
+
+Если при обработке платежа выполнялась 3D-авторизация, то при возвращении пользователя с формы авторизации на сервис мерчанта будут переданы данные с результатом обработки платежа. Обработка этих данных совпадает с обработкой данных для [sale-form, preauth-form или transfer-form](05-payment-form-integration.md) и описана в [базовом примере использования библиотеки](../00-basic-tutorial.md#stage_2).
+
+## <a name="callback"></a> Обработка обратного вызова
+
+После завершения обработки платежа на стороне PaynetEasy, данные с результатом обработки передаются в сервис мерчанта с помощью обратного вызова. Это необходимо, чтобы платеж был обработан сервисом мерчанта независимо от того, выполнил пользователь корректно возврат с шлюза PaynetEasy или нет.
+[Подробнее о Merchant callbacks](06-merchant-callbacks.md)

data/doc/payment-scenarios/01-preauth-capture-transactions.md

@@ -0,0 +1,105 @@
+# Preauth/Capture transactions
+
+Список запросов сценария:
+* [Запрос "preauth"](#preauth)
+* [Запрос "capture"](#capture)
+* [Запрос "status"](#status)
+
+## Общие положения
+
+* В данной статье описывается исключительно работа с библиотекой. Полная информация о выполнении Preauth/Capture transactions расположена в [статье в wiki PaynetEasy](http://wiki.payneteasy.com/index.php/PnE:Preauth/Capture_Transactions).
+* Описание правил валидации можно найти в описании метода **[Validator::validateByRule()](../library-internals/02-validator.md#validateByRule)**.
+* Описание работы с цепочками свойств можно найти в описании класса **[PropertyAccessor](../library-internals/03-property-accessor.md)**
+
+## <a name="preauth"></a> Запрос "preauth"
+
+Запрос применяется для блокирования части средств кредитной карты клиента. При этом информация о карте вводится на стороне сервиса мерчанта и передается в запросе к PaynetEasy. После отправки данного запроса необходимо выполнить серию запросов "**status**" для обновления статуса платежа. Для этого сервис мерчанта может вывести самообновляющуюся страницу, каждая перезагрузка которой будет выполнять запрос "**status**". После успешного завершения этого запроса для списания средств с карты клиента необходимо выполнить запрос **[capture](#capture)**.
+
+[Пример самообновляющейся страницы](../../example/common/waitPage.html)
+
+##### Обязательные параметры запроса
+
+Поле запроса        |Цепочка свойств платежа            |Правило валидации
+--------------------|-----------------------------------|-----------------
+client_orderid      |payment.clientId                   |Validator::ID
+order_desc          |payment.description                |Validator::LONG_STRING
+amount              |payment.amount                     |Validator::AMOUNT
+currency            |payment.currency                   |Validator::CURRENCY
+address1            |payment.billingAddress.firstLine   |Validator::MEDIUM_STRING
+city                |payment.billingAddress.city        |Validator::MEDIUM_STRING
+zip_code            |payment.billingAddress.zipCode     |Validator::ZIP_CODE
+country             |payment.billingAddress.country     |Validator::COUNTRY
+phone               |payment.billingAddress.phone       |Validator::PHONE
+ipaddress           |payment.customer.ipAddress         |Validator::IP
+email               |payment.customer.email             |Validator::EMAIL
+card_printed_name   |payment.creditCard.cardPrintedName |Validator::LONG_STRING
+credit_card_number  |payment.creditCard.creditCardNumber|Validator::CREDIT_CARD_NUMBER
+expire_month        |payment.creditCard.expireMonth     |Validator::MONTH
+expire_year         |payment.creditCard.expireYear      |Validator::YEAR
+cvv2                |payment.creditCard.cvv2            |Validator::CVV2
+redirect_url        |queryConfig.redirectUrl            |Validator::URL
+
+##### Необязательные параметры запроса
+
+Поле запроса        |Цепочка свойств платежа            |Правило валидации
+--------------------|-----------------------------------|-----------------
+first_name          |payment.customer.firstName         |Validator::MEDIUM_STRING
+last_name           |payment.customer.lastName          |Validator::MEDIUM_STRING
+ssn                 |payment.customer.ssn               |Validator::SSN
+birthday            |payment.customer.birthday          |Validator::DATE
+state               |payment.billingAddress.state       |Validator::COUNTRY
+cell_phone          |payment.billingAddress.cellPhone   |Validator::PHONE
+destination         |payment.destination                |Validator::LONG_STRING
+site_url            |queryConfig.siteUrl                |Validator::URL
+server_callback_url |queryConfig.callbackUrl            |Validator::URL
+
+[Пример выполнения запроса preauth](../../example/preauth.php)
+
+## <a name="capture"></a> Запрос "capture"
+
+Запрос применяется для списания средств, ранее блокированных запросом **[preauth](#preauth)**, с карты клиента. После выполнения данного запроса необходимо выполнить серию запросов "**status**" для обновления статуса платежа. Для этого сервис мерчанта может вывести самообновляющуюся страницу, каждая перезагрузка которой будет выполнять запрос "**status**". **Внимание!** Если в библиотеку будет передан платеж, созданный ранее для выполнения запроса **[preauth](#preauth)**, то его данные будут перезаписаны данными запроса **capture**. Создайте для запроса **capture** новый платеж.
+
+##### Обязательные параметры запроса
+
+Поле запроса        |Цепочка свойств платежа|Правило валидации
+--------------------|-----------------------|-----------------
+client_orderid      |payment.clientId       |Validator::ID
+orderid             |payment.paynetId       |Validator::ID
+login               |queryConfig.login      |Validator::MEDIUM_STRING
+
+[Пример выполнения запроса capture](../../example/capture.php)
+
+## <a name="status"></a> Запрос "status"
+
+Запрос применяется для проверки статуса платежа. Обычно требуется серия таких запросов из-за того, что обработка платежа занимает некоторое время. В зависимости от типа авторизации клиента (необходима 3D-авторизация или нет) и статуса платежа обработка результата этого запроса может происходить несколькими путями.
+
+##### Необходимо обновление платежа
+
+В том случае, если статус платежа не изменился (значение поля **status** - **processing**) и нет необходимости в дополнительных шагах авторизации, то запустить проверку статуса еще раз.
+
+##### Необходима 3D-аторизация (только при выполнении запроса **[preauth](#preauth)**)
+
+В ответе на запрос будет передано поле **html**, содержимое которого необходимо вывести на экран браузера клиента. Содержимое поля представляет собой форму, которая переадресует пользователя для выполнения 3D-авторизации.
+
+##### Обработка платежа завершена
+
+В ответе на запрос поле **status** содержит результат обработки платежа - **approved**, **filtered**, **declined**, **error**
+
+##### Обязательные параметры запроса
+
+Поле запроса        |Цепочка свойств платежа|Правило валидации
+--------------------|-----------------------|-----------------
+client_orderid      |payment.clientId       |Validator::ID
+orderid             |payment.paynetId       |Validator::ID
+login               |queryConfig.login      |Validator::MEDIUM_STRING
+
+[Пример выполнения запроса status](../../example/status.php)
+
+## <a name="3d-redirect"> Обработка результата платежа после 3D-авторизации (только при выполнении запроса **[preauth](#preauth)**)
+
+Если при обработке платежа выполнялась 3D-авторизация, то при возвращении пользователя с формы авторизации на сервис мерчанта будут переданы данные с результатом обработки платежа. Обработка этих данных совпадает с обработкой данных для [sale-form, preauth-form или transfer-form](05-payment-form-integration.md) и описана в [базовом примере использования библиотеки](../00-basic-tutorial.md#stage_2).
+
+## <a name="callback"></a> Обработка обратного вызова
+
+После завершения обработки платежа на стороне PaynetEasy, данные с результатом обработки передаются в сервис мерчанта с помощью обратного вызова. Это необходимо, чтобы платеж был обработан сервисом мерчанта независимо от того, выполнил пользователь корректно возврат с шлюза PaynetEasy или нет.
+[Подробнее о Merchant callbacks](06-merchant-callbacks.md)

data/doc/payment-scenarios/02-transfer-transactions.md

@@ -0,0 +1,89 @@
+# Transfer transactions
+
+Список запросов сценария:
+* [Запрос "create-card-ref"](#create-card-ref)
+* [Запрос "transfer-by-ref"](#transfer-by-ref)
+* [Запрос "status"](#status)
+
+## Общие положения
+
+* В данной статье описывается исключительно работа с библиотекой. Полная информация о выполнении Transfer transactions расположена в [статье в wiki PaynetEasy](http://wiki.payneteasy.com/index.php/PnE:Transfer_Transactions).
+* Описание правил валидации можно найти в описании метода **[Validator::validateByRule()](../library-internals/02-validator.md#validateByRule)**.
+* Описание работы с цепочками свойств можно найти в описании класса **[PropertyAccessor](../library-internals/03-property-accessor.md)**
+
+## <a name="create-card-ref"></a> Запрос "create-card-ref"
+
+Запрос применяется для получения id для кредитной карты, сохраненной на стороне PaynetEasy. Этот id позволяет совершать повторные платежи без ввода данных кредитной карты как на стороне сервиса мерчанта так и на стороне PaynetEasy.
+Перед выполнением этого запроса необходимо выполнить один из следующих сценариев для проверки данных, которые ввел клиент:
+* [Sale Transactions](00-sale-transactions.md)
+* [Preauth/Capture Transactions](01-preauth-capture-transactions.md)
+* [Payment Form Integration](05-payment-form-integration.md)
+
+##### Обязательные параметры запроса
+
+Поле запроса        |Цепочка свойств платежа|Правило валидации
+--------------------|-----------------------|-----------------
+client_orderid      |payment.clientId       |Validator::ID
+orderid             |payment.paynetId       |Validator::ID
+login               |queryConfig.login      |Validator::MEDIUM_STRING
+
+[Пример выполнения запроса create-card-ref](../../example/create-card-ref.php)
+
+После выполнения данного запроса будет получен id сохраненной кредитной карты и создан объект **[RecurrentCard](../library-internals/00-payment-data.md#RecurrentCard)**. Получить доступ к **RecurrentCard** можно с помощью вызова
+`$payment->getRecurrentCardFrom()`, а к ее id с помощью вызова `$payment->getRecurrentCardFrom()->getCardReferenceId()`
+
+## <a name="transfer-by-ref"></a> Запрос "transfer-by-ref"
+
+Запрос применяется для перевода определенной суммы с одного счета на другой.
+Перед выполнением этого запроса необходимо как минимум один запрос [create-card-ref](#create-card-ref), для получения id сохраненной карты, на которую производится перевод средств. Если перевод выполняется между двумя картами клиентов, то необходимо выполнить два запроса [create-card-ref](#create-card-ref), для получения id сохраненных карт, между которымы переводятся средства.
+После выполнения данного запроса необходимо выполнить серию запросов "**status**" для обновления статуса платежа. Для этого сервис мерчанта может вывести самообновляющуюся страницу, каждая перезагрузка которой будет выполнять запрос "**status**".
+
+##### Обязательные параметры запроса
+
+Поле запроса            |Цепочка свойств платежа            |Правило валидации
+------------------------|-----------------------------------|-----------------
+client_orderid          |payment.clientId                   |Validator::ID
+amount                  |payment.amount                     |Validator::AMOUNT
+currency                |payment.currency                   |Validator::CURRENCY
+ipaddress               |payment.customer.ipAddress         |Validator::IP
+destination-card-ref-id |payment.recurrentCardTo.paynetId   |Validator::ID
+login                   |queryConfig.login                  |Validator::MEDIUM_STRING
+
+##### Необязательные параметры запроса
+
+Поле запроса            |Цепочка свойств платежа            |Правило валидации
+------------------------|-----------------------------------|-----------------
+order_desc              |payment.description                |Validator::LONG_STRING
+source-card-ref-id      |payment.recurrentCardFrom.paynetId |Validator::ID
+cvv2                    |payment.recurrentCardFrom.cvv2     |Validator::CVV2
+redirect_url            |queryConfig.redirectUrl            |Validator::URL
+server_callback_url     |queryConfig.callbackUrl            |Validator::URL
+
+[Пример выполнения запроса transfer-by-ref](../../example/transfer-by-ref.php)
+
+## <a name="status"></a> Запрос "status"
+
+Запрос применяется для проверки статуса платежа. Обычно требуется серия таких запросов из-за того, что обработка платежа занимает некоторое время. В зависимости от статуса платежа обработка результата этого запроса может происходить несколькими путями.
+
+##### Необходимо обновление платежа
+
+В том случае, если статус платежа не изменился (значение поля **status** - **processing**) и нет необходимости в дополнительных шагах авторизации, то запустить проверку статуса еще раз.
+
+##### Обработка платежа завершена
+
+В ответе на запрос поле **status** содержит результат обработки платежа - **approved**, **filtered**, **declined**, **error**
+
+##### Обязательные параметры запроса
+
+Поле запроса        |Цепочка свойств платежа|Правило валидации
+--------------------|-----------------------|-----------------
+client_orderid      |payment.clientId       |Validator::ID
+orderid             |payment.paynetId       |Validator::ID
+login               |queryConfig.login      |Validator::MEDIUM_STRING
+
+[Пример выполнения запроса status](../../example/status.php)
+
+## <a name="callback"></a> Обработка обратного вызова
+
+После завершения обработки платежа на стороне PaynetEasy, данные с результатом обработки передаются в сервис мерчанта с помощью обратного вызова. Это необходимо, чтобы платеж был обработан сервисом мерчанта независимо от того, выполнил пользователь корректно возврат с шлюза PaynetEasy или нет.
+[Подробнее о Merchant callbacks](06-merchant-callbacks.md)