Описание интерфейса приема платежей

1.   Бизнес схемы

Взаимодействие системы IntellectMoney, Интернет-магазина и Пользователя (Покупателя) происходит по следующей схеме:

1. Пользователь (Покупатель) заполняет платежную форму (п.4.2.1, Табл.2) на сайте Интернет-магазина.

2. Интернет-магазин отправляет запрос на оплату в систему IntellectMoney с передачей данных платежной формы, и перенаправляет Пользователя (Покупателя) на сайт IntellectMoney.

3. IntellectMoney запрашивает у Пользователя (Покупателя) подтверждение правильности полученных данных.

4. Пользователь (Покупатель) подтверждает данные.

5. Если Пользователь (Покупатель) выбрал мгновенную оплату, IntellectMoney сразу же принимает платеж Пользователя (Покупателя). Если выбрана оплата отложенным платежом, шаг 5 не производится.

6. IntellectMoney выводит сообщение о завершении процедуры оплаты, перенаправляет Пользователя (Покупателя) на сайт Интернет-магазина и сообщает о завершении процедуры оплаты ( URL удачного платежа , п.4.1, Табл.1)

7. Если выбрана отложенная оплата, Пользователь (Покупатель) асинхронно оплачивает покупку, сделанную в Интернет-магазине.

8. В порядке общей очереди, IntellectMoney обрабатывает все имеющиеся платежи и в асинхронном режиме сообщает Интернет-магазину о факте поступления средств на его счет ( URL оповещения о платеже , п.4.2.1, Табл.2).

2.   Общая информация

Система IntellectMoney.Merchant предоставляет Интернет-магазинам (далее продавец) возможность оплачивать покупки Пользователями (далее покупатель) разными способами, например со счета в системе ИнтеллектМани, банковской картой, денежным переводом, терминальным или банковским платежом.

Покупатель формирует заказ на сайте продавца, выбирает способ оплаты через ИнтеллектМани и переходит на сайт IntellectMoney.Merchant, где покупателю выставляется счет к оплате (далее СКО) на основе данных полученных с сайта продавца. Каждая покупка имеет счет к оплате (далее СКО) это уникальный номер в системе, начинающийся с 3 и состоящий из 10 цифр и имеющий срок годности (максимально 6 месяц с момента создания) и сумму покупки.

Оплата СКО

Продавец может выбрать какие способы оплаты будут доступны покупателю. СКО покупатель может оплатить несколькими платежами.

Если после зачисления платежа на СКО не полностью подтверждено, то оно считается частично подтвержденным. Частично подтвержденное СКО может аннулировать покупатель из ЛК или сайта мерчанта. При аннулировании счета все средства зачисленные на СКО, зачисляются на счет покупателя.  Если покупатель не зарегистрирован в системе то на указанный емайл на сайте мерчанта создается счет, в этом случае покупатель может воспользоваться сдачей, зарегистрировавшись в системе указав в качестве логина емайл указанный в СКО.

Если после зачисления платежа на СКО остаются средства, создается два платежа, «итоговый»  создается на сумму СКО,- он зачисляется магазину на счет за вычетом комиссии ИнтеллектМани и «сдача» создается на сумму переплаты и зачисляется на счет покупателя. После создания «итогового» платежа СКО становится подтвержденным. Пользователь может продолжать делать платежи на такое СКО, при этом все средства будут уходить в сдачу покупателя.

Срок годности СКО

У СКО есть срок годности это параметр, который продавец передает на сайт мерчанта вместе с суммой покупки. Если продавец не передал срок годности, то ИнтеллектМани выставляет время жизни СКО 6 месяцев с момента создания покупки. В момент окончания срока действия СКО частично подтвержденное СКО переводит все деньги в сдачу покупателя. Если СКО было заморожено, то все деньги переводятся на счет продавца за вычетом комиссии ИнтеллектМани.

В случае попадания денежных средств плательщика на отмененный СКО средства попадают в сдачу плательщика.

Холдирование

Продавец может настроить работу СКО в режиме «холдирования». Для настройки данного режима достаточно передать параметры  holdMode, expireDate и holTime , а также необходимо   включить в настройках магазина параметр «Принимать только уникальные ID покупки».

Данный режим используется для заморозки счета СКО. В основном данный режим удобно использовать в случае, если пользователи интернет магазина часто оплачивают банковскими картами. Выписав СКО в режиме холдирования и оплатив с банковской карты, сумма на банковской карте не списывается, а блокируется, само СКО при полной оплате не изменит своё состояние, до установленного времени холдирования, но может сменить состояние по запросу магазина. Либо отменить СКО, в этом случае денежные средства, которые были на СКО, вернутся пользователю. Если происходит подтверждение денежные средства зачисляются магазину.

При отмене СКО магазином заблокированная сумма на банковской карте возвращается обратно, а все другие средства будут списаны в сдачу. Например, покупатель выписал СКО на 100 рублей, с терминала он оплатил 30 рублей, а остальную сумму он оплатил с банковской карты. Магазин или покупатель аннулировали СКО, в сдачу покупателю будет зачислено 30 рублей, а 70 рублей вернется на банковскую карту. В случае оплаты СКО способами отличными от банковских карт, при отмене СКО денежные средства возвращаются пользователю на счёт.

Максимальная дата холдирования СКО 119 часов (4 дня 23 часа) с момента оплаты. Если до даты действия СКО продавец не отправит в систему ИнтеллектМани запрос на аннулирование или зачисление СКО, то СКО будет автоматически зачислен на счёт магазина или вернется на счёт покупателю (в зависимости от настроек магазина в личном кабинете) автоматически.

Пользователь (Покупатель) выбирает в Интернет-магазине товар, магазин подсчитывает сумму Заказа и посылает запрос на оплату к системе IntellectMoney. IntellectMoney принимает платеж от Пользователя (Покупателя) и сообщает Интернет-магазину о получении платежа.

Платежи принимаются системой IntellectMoney с помощью безопасного протокола передачи данных SSL.

Интерфейсы системы IntellectMoney позволяют Интернет-магазинам мгновенно узнавать о принятых платежах, а также о факте получения отложенных платежей.

Далее приводится полное описание интерфейсов приема платежей Интернет-магазинами с помощью системы IntellectMoney.

3.   Последовательность приема платежей системой IntellectMoney через интернет-магазин

Взаимодействие системы IntellectMoney, интернет-магазина и пользователя (покупателя) происходит по следующей схеме:

1. Покупатель выбирает товар на веб-сайте интернет-магазина;
2. Интернет-магазин создает заказ (покупку), формирует и выводит покупателю “Форму запроса платежа” для отправки его на оплату в IntellectMoney (п.4.2.1, Таблица 2, Пример 1).
3. Пользователь (покупатель) переходит на веб-сайт IntellectMoney, выбирает способ оплаты (из  заданных параметром preference в “Форме запроса платежа” (в случае если он задан), или из всех возможных (если не задан). Вводит идентификационные данные: E-mail, или логин/пароль (если есть).
4. Система IntellectMoney создает счет к оплате (СКО) на основе данных полученных из “Формы запроса платежа”.
5. Информация о созданном (выставленном) СКО и способе его оплаты выводится покупателю.
6. Система IntellectMoney отправляет уведомление интернет-магазину о создании СКО через “Форму оповещения о платеже” (п.4.2.2, Таблица 3, Пример 2) с полем paymentStatus = 3 (создан СКО).
7. Покупатель оплачивает покупку одним из доступных способов.
8. Если при создании покупки интернет-магазин в  “Форме запроса платежа” не указал (не передал) параметр holdMode, то далее выполнение продолжается с шага 10 немедленно зачисляя средства на счет интернет-магазина.
   В противном случае (задан параметр holdMode) система IntellectMoney отправляет уведомление интернет-магазину о создании СКО через “Форму оповещения о платеже” (п.4.2.2, Таблица 3, Пример 2) с полем paymentStatus = 6 (необходимая сумма заблокирована на СКО, ожидается запрос на списание или разблокировку средств или истечение срока блокировки).
9. Интернет-магазин отправляет запрос системе IntellectMoney о действии с заблокированными средствами через “Форму запроса зачисления или разблокировки  средств” (п.4.2.3, Таблица 4, Пример 3) с параметром action = Refund (для разблокировки  средств (возврата пользователю), или ToPaid (для зачисления средств на счет интернет-магазина).
10. В соответствии с запросом пришедшем на шаге 9 система IntellectMoney зачисляет средства на счет интернет-магазина, или аннулирует СКО и возвращает средства пользователю.
    Если интернет-магазин не отправлял запрос в соответствии с шагом 9, то по истечении срока блокировки средств на СКО система IntelectMoney автоматически зачисляет средства на счет интернет-магазина, или возвращает средства пользователю, в зависимости от настроек магазина в личного кабинете.
11. Система IntellectMoney отправляет уведомление интернет-магазину об оплате СКО, или аннулировании (только в случае с блокировкой средств) СКО через “Форму оповещения о платеже” (п.4.2.2, Таблица 3, Пример 2) с полем paymentStatus = 5 (СКО полностью подтвержден, деньги переведены на счет интернет-магазина), paymentStatus = 4 (СКО аннулирован, деньги возвращены пользователю), paymentStatus = 7 (СКО частично подтвержден, в этом случае будет передана сумма которая уже подтверждена).

4.  Интерфейсы

4.1. Регистрационные данные интернет-магазина

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

Для сайта интернет-магазина в системе хранится свой набор значений. Страница в личном кабинете юр. лица   https://www.intellectmoney.ru/ru/enter/ps_organization_shop/ для редактирования параметров кликнуть на ссылку "Редактировать" выбранного магазина. Необходимо заполнить поля, а так же правильно выбрать счет, на который будут зачисляться платежи. Для удобства тестирования протокола, вам нужно выбрать счет с тестовой валютой (тст.). После удачного тестирования, необходимо перейти на счет с рублевой валютой.

Вторым шагом необходимо настроить протокол "ИнтеллектМани". На странице   https://www.intellectmoney.ru/ru/enter/ps_organization_shop/ нужно перейти в настройки протокола кликнув на ссылку "ИнтеллектМани" у настраиваемого магазина. Перечень параметров протокола и их назначение приведен в Таблице 1:

Таблица 1. Перечень параметров протокола

Форма запроса платежа - генерируется веб-сайтом интернет-магазина для формирования запроса на создание (выставление) СКО (счета к оплате) для оплаты покупки в системе IntellectMoney. Передается через веб-браузер пользователя (покупателя).

Форма оповещения о платеже - генерируется системой IntellectMoney для оповещения интернет-магазина о создании или изменении статуса СКО. Оповещение передается без использования веб-браузера пользователя (покупателя) на веб-сайт интернет-магазина.

Форма запроса зачисления, или разблокировки  средств - генерируется интернет-магазином для запроса разблокировки средств (возврата пользователю), или зачисления средств на счет интернет-магазина в системе IntellectMoney. Используется в случае, если при создании СКО была задана дата блокировки (холдирования) средств на СКО. Запрос передается без использования веб-браузера пользователя (покупателя) на веб-сайт IntellectMoney.

4.2.1. Форма запроса платежа

Эта форма передает запрос с веб-сайта интернет-магазина в систему IntellectMoney через веб-браузер пользователя (покупателя). Она должна иметь следующие атрибуты и поля:
Action -   https://merchant.intellectmoney.ru/ru/ Method - POST, GET

Таблица 2.1 Поля формы запроса платежа

<html>
<head>
...
</head>
... 
<form action="https://merchant.intellectmoney.ru/ru/" name="pay" method="POST">
     <input type="hidden" name="eshopId" value="17354">
     <input type="hidden" name="orderId" value="order_0000001">
     <input type="hidden" name="serviceName" value="Книга">
     <input type="hidden" name="recipientAmount" value="12.30">
     <input type="hidden" name="recipientCurrency" value="RUB">
     <input type="hidden" name="successUrl" value="http://eshop.ru/success">
     <input type="hidden" name="failUrl" value="http://eshop.ru/fail">
     <input type="hidden" name="expireDate" value="2010-11-30 22:55:00">
	 <input type="hidden" name="merchantReceipt" value='{"inn":"7704019762","group":"Main","content":{"type":1,"positions":[{"quantity":2.000,"price":12.45,"tax":6,"text":"Булка"},{"quantity":1.000,"price":5.10,"tax":4,"text":"Спички"}],"customerContact":"foo@example.com"}}'>   
     <input type="hidden" name="UserField_1" value="value_1">
     <input type="hidden" name="UserField_2" value="value_2">
     <input type="hidden" name="UserFieldName_2" value="Param name for value_2">
     ...
     ...
     <input type="submit" name="button" value="оплатить">
</form>
...
</body><body>
</html>

Эта форма отправляется интернет-магазину при создании СКО и изменении его статуса. Она имеет следующие атрибуты и поля (Все значения полей, отправляемые системой IntellectMoney будут транслированы):

Action - URL информирования о платеже

Method - POST

Content-Type - application/x-www-form-urlencode

encoding - UTF-8

Поля, передаваемые в форме, описаны в Таблице 3. После получения запроса от системы IntellectMoney о создании СКО или изменении статуса СКО магазин должен ответить системе IntellectMoney на этот запрос статусом 200 и текстом OK (две буквы латинского алфавита). Если система IntellectMoney не получит ответ или текст ответа магазина будет отличным от OK, запрос будет направлен повторно. Система IntellectMoney будет дублировать магазину запрос по одному и тому же событию до тех пор, пока не будет получен ответ OK (с этого момента запрос будет считаться принятым магазином). В случае, когда система IntellectMoney дублирует сообщения магазину по разным событиям очередность прихода данных сообщений может быть произвольной. Магазин должен в правильной последовательности, корректно обрабатывать запросы от системы IntellectMoney.

Пример корректного ответа обработчика магазина при успешном принятии уведомления о создании или изменении счета (частичная оплата счета, полная оплата счета и т.д.):

<?
echo "OK";
?>

Таблица 3. Поля формы оповещения о платеже.

<html>
<head>
...
</head>
<body>
...
<form method="POST" action=" URL Оповещение   о   платеже ">
     <input type="hidden" name="eshopId" value=" 17354 ">
     <input type="hidden" name="paymentId" value=" 2001322292 ">
     <input type="hidden" name="orderId" value=" order_0000001 ">
     <input type="hidden" name="eshopAccount" value=" 4356091274 ">
     <input type="hidden" name="serviceName" value=" Книга ">
     <input type="hidden" name="recipientAmount" value=" 12.30 ">
     <input type="hidden" name="recipientOriginalAmount" value=" 12.30 ">
     <input type="hidden" name="recipientCurrency" value=" RUB ">
     <input type="hidden" name="paymentStatus" value=" 5 ">
     <input type="hidden" name="userName" value=" Артем Дворядкин ">
     <input type="hidden" name="userEmail" value="  tema@intellectmoney.ru  ">
     <input type="hidden" name="paymentData" value=" 2010-01-17 13:12:03 ">
     <input type="hidden" name="secretKey" value=" myKey ">
     <input type="hidden" name="hash" value=" 61620ea240928af649e44aaebb1c15dd ">
     <input type="hidden" name="UserField_1" value=" value_1 ">
     <input type="hidden" name="UserField_2" value=" value_2 ">
     <input type="hidden" name="UserFieldName_2" value=" Param name for value_2 ">
     ...
     ...
</form>
...
</body>
</html>

<html> 
<head> 
... 
</head> 
<body> 
... 
<form action="https://merchant.intellectmoney.ru/ru/" name="pay" method="POST"> 
<input type="hidden" name="eshopId" value="17354"> 
<input type="hidden" name="orderId" value="order_0000001"> 
<input type="hidden" name="action" value="ToPaid"> 
<input type="hidden" name="secretKey" value="myKey" >
<input type="hidden" name="merchantReceipt" value='[{"Quantity":1.0,"Price":137.0,"Tax":1,"Text":"euoa"},{"Quantity":1.0,"Price":1.0,"Tax":1,"Text":"euoa"}]' > 
<input type="hidden" name="hash" value="8873d8442f5a9e1ad884114c15f11706"> 
<input type="submit" name="button" value="отправить"> 
</form> 
.. 
</body> 
</html>

<html> 
<head> 
... 
</head> 
<body> 
... 
<form action="https://merchant.intellectmoney.ru/ru/" name="pay" method="POST"> 
<input type="hidden" name="eshopId" value="17354"> 
<input type="hidden" name="orderId" value="order_0000001"> 
<input type="hidden" name="action" value="Refund"> 
<input type="hidden" name="secretKey" value="myKey" > 
<input type="hidden" name="hash" value="9817934869710f99703ed9246b4867cc"> 
<input type="submit" name="button" value="отправить"> 
</form> 
.. 
</body> 
</html>

<html> 
<head> 
... 
</head> 
<body> 
... 
<form action="https://merchant.intellectmoney.ru/ru/" name="pay" method="POST"> 
<input type="hidden" name="eshopId" value="17354"> 
<input type="hidden" name="orderId" value="order_0000001"> 
<input type="hidden" name="action" value="Refund"> 
<input type="hidden" name="operationAmount" value="12.00"> 
<input type="hidden" name="secretKey" value="myKey" > 
<input type="hidden" name="hash" value="9817934869710f99703ed9246b4867cc"> 
<input type="submit" name="button" value="отправить"> 
</form> 
.. 
</body> 
</html>

<?php 
	$data = [
		'eshopId' => 'Номер Вашего магазина в IntellectMoney',
		'orderId' => 'Номер заказа в системе интернет магазина',
		'action' => 'ToPaid',
		'secretKey' => 'Секретный ключ магазина в IntellectMoney',
		'hash' => 'создайте хэш',
	];
	$URL = 'https://merchant.intellectmoney.ru/ru/index.php';

	$ch = curl_init();
	curl_setopt($ch, CURLOPT_URL, $URL );
	curl_setopt($ch, CURLOPT_USERAGENT, 'Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US; rv:1.9.1.2) Gecko/20090729 Firefox/3.5.2 GTB5');
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
	curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
	curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
	curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

	$result = curl_exec($ch);
	curl_close($ch);
	print_r($result);
?>

if (!preg_match("/91.212.151.\d{0,255}/", $_SERVER['REMOTE_ADDR'])){
    return "ERROR! IP MISMATCH!"; die;
}

{
"inn":"7704019762",
"group":"Main",
"content":
	{
		"type":1,
		"customerContact":"foo@example.com"
		"positions":[
					{
						"quantity":2.000,
						"price":12.45,
						"tax":6,
						"text":"Булка"
					},
					{
						"quantity":1.000,
						"price":5.10,
						"tax":4,
						"text":"Спички"
					}
					],
	}
} 

<input type="hidden" value='{"inn":"7704019762","group":"Main","content":{"type":1,"positions":
[{"quantity":2.000,"price":12.45,"tax":6,"text":"Булка"},
{"quantity":1.000,"price":5.10,"tax":4,"text":"Спички"}],
"customerContact":"foo@example.com"}}' name="merchantReceipt">

$inputPositions = array(
	array("quantity"=>"1", "price"=>"10", "tax"=>"6", "text"=>"Товар номер 1"),
	array("quantity"=>"1", "price"=>"11", "tax"=>"6", "text"=>"Товар номер 2"),
	array("quantity"=>"1", "price"=>"12", "tax"=>"6", "text"=>"Товар номер 3")
);
function createMerchantReceipt($inputPositions){
        $inn = "Ваш ИИН";
        $customerContact = "test@test.ru";//Почта плательщика

        $positions = array();
        foreach($inputPositions as $position){
            $positions[] = array(
                'quantity' => $position['quantity'],
                'price' => $position['price'],
                'tax' => $position['tax'],
                'text' => $position['text'],
            );
        }

        $merchantReceipt = array(
            "inn" => $inn,
            "group" => "Main",
            "content" => array(
                "type" => "1",
                "positions" => $positions,
                "customerContact" => $customerContact
            )
        );

        return json_encode($merchantReceipt);
}