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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3.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.

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

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

Method - POST, GET

https://merchant.intellectmoney.ru/ru/ - Русский язык
https://merchant.intellectmoney.ru/en/ - Английский язык
https://merchant.intellectmoney.ru/de/ - Немецкий язык
https://merchant.intellectmoney.ru/fr/ - Французский язык
https://merchant.intellectmoney.ru/es/ - Испанский язык
https://merchant.intellectmoney.ru/pt/ - Португальский язык
https://merchant.intellectmoney.ru/it/ - Итальянский язык
https://merchant.intellectmoney.ru/jp/ - Японский язык
https://merchant.intellectmoney.ru/bg/ - Болгарский язык

Таблица 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="user_email" value="test@test.ru">
     <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 отправляет HTTP-запрос на адрес, указанный в поле Result Url в настройках магазина. Отправляемая форма имеет следующие атрибуты и поля (Все значения полей, отправляемые системой 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("/139.45.224.\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":"Спички",
				"paymentSubjectType": 1,
				"paymentMethodType": 4
			},
			{
				"quantity":1.000,
				"price":53.70,
				"tax":4,
				"text":"Кефир",
				"supplierINN": 3808027390
			}
		],
	}
} 

<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":"Спички","paymentSubjectType": 1,"paymentMethodType": 4,"supplierINN": 3808027390}],
"customerContact":"foo@example.com"}}' name="merchantReceipt">

$inputPositions = array(
	array("quantity"=>"1", "price"=>"10", "tax"=>"6", "text"=>"Товар номер 1", "paymentSubjectType" => 1, "paymentMethodType" => 4),
	array("quantity"=>"1", "price"=>"11", "tax"=>"6", "text"=>"Товар номер 2", "supplierINN" => 3808027390),
	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'],
				'paymentSubjectType' => $position['paymentSubjectType'],
				'paymentMethodType' => $position['paymentMethodType'],
				'supplierINN' => $position['supplierINN']
            );
        }

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

        return json_encode($merchantReceipt);
}

<form method='POST' action='https://merchant.intellectmoney.ru/ru/' >
  <input id='orderId' type='hidden' value='433194' name='orderId'/>
  <input id='eshopId' type='hidden' value='455551' name='eshopId'/>
  <input id='serviceName' type='hidden' value='Обработка документа' name='serviceName'/>
  <input id='recipientAmount' type='text' value='10.00' name='recipientAmount'/>руб.
  <input type='hidden' value='RUB' name='recipientCurrency'/>
  <input type='hidden' value='http://test.ru' name='successUrl'/>
  <input id='userEmail' type='hidden' value='s.zhukov+1@intellectmoney.ru' name='user_email'/>
  <input type="hidden" name="hash" value="Geo34urc39a3tue34289aoua9eu">
  <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="hidden" name="UserFieldName_3" value="Param name for value_3">
  <input type="hidden" name="AnotherField" value="AnotherField">
  <input type=submit value='Оплатить' /><br/>
</form>

value_2

Param name for value_2

Param name for value_3

AnotherField