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

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. Перечень параметров протокола


Название параметра

Формат

Описание

URL информирования о платеже (Result URL)

до 512 символов

URL (на веб-сайте интернет-магазина), на который система IntellectMoney посылает HTTP/S POST запросы о совершении платежа. Если интернет-магазин не определил этот URL, он не будет оповещаться системой о совершенных платежах.

URL должен начинаться с префикса “http://” или “https://”.

Секретный ключ (Secret Key)

до 32 символов

Строка символов, используемая для подписи данных передаваемых системой ИнтеллектМани магазину. Эта строка используется для повышения надежности идентификации высылаемого оповещения. Содержание строки известно только системе IntellectMoney и интернет-магазину!

Высылать Secret Key на Result URL
(только при HTTPS)


Если используется защищенное соединение с магазином (https), то можно использовать "секретный ключ" в качестве удостоверения что данные отправлены от ИнтеллектМани.

BackURL

до 512 символов

Адрес, на который будет перенаправлен пользователь (покупатель) после выставления счета в случае если пользователь выбрал “оффлайн” способ оплаты (например: терминалы).

Максимальная длина - 512 символов.

Режим отладки

Чекбокс

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

4.2. Формы HTML

Для передачи информации между сайтом интернет-магазина и системой IntellectMoney используются HTML-формы:

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

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

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

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

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

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


Название

Имя поля HTML формы

Обязательный

Описание

ID магазина

eshopId

Да

Номер сайта интернет-магазина, на который пользователь (покупатель) должен совершить платеж. Можно увидеть на странице   https://www.intellectmoney.ru/ru/enter/ps_organization_shop/ в столбце "ID"

Внутренний номер покупки интернет-магазина

orderId

Да

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

Максимальная длина - 50 символов.

Назначение платежа

serviceName

Нет

Описание товара или услуги. Формируется интернет-магазином.

Максимальная длина - 1024 символов.

Сумма

платежа

recipientAmount

Да

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

Максимальная длина - 10 цифр вместе с десятичными знаками.

Валюта

платежа

recipientCurrency

Да

Валюта платежа. Может принимать значения: RUB и RUR для  платежей в рублях и TST для тестовых платежей.
Правила использования валюты TST описаны в этой статье - Тестирование на тестовой валюте.

Имя Пользователя

userName

Нет

Полное имя пользователя (покупателя). Вводится самим пользователем (покупателем).

Максимальная длина – 255 символов.

E-mail пользователя

user_email

Нет

Email пользователя (покупателя). Вводится самим покупателем.

Максимальная длина – 255 символов.

Адрес удачного платежа

successUrl

Нет

Адрес, на который будет перенаправлен пользователь (покупатель) в случае успешной оплаты

Максимальная длина - 512 символов.

Способы оплаты для пользователя – переход сразу на страницу ввода реквизитов

preference

Нет

Способы оплаты, которые будут доступны для выбора при оплате покупки. В случае указания одного параметра пользователь будет перенаправлен на страницу ввода реквизитов. (при задании параметра  bankCard и указании email пользователя,  пользователь перейдет сразу к вводу номера банковской карты, при этом счёт уже будет создан. В случае, если не указан email ,то пользователь будет перенаправлен на страницу ввода email)

Возможные значения (при выборе нескольких они разделяются запятой):

Оплата со счета IntellectMoney – inner;

Банковская карта Visa/MasterCard – bankCard;

Внимание! Если передать параметр preference или lmi_pay_method при запросе платежа, то будут отображаться только переданные способы оплаты, даже если все остальные включены. Например есть передать preference=BankCard, то пользователь сразу попадет на страницу ввода реквизитов карты. Если нажать на кнопку "Изменить способ оплаты", то пользователь вернется на страницу выборов оплаты, но буден показан только способ оплаты банковской картой. Соответствия preference способам оплаты.

Включение режима холдированияholdModeНет

Отвечает за включение режима холдирования, и может принимать три состояния:

  1. "1" - включает режим холдирования, в данном случае, необходимо передать параметры expireDate и/или holdTime
  2. "0" - выключает режим холдирования, счета не будут холдироваться
  3. "null" = не передавать данный параметр - режим холдирования определяется в настройках магазина в личном кабинете

Также необходимо включить в настройках магазина параметр «Принимать только уникальные ID покупки».

Срок существования СКО

expireDate

Нет

Дата и время, по достижению, которых оплатить счёт в системе IntellectMoney станет не возможно.

Передавать в формате “yyyy-MM-dd HH:mm:ss”.

Срок холдирования денежных средствholdTimeНет

Время, через которое захолдированные (замороженные) денежные средства будут зачислены на счёт магазина или возвращены покупателю, измеряется в часах.

Целое число от 0 до 119 часов.

Данные по чеку
merchantReceiptНет

Данные для формирования чека в онлайн кассе. Подробное описание смотрите в пункте 4.5 Правила формирования чека для онлайн кассы (merchantReceipt)

Параметр является обязательным для магазинов с включенной онлайн-кассой

Компактный дизайнframeНетПри передаче значения 1 платежная страница будет выведена в компактном дизайне

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

Определяется интернет-магазином

Нет

Все поля формы, имеющие в названии префикса "UserField_N", "UserFieldName_N" (где N порядковый номер), обрабатываются системой IntellectMoney автоматически и передаются на сайт интернет-магазина.

Максимальная длина всех дополнительных полей в сумме - 4000 символов.

Подпись для преданных данных

hash

Нет

Контрольная подпись запроса, которая используется для проверки целостности полученной от магазина информации и однозначной идентификации отправителя.

Алгоритм формирования описан в разделе "Проверка данных формы запроса".

Важно: Для операций по расписанию алгоритм формирования подписи описан в разделе "Проверка данных формы запроса для операций по расписанию".

Параметр является обязательным при включении параметра «Требовать HASH»  в настройках магазина.

Тип рекуррентной операции

recurringType

Нет

Тип операции рекарринга принимает одно значение - "Activate".

Данной командой карта регистрируется в цепочке платежей. Дальше, для всех операций с этой картой, нужно передавать оплаченный счет(Номер Счёта К Оплате) в поле recurringSourceInvoiceId, остальные операции над выставленными счетами проводятся системой в автоматическом режиме без участия пользователя. Передавая данный параметр, Вы привязываете карту, которой оплатил покупатель, к номеру СКО по которому производилась оплата.

Только для рекуррентных платежей (Операции по расписанию).

Сообщение для пользователяrecurringInfoНет

Информация для пользователя, которая показывается в процессе оплаты, перед вводом реквизитов банковской карты.

Параметр не поддерживается в текущей версии протокола. Если возникнет необходимость в данном параметре, следует написать на ts@intellectmoney.ru с темой письма: "Recurring 2.0".

Только для рекуррентных платежей (Операции по расписанию).


Пример 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>


4.2.2. Форма оповещения о платеже

Эта форма отправляется интернет-магазину при создании СКО и изменении его статуса. Она имеет следующие атрибуты и поля (Все значения полей, отправляемые системой 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 формы

Описание

Номер сайта интернет-магазина

eshopId

Номер сайта интернет-магазина, на который Пользователь (Покупатель) совершает платеж.

Номер покупки в системе IntellectMoney

paymentId

Номер покупки (СКО) в системе IntellectMoney

Внутренний номер покупки в интернет-магазине

orderId

Номер покупки в соответствии с системой учета интернет-магазина, полученный системой с веб-сайта интернет-магазина.

Номер счета  магазина

eshopAccount

Номер счета интернет-магазина в системе IntellectMoney. На этот счет будут зачислены средства после оплаты покупки.

Назначение платежа

serviceName

Назначение платежа в соответствии с системой учета Интернет-магазина, получаемое системой с веб-сайта Интернет-магазина.

Исходная сумма платежа

recipientOriginalAmount

Исходная сумма платежа. Разделитель дробной части “.“, точность до копейки (2 знака после  разделителя). Не изменяется в процессе оплаты.

Сумма платежа

recipientAmount

Сумма, которую получает Интернет-магазин. Дробная часть отделяется точкой. В процессе оплаты может быть изменена

Валюта платежа

recipientCurrency

Валюта платежа (RUB или TST)

Статус покупки

paymentStatus

Статус платежа может иметь следующие значения: 3 (создан счет к оплате (СКО) за покупку), 4 (СКО аннулирован, деньги возвращены пользователю), 7 (СКО частично подтвержден , в данном случае сумма которая уже подтвержден а передается в параметре recipientAmount), 5 (СКО полностью подтвержден , деньги переведены на счет интернет-магазина), 6 (необходимая сумма заблокирована на СКО, ожидается запрос на списание или разблокировку средств или истечение срока блокировки)

Имя Пользователя

userName

Имя Пользователя (покупателя) выписавшего счет в системе IntellectMoney

Email покупателя

userEmail

Email Пользователя (покупателя) выписавшего счет в системе IntellectMoney

Дата и время выполнения платежа

paymentData

Дата и время реального прохождения платежа в системе IntellectMoney в формате

"yyyy-MM-dd HH:mm:ss".

Способ оплаты

payMethod

Способ оплаты счета. Перечень соответствия значения параметра способу оплаты можно посмотреть здесь

ShortPan пластиковой карты 2

shortPan

Короткий номер пластиковой карты (первая и четыре последние цифры пластиковой карты), которой был оплачен счет.

Страна 2

country

Страна, в которой была выпущена пластиковая карта. 2

Банк эмитент 2

bank

Банк, выпустивший пластиковую карту. 2

IP адрес 2

ipAddress

IP адрес пользователя, совершившего оплату счета. 1

Секретный ключ

secretKey

Значение Секретный ключ, известное только интернет-магазину и системе IntellectMoney. Передается, если включена функция "Отправлять секретный ключ". Это поле будет пустым, если параметр "URL Оповещение о платеже" не обеспечивает секретность (используется протокол HTTP, а не HTTPS).

Контрольная подпись

hash

Контрольная подпись оповещения о выполнении платежа, которая используется для проверки целостности полученной информации и однозначной идентификации отправителя.

Алгоритм формирования описан в разделе "Контрольная подпись данных о платеже".

Параметры интернет-магазина

Определяется интернет-магазином

Все поля, переданные с веб-сайта интернет-магазина в "Форме запроса платежа", имеющие префикс " UserField_N" , "UserFieldName_N" (где N порядковый номер)  

Состояние операции по расписаниюreccurringState


Пример 2. 

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

4.2.3. Форма запроса зачисления или разблокировки средств

Эта форма передается интернет-магазином без использования веб-браузера пользователя (покупателя) на веб-сайт IntellectMoney.

Запрос предназначен для использования в случае если используется блокировка (холдирование) средств на СКО. Запрос может быть отправлен интернет-магазином только после получения оповещения о платеже со статусом покупки (paymentStatus) = 6 (необходимая сумма заблокирована на СКО, ожидается запрос на списание или разблокировку средств или истечение срока блокировки).

В ответ веб-сайт IntellectMoney возвращает строку “OK” в случае удачного выполнения запроса, либо строку с описанием ошибки в противном случае.
Форма должна иметь следующие атрибуты и поля:

Action -   https://merchant.intellectmoney.ru/ru/

Method - POST

Таблица 4. Поля формы запроса зачисления или разблокировки средств

Название

Имя поля HTML формы

Обязательный

Описание

ID магазина

eshopId

Да

Номер сайта интернет-магазина, на который пользователь (покупатель) должен совершить платеж. Можно увидеть на странице   https://www.intellectmoney.ru/ru/enter/ps_organization_shop/ в столбце "ID"

Внутренний номер покупки интернет-магазина

orderId

Да

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

Максимальная длина - 50 символов.

Сумма операции

operationAmount

Нет

Сумма на которую необходимо произвести операцию разблокировки денежных средств по холдированному СКО, или сумма на которую нужно уменьшить изначальную сумму СКО при частичной оплате.

Данный параметр передается только для разблокировки средств при холдированном СКО, или для уменьшения изначальной суммы СКО при частичной оплате (action=Refund).

При зачислении средств (action=ToPaid) или при полном возврате денежных средств данный параметр не передается.

Запрашиваемое действиеactionДа

Действие, которое необходимо произвести с СКО: Refund для разблокировки средств (возврата пользователю), или ToPaid для зачисления средств на счет интернет-магазина

Назначение платежа

serviceName

Нет

Описание товара или услуги. Формируется интернет-магазином.

Максимальная длина - 1024 символов.

Новые параметры чекаmerchantReceiptНет

Данные для формирования нового чека в онлайн кассе.

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

Подробное описание смотрите в пункте 4.5 Формирование merchantReceipt

Подпись для преданных данных

hash

Нет

Контрольная подпись запроса, которая используется для проверки целостности полученной от магазина информации и однозначной идентификации отправителя.

Алгоритм формирования описан в разделе "Контрольная подпись данных о платеже". Требуется только при включении параметра «Требовать HASH»  в настройках магазина.

Секретный ключsecretKey

В случае если не используется подпись (hash).



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

operationAmount - данный параметр используется в случае частичной оплаты СКО, или в случае необходимости частичной разблокировки средств на холдированном СКО.

Случай 1: Был выставлен холдированный СКО на 30.00 рублей. Покупатель оплатил данный СКО пластиковой картой, денежные средства в размере 30.00 рублей блокируются на счете пластиковой карты. У магазина появилась необходимость уменьшить сумму СКО на 10.00 рублей. Магазин передает запрос с параметрами action=Refund и operationAmount=10.00. После этого 10.00 рублей разблокируются на счету пластиковой карты покупателя и сумма СКО уменьшается до 20.00 рублей.

Случай 2: Был выставлен обычный СКО на 30 рублей. Клиент частично оплатил СКО на сумму 20.00 рублей. СКО находиться в состоянии “частично оплачен“ и не может быть зачислен на счет магазина. Магазин отправляет запрос с параметрами action=Refund и operationAmount=10.00. Сумма СКО меняется на 20.00 рублей. СКО переходит в состояние “полностью оплачен“ и зачисляется на счет магазина.


Пример 3.3 


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

Пример 3.4

Для реализации данного примера Вам потребуется пакет libcurl.

<?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);
?>


4.3. Проверка информации о платеже

При выполнении платежа система IntellectMoney высылает оповещение о платеже через "Форму оповещения о платеже" на "URL информирования о платеже", указанный Интернет-магазином. 
Мы рекомендуем вам проверить данные, полученные через "Форму оповещения о платеже": 

  1. Проверить, действительно ли данные переданы от системы IntellectMoney (Проверка источника данных) по IP адресу.
  2. Проверить, не исказились ли данные в процессе передачи (Проверка целостности данных)
  3. Проверить сумму платежа
  4. Проверить номер сайта интернет-магазина

4.3.1. Проверка источника данных

Как указывалось выше, значение параметра "Секретный ключ" должно быть известно только системе IntellectMoney и Интернет-магазину. Исходя из этого, Секретный ключ может использоваться для аутентификации источника, приславшего данные о платеже. Интернет-магазин может провести аутентификацию несколькими методами в зависимости от того, включен ли функционал "Отправлять секретный ключ".
Запросы к магазину от системы ИнтеллектМани могут приходить только с подсети 91.212.151.0/24. Пример проверки принадлежности IP к подсети:

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

Для передачи данных желательно использовать протокол HTTPS.

4.3.2.1. Формирование контрольной подписи

При формировании контрольной подписи система IntellectMoney "склеивает" значения полей в одну строку разделяя их "::".
Для "Формы оповещения о платеже" склеиваются следующие поля в следующем порядке:
1. Номер сайта интернет-магазина (eshopId);
2. Номер покупки интернет-магазина (orderId);
3. Описание покупки (serviceName);
4. Номер счета в системе IntellectMoney (eshopAccount);
5. Сумма платежа (recipientAmount);
6. Валюта платежа (recipientCurrency);
7. Статус платежа (paymentStatus);
8. Имя Пользователя (userName);
9. Email Пользователя (userEmail);
10. Дата и время выполнения платежа (paymentData);
11. Секретный ключ (secretKey

Пример 4. Формирование строки и подписи для проверки в "Форме оповещения о платеже

Строка для подписи: 17354::order_0000001::Книга::4356091274::12.30::RUB::5::АртемДворядкин::tema@intellectmoney.ru::2010-01-17 13:12:03::myKey
Полученный хэш: 61620ea240928af649e44aaebb1c15dd
При реализации проверки подписи рекомендуется сверить полученный результат с приведенным выше примером. 

Для "Формы запроса зачисления или разблокировки средств" склеиваются следующие поля в следующем порядке:

  1. Номер сайта интернет-магазина (eshopId);
  2. Номер покупки интернет-магазина (orderId);
  3. Запрашиваемое действие (action);
  4. Секретный ключ (secretKey)

Пример 5. Формирование строки и подписи для "Формы запроса зачисления или разблокировки средств"

Строка для подписи: 17354::order_0000001::ToPaid::myKey
Полученный хэш: 8873d8442f5a9e1ad884114c15f11706
При реализации формирования подписи рекомендуется сверить полученный результат с приведенным выше примером.
MD5 формируется последовательность из 32-х шестнадцатеричных цифр (пример "f849a1c57c66b372ec4a3a2e04d2feba") в соответствии с широко распространенным алгоритмом Message Digest 5 (MD5) разработанным Ron Rivest из MIT Laboratory for Computer Science и RSA Data Security, Inc. Алгоритм был опубликован в Интернете в апреле 1992 года (RFC 1321).

4.3.2.2. Проверка контрольной подписи

Проверка контрольной подписи на сайте интернет-магазина по следующему алгоритму:

  1. Сформируйте строку путем "склеивания" значений параметров, полученных через "Форму оповещения о платеже", в том же порядке, что и при формировании контрольной подписи разделяя их "::" в системе IntellectMoney (см. выше). Помните, что при формировании подписи используется Секретный ключ.
  2. Вычислите MD5 полученной строки.
  3. Сравните полученное значение с значением параметра "hash", полученного через "Форму оповещения о платеже". Если сформированная подпись совпадает с полученной через "Форму оповещения о платеже", данные не изменены, и источник данных действительно система IntellectMoney.

4.3.2.3. Проверка суммы и валюты платежа

Несмотря на то, что пользователь (покупатель) не может изменить сумму платежа, интернет-магазину рекомендуется контролировать информацию о сумме и валюте платежа, передаваемую через параметры "recipientAmount" и "recipientCurrency".

4.3.2.4 Проверка номера сайта (ID) интернет-магазина

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

4.4.1 Проверка данных формы запроса

Для исключения случая подмены передаваемых магазином данных, магазин может подписать их. В таком случае ИМ будет проверять полученные данные согласно подписи. При обнаружении не соответствия переданных данных и подписи покупка не будет создана. Для включения режима необходимо в настройках протокола IntellectMoney напротив поля «Требовать Hash» поставить галку и сохранить параметры протокола. Подпись формируется "склеиванием" значений полей в одну строку с использованием разделителя "::".
1. Номер сайта интернет-магазина (eshopId);
2. Номер покупки интернет-магазина (orderId);
3. Описание покупки (serviceName);
4. Сумма платежа (recipientAmount);
5. Валюта платежа (recipientCurrency);
6. Секретный ключ (secretKey); 

Пример

  1. eshopId= 17354
  2. orderId=1
  3. serviceName=покупка книги Хочу все знать
  4. recipientAmount=10,10
  5. recipientCurrency=RUB
  6. secretKey=test 


Строка для подписи: 17354::1::покупка книги Хочу все знать::10,10::RUB::test
Подписываемая строка символов должна быть в кодировке win1251. Подпись для примера 4590a539674c6b74d3032e004d1f8192

4.4.2 Проверка данных формы запроса для операций по расписанию

Для исключения случая подмены передаваемых магазином данных, магазин может подписать их. В таком случае ИМ будет проверять полученные данные согласно подписи. При обнаружении не соответствия переданных данных и подписи покупка не будет создана. Для включения режима необходимо в настройках протокола IntellectMoney напротив поля «Требовать Hash» поставить галку и сохранить параметры протокола. Подпись формируется "склеиванием" значений полей в одну строку с использованием разделителя "::".
1. Номер сайта интернет-магазина (eshopId);
2. Номер покупки интернет-магазина (orderId);
3. Описание покупки (serviceName);
4. Сумма платежа (recipientAmount);
5. Валюта платежа (recipientCurrency);
6. Секретный ключ (secretKey); 

Пример

  1. eshopId= 17354
  2. orderId=1
  3. serviceName=покупка книги Хочу все знать
  4. recipientAmount=10,10
  5. recipientCurrency=RUB
  6. recurringType=Activate
  7. secretKey=test


Строка для подписи: 17354::1::покупка книги Хочу все знать::10,10::RUB::Activate::test
Подписываемая строка символов должна быть в кодировке win1251. Подпись для примера 139de04be8c37061f99218353f4e13e0

4.5 Правила формирования чека для онлайн кассы (merchantReceipt)

Данные для формирования чека в онлайн кассе. Представляет собой JSON - строку. Для корректного отображения названия товара в чеке, параметр text передавать в кодировке UTF-8.Корректно сформировать JSON-строку из массива данных можно функцией  языка программирования PHP json_encode. Проверить правильность составления JSON-строки можно воспользовавшись функцией языка программирования PHP json_decode.

Важно: Документы генерируются фискальным накопителем(ФН), данный факт накладывает на кодировку передаваемых строк, обмен сообщениями по http с кассой осуществляется в кодировке UTF-8, но при записи в ФН строки передаются в кодировке CP866, которая поддерживает меньший набор символов чем UTF-8, например: в CP866 отсутствуют символы «» и в ФН они не будут переданы - вместо строки "Сок «Груша»" в документе будет "Сок Груша". Экранирование символов возможно через обратный слэш "\" или функцией addslashes в PHP.


{
"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":"Спички"
					}
					],
	}
} 

Название

Элемент

Описание

Валидация суммыskipAmountCheck

Отключить встроенную проверку соответствия сумм позиций чека сумме счета. По умолчанию, если параметр не передан - 0

Может принимать значения 0 или 1

Ваш номер ИНН.innИндивидуальный Номер Налогоплательщика, полученный в Федеральной налоговой службе
Название группы.group

По умолчанию "Main". Для того что бы выставить в другую группу, нужно создать новую группу в Orange Data.

Если передать группу, которой не существует, Orange Data вернет ошибку.

Содержимое документаcontentНаполнение данного поля смотрите в Таблице content.

Таблица content

Название

Описание

Включает в себя

Тип документаtype

Нужно передать число, согласно действию:

  1. Приход
  2. Возврат прихода
  3. Расход
  4. Возврат расхода
Данные покупателяcustomerContact

Телефон или Email - покупателя

Формат телефона: +ХХХХХХХХХХ

Список позиций в чекеpositions

Список товаров, за которые производится оплата. Наполнение данного поля смотрите в таблице positions.

Таблица positions

Название

Обязательное

Описание

quantityДа

Количество товара.

Десятичное число с точностью до 3 символов после точки.

priceДа

Цена товара с учётом всех скидок и наценок.

Десятичное число с точностью до двух знаков после точки.

taxДа

Ставка НДС. Нужно передать число от 1 до 6:

1 – ставка НДС 18%

2 – ставка НДС 10%

3 – ставка НДС расч. 18/118

4 – ставка НДС расч. 10/110

5 – ставка НДС 0%

6 – НДС не облагается

textДа

Описание позиции в чеке (товара).

Строка до 128 байтов.

paymentSubjectType

Нет

Предмет расчета. Нужно передать число от 1 до 13:

Товар = 1,
Подакцизный товар = 2,
Работа = 3,
Услуга = 4,
Ставка азартной игры = 5,
Выигрыш азартной игры = 6,
Лотерейный билет = 7,
Выигрыш лотереи = 8,
Предоставление РИД = 9,
Платёж = 10,
Агентское вознаграждение = 11,
Составной предмет расчета = 12,
Иной предмет расчета = 13

paymentMethodTypeНет

Способ расчета. Нужно передать число от 1 до 7:

Предоплата 100% = 1,
Частичная предоплата = 2,
Аванс = 3,
Полный расчёт = 4,
Частичный расчёт и кредит = 5,
Передача в кредит = 6,
Оплата кредита = 7

<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);
}
ВопросОтвет
В чеке выводится нечитаемое назначение платежаПараметр merchantReceipt следует передавать в кодировке UTF-8