Versions Compared
Key
- This line was added.
- This line was removed.
- Formatting was changed.
Описание интерфейса приема платежей
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, интернет-магазина и пользователя (покупателя) происходит по следующей схеме:
- Покупатель выбирает товар на веб-сайте интернет-магазина;
- Интернет-магазин создает заказ (покупку), формирует и выводит покупателю Форму запроса платежа для отправки заказа на оплату в IntellectMoney.
- Пользователь (покупатель) переходит на веб-сайт IntellectMoney, выбирает способ оплаты (либо из заданных параметром preference в Форме запроса платежа (в случае если он задан), либо из всех возможных (если не задан), и вводит идентификационные данные.
- Система IntellectMoney создает счет к оплате (СКО) на основе данных полученных из Формы запроса платежа .
- Информация о созданном СКО выводится покупателю.
- Система IntellectMoney отправляет уведомление интернет-магазину о создании СКО через Форму оповещения о платеже с полем paymentStatus = 3 (создан СКО).
- Покупатель оплачивает покупку одним из доступных способов.
- Если при создании покупки интернет-магазин в Форме запроса платежа не указал (не передал) параметр holdMode, то далее выполнение продолжается с шага 10 немедленно зачисляя средства на счет интернет-магазина.
В противном случае (задан параметр holdMode) система IntellectMoney отправляет уведомление интернет-магазину о создании СКО через Форму оповещения о платеже с полем paymentStatus = 6 (необходимая сумма заблокирована на СКО, ожидается запрос на списание или разблокировку средств или истечение срока блокировки). - Интернет-магазин отправляет запрос системе IntellectMoney о действии с заблокированными средствами через Форму запроса зачисления или разблокировки средств с параметром action = Refund (для разблокировки средств (возврата пользователю), или ToPaid (для зачисления средств на счет интернет-магазина).
- В соответствии с запросом пришедшем на шаге 9 система IntellectMoney зачисляет средства на счет интернет-магазина, или аннулирует СКО и возвращает средства пользователю.
Если интернет-магазин не отправлял запрос в соответствии с шагом 9, то по истечении срока блокировки средств на СКО система IntelectMoney автоматически зачисляет средства на счет интернет-магазина, или возвращает средства пользователю, в зависимости от настроек магазина в личного кабинете. - Система 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. Перечень параметров протокола
Название параметра | Формат | Описание |
URL информирования о платеже (Result URL) | до 512 символов | URL (на веб-сайте интернет-магазина), на который система IntellectMoney посылает HTTP/S POST запросы о совершении платежа. Если интернет-магазин не определил этот URL, он не будет оповещаться системой о совершенных платежах. URL должен начинаться с префикса “http://” или “https://”. |
Секретный ключ (Secret Key) | до 32 символов | Строка символов, используемая для подписи данных передаваемых системой ИнтеллектМани магазину. Эта строка используется для повышения надежности идентификации высылаемого оповещения. Содержание строки известно только системе IntellectMoney и интернет-магазину! |
Высылать Secret Key на Result URL | Если используется защищенное соединение с магазином (https), то можно использовать "секретный ключ" в качестве удостоверения что данные отправлены от ИнтеллектМани. | |
BackURL | до 512 символов | Адрес, на который покупатель может возвратиться с платежной страницы, если нажать на ссылку "Вернуться в магазин" на странице оплаты. Максимальная длина - 512 символов. |
Режим отладки | Чекбокс | Рекомендуется включить на время разработки модуля, реализующего протокол. Позволяет разработчику получать информацию об ошибках в расширенном варианте, с предлагаемыми вариантами их решения. После переключения магазина в боевой режим, параметр отключить. |
3.2. Формы HTML
Для передачи информации между сайтом интернет-магазина и системой IntellectMoney используются HTML-формы:
Форма запроса платежа - генерируется веб-сайтом интернет-магазина для формирования запроса на создание (выставление) СКО (счета к оплате) для оплаты покупки в системе IntellectMoney. Передается через веб-браузер пользователя (покупателя).
Форма оповещения о платеже - генерируется системой IntellectMoney для оповещения интернет-магазина о создании или изменении статуса СКО. Оповещение передается без использования веб-браузера пользователя (покупателя) на веб-сайт интернет-магазина.
Форма запроса зачисления, или разблокировки средств - генерируется интернет-магазином для запроса разблокировки средств (возврата пользователю), или зачисления средств на счет интернет-магазина в системе IntellectMoney. Используется в случае, если при создании СКО была задана дата блокировки (холдирования) средств на СКО. Запрос передается без использования веб-браузера пользователя (покупателя) на веб-сайт IntellectMoney.
Anchor merchant-form merchant-form
merchant-form | |
merchant-form |
3.2.1. Форма запроса платежа
Эта форма передает запрос с веб-сайта интернет-магазина в систему IntellectMoney через веб-браузер пользователя (покупателя). Она должна иметь следующие атрибуты и поля:
Action - https://merchant.intellectmoney.ru/ru/
Method - POST, GET
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
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/ - Болгарский язык |
Extend_comment Label doc_Форма_запроса_платежа
Таблица 2.1 Поля формы запроса платежа
Название | Имя поля HTML формы | Обязательный | Описание | |||||||||
ID магазина | eshopId | Да | Номер сайта интернет-магазина, на который пользователь (покупатель) должен совершить платеж. Можно увидеть на странице https://www.intellectmoney.ru/ru/enter/ps_organization_shop/ в столбце "ID" | |||||||||
Внутренний номер покупки интернет-магазина | orderId | Да | В этом поле интернет-магазин задает номер покупки в соответствии со своей системой учета. Желательно использовать уникальный номер для каждого платежа, что позволит быстро получить относящуюся к нему информацию через систему IntellectMoney. Максимальная длина - 50 символов. | |||||||||
Назначение платежа | serviceName | Нет | Описание товара или услуги. Формируется интернет-магазином. Максимальная длина - 1024 символов. | |||||||||
Сумма платежа | recipientAmount | Да | Сумма платежа, которую Интернет-магазин желает получить от пользователя (покупателя). Сумма должна быть больше нуля, дробная часть отделяется точкой, два знака после точки. Максимальная длина - 10 цифр вместе с десятичными знаками. | |||||||||
Валюта платежа | recipientCurrency | Да | Валюта платежа. Может принимать значения:
Внимание: USD и EUR можно передавать только для платежей посредством банковской карты (preference=bankCard). Подробную информацию о подключении иностранных валют Вы можете получить у Вашего персонального менеджера.
| |||||||||
Имя Пользователя | userName | Нет | Полное имя пользователя (покупателя). Вводится самим пользователем (покупателем). Максимальная длина – 255 символов. | |||||||||
E-mail пользователя | user_email | Нет | Email пользователя (покупателя). Вводится самим покупателем. Максимальная длина – 255 символов. | |||||||||
Адрес удачного платежа | successUrl | Нет | Адрес, на который будет перенаправлен пользователь (покупатель) в случае успешной оплаты Максимальная длина - 512 символов. | |||||||||
Адрес возврата в интернет-магазин | backUrl | Нет | Адрес, на который будет перенаправлен пользователь (покупатель) в случае клика по ссылке "Вернуться в магазин" на странице оплаты. Максимальная длина - 512 символов. | |||||||||
Способы оплаты для пользователя – переход сразу на страницу ввода реквизитов | preference | Нет |
| |||||||||
Включение режима холдирования | holdMode | Нет | При оплате СКО, средства на счете пользователя не списываются, а “замораживаются“. Данный параметр может принимать три значения:
Данный параметр подробно описан в разделе Холдирование | |||||||||
Срок существования СКО | expireDate | Нет | Дата и время, по достижению, которых оплатить счёт в системе IntellectMoney станет не возможно. Счет переходит в статус "Отменён". Передавать в формате “yyyy-MM-dd HH:mm:ss”. Данный параметр подробно описан в разделе Холдирование | |||||||||
Срок холдирования денежных средств | holdTime | Нет | Время, через которое захолдированные (замороженные) денежные средства будут зачислены на счёт магазина или возвращены покупателю, измеряется в часах. Целое число от 0 до 119 часов. Данный параметр подробно описан в разделе Холдирование | |||||||||
Данные по чеку | merchantReceipt | Нет | Данные для формирования чека в онлайн кассе. Подробное описание смотрите в пункте 3.5 Правила формирования чека для онлайн кассы (merchantReceipt) Параметр является обязательным для магазинов с включенной онлайн-кассой | |||||||||
Компактный дизайн | frame | Нет | При передаче значения 1 платежная страница будет выведена в компактном дизайне | |||||||||
Дополнительные параметры интернет-магазина | Определяется интернет-магазином | Нет | Все поля формы, имеющие в названии префикса "UserField_N", "UserFieldName_N" (где N порядковый номер), обрабатываются системой IntellectMoney автоматически и передаются на сайт интернет-магазина. Максимальная длина всех дополнительных полей в сумме - 4000 символов. | |||||||||
Тип операции по расписанию | recurringType | Нет | Тип операции по расписанию, принимает значение:
Данной командой, банковская карта регистрируется в цепочке платежей и привязывается к счету, после того как счет будет оплачен. Параметр является обязательным для рекуррентых платежей (ребиллинга). | |||||||||
Подпись для преданных данных | hash | Нет | Контрольная подпись запроса, которая используется для проверки целостности полученной от магазина информации и однозначной идентификации отправителя. Алгоритм формирования описан в разделе "Проверка данных формы запроса". Важно: Для операций по расписанию алгоритм формирования подписи описан в разделе "Проверка данных формы запроса для операций по расписанию". Параметр является обязательным при включении параметра «Требовать HASH» в настройках магазина. |
Пример 1.
Multiexcerpt | |||||||||
---|---|---|---|---|---|---|---|---|---|
| |||||||||
|
Anchor | ||||
---|---|---|---|---|
|
3.2.2. Форма оповещения о платеже
При создании СКО и изменении его статуса система 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.
Пример корректного ответа обработчика магазина при успешном принятии уведомления о создании или изменении счета (частичная оплата счета, полная оплата счета и т.д.):
Code Block | ||
---|---|---|
| ||
<? echo "OK"; ?> |
Таблица 3. Поля формы оповещения о платеже.
Название | Имя поля HTML формы | Описание | |||||||||||||||
Номер сайта интернет-магазина | eshopId | Номер сайта интернет-магазина, на который Пользователь (Покупатель) совершает платеж. | |||||||||||||||
Номер покупки в системе IntellectMoney | paymentId | Номер покупки (СКО) в системе IntellectMoney | |||||||||||||||
Внутренний номер покупки в интернет-магазине | orderId | Номер покупки в соответствии с системой учета интернет-магазина, полученный системой с веб-сайта интернет-магазина. | |||||||||||||||
Номер счета магазина | eshopAccount | Номер счета интернет-магазина в системе IntellectMoney. На этот счет будут зачислены средства после оплаты покупки. | |||||||||||||||
Назначение платежа | serviceName | Назначение платежа в соответствии с системой учета Интернет-магазина, получаемое системой с веб-сайта Интернет-магазина. | |||||||||||||||
Исходная сумма платежа | recipientOriginalAmount | Исходная сумма платежа. Разделитель дробной части “.“, точность до копейки (2 знака после разделителя). Не изменяется в процессе оплаты. | |||||||||||||||
Сумма платежа | recipientAmount | Сумма, которую получает интернет-магазин. Разделитель дробной части “.“, точность до копейки (2 знака после разделителя). В процессе оплаты может быть изменена. | |||||||||||||||
Сумма возврата | refundAmount | Сумма, которая будет передана плательщику при возврате. Разделитель дробной части “.“, точность до копейки (2 знака после разделителя) Так как по одному СКО может быть несколько возвратов, то в данном параметре будет передана сумма по текущему возврату. | |||||||||||||||
Валюта платежа | recipientCurrency | Валюта платежа (RUB или TST) | |||||||||||||||
Статус покупки | paymentStatus | Статус платежа может иметь следующие значения:
| |||||||||||||||
Имя Пользователя | 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 | Отображает состояние операции по расписанию для данного платежа.
| |||||||||||||||
Исходный номер счета | sourceInvoiceId | Исходный номер счета (является "paymentId" для счета рекуррентных платежей). Номер исходного СКО. |
Пример 2.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<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> |
Anchor actionRefund actionRefund
3.2.3. Форма запроса зачисления или разблокировки средств
actionRefund | |
actionRefund |
Эта форма передается интернет-магазином без использования веб-браузера пользователя (покупателя) на веб-сайт 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 подключена онлайн-касса. В случае частичного уменьшения суммы СКО нужно передавать новый чек (т.е. позиции товаров, по которым будет производиться оплата), в случае частичного возврата по СКО нужно передавать чек возврата (т.е. позиции товаров, по которым совершается возврат). Подробное описание смотрите в пункте 3.5 Формирование merchantReceipt |
Подпись для преданных данных | hash | Нет | Контрольная подпись запроса, которая используется для проверки целостности полученной от магазина информации и однозначной идентификации отправителя. Алгоритм формирования описан в разделе "Контрольная подпись данных о платеже". Требуется только при включении параметра «Требовать HASH» в настройках магазина. |
Секретный ключ | secretKey | В случае если не используется подпись (hash). |
Expand | |||||
---|---|---|---|---|---|
| |||||
|
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<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> |
Случай 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: Был выставлен обычный СКО на 30 рублей. Клиент полностью оплатил СКО на сумму 30.00 рублей. СКО находиться в состоянии “полностью оплачен“ и средства были зачислены на счет магазина. Магазин отправляет запрос с параметрами action=Refund и operationAmount=10.00. По СКО происходит возврат средств плательщику на сумму 10.00 рублей.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<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
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
Для реализации данного примера Вам потребуется пакет libcurl.
|
3.3. Проверка информации о платеже
При выполнении платежа система IntellectMoney высылает оповещение о платеже через "Форму оповещения о платеже" на "URL информирования о платеже", указанный Интернет-магазином.
Мы рекомендуем вам проверить данные, полученные через "Форму оповещения о платеже":
- Проверить, действительно ли данные переданы от системы IntellectMoney (Проверка источника данных) по IP адресу.
- Проверить, не исказились ли данные в процессе передачи (Проверка целостности данных)
- Проверить сумму платежа
- Проверить номер сайта интернет-магазина
3.3.1. Проверка источника данных
Как указывалось выше, значение параметра "Секретный ключ" должно быть известно только системе IntellectMoney и Интернет-магазину. Исходя из этого, Секретный ключ может использоваться для аутентификации источника, приславшего данные о платеже. Интернет-магазин может провести аутентификацию несколькими методами в зависимости от того, включен ли функционал "Отправлять секретный ключ".
Запросы к магазину от системы ИнтеллектМани могут приходить только с подсети 139.45.224.0/24. Пример проверки принадлежности IP к подсети:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
if (!preg_match("/139.45.224.\d{0,255}/", $_SERVER['REMOTE_ADDR'])){ return "ERROR! IP MISMATCH!"; die; } |
Для передачи данных желательно использовать протокол HTTPS.
Anchor | ||||
---|---|---|---|---|
|
3.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
Полученный хэш: 4c6498fdd639ccefd3bb1aa0e4d95aa8
При реализации проверки подписи рекомендуется сверить полученный результат с приведенным выше примером.
Для "Формы запроса зачисления или разблокировки средств" склеиваются следующие поля в следующем порядке:
- Номер сайта интернет-магазина (eshopId);
- Номер покупки интернет-магазина (orderId);
- Запрашиваемое действие (action);
- Секретный ключ (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).
3.3.2.2. Проверка контрольной подписи
Проверка контрольной подписи на сайте интернет-магазина по следующему алгоритму:
- Сформируйте строку путем "склеивания" значений параметров, полученных через "Форму оповещения о платеже", в том же порядке, что и при формировании контрольной подписи разделяя их "::" в системе IntellectMoney (см. выше). Помните, что при формировании подписи используется Секретный ключ.
- Вычислите MD5 полученной строки.
- Сравните полученное значение с значением параметра "hash", полученного через "Форму оповещения о платеже". Если сформированная подпись совпадает с полученной через "Форму оповещения о платеже", данные не изменены, и источник данных действительно система IntellectMoney.
3.3.2.3. Проверка суммы и валюты платежа
Несмотря на то, что пользователь (покупатель) не может изменить сумму платежа, интернет-магазину рекомендуется контролировать информацию о сумме и валюте платежа, передаваемую через параметры "recipientAmount" и "recipientCurrency".
3.3.2.4 Проверка номера сайта (ID) интернет-магазина
Несмотря на то, что пользователь (покупатель) не может изменить номер сайта, на который совершается платеж, интернет-магазину рекомендуется контролировать информацию о номере сайта, которая передается через параметр "eshopId", особенно при использовании нескольких сайтов для приема платежей через систему IntellectMoney.
Anchor | ||||
---|---|---|---|---|
|
3.4.1 Проверка данных формы запроса
Для исключения случая подмены передаваемых магазином данных, магазин может подписать их. В таком случае ИМ будет проверять полученные данные согласно подписи. При обнаружении не соответствия переданных данных и подписи покупка не будет создана. Для включения режима необходимо в настройках протокола IntellectMoney напротив поля «Требовать Hash» поставить галку и сохранить параметры протокола. Подпись формируется "склеиванием" значений полей в одну строку с использованием разделителя "::".
1. Номер сайта интернет-магазина (eshopId);
2. Номер покупки интернет-магазина (orderId);
3. Описание покупки (serviceName);
4. Сумма платежа (recipientAmount);
5. Валюта платежа (recipientCurrency);
6. Секретный ключ (secretKey);
Пример
- eshopId = 17354
- orderId = 1
- serviceName = покупка книги Хочу все знать
- recipientAmount = 10.10
- recipientCurrency = RUB
- secretKey = test
Строка для подписи: "17354::1::покупка книги Хочу все знать::10.10::RUB::test".
Подпись для примера 139de04be8c37061f99218353f4e13e0
Правильность формирования подписи можно проверить в калькуляторе hash-подписей
Anchor | ||||
---|---|---|---|---|
|
3.4.2 Проверка данных формы запроса для операции по расписанию
Для исключения случая подмены передаваемых магазином данных, магазин может подписать их. В таком случае IntellectMoney будет проверять полученные данные согласно подписи. При обнаружении не соответствия переданных данных и подписи покупка не будет создана. Для включения режима необходимо в настройках протокола IntellectMoney напротив поля «Требовать Hash» поставить галку и сохранить параметры протокола. Подпись формируется "склеиванием" значений полей в одну строку с использованием разделителя "::".
1. Номер сайта интернет-магазина (eshopId);
2. Номер покупки интернет-магазина (orderId);
3. Описание покупки (serviceName);
4. Сумма платежа (recipientAmount);
5. Валюта платежа (recipientCurrency);
6. Тип операции по расписанию (recurringType);
7. Секретный ключ (secretKey);
Пример
- eshopId = 17354
- orderId = 1
- serviceName = покупка книги Хочу все знать
- recipientAmount = 10.10
- recipientCurrency = RUB
- recurringType = Activate
- secretKey = test
Строка для подписи: "17354::1::покупка книги Хочу все знать::10.10::RUB::Activate::test".
Подпись для примера 5f87ff3da5adeaeb42f8133653725a02
Anchor | ||||
---|---|---|---|---|
|
3.5 Правила формирования чека для онлайн кассы (merchantReceipt)
Multiexcerpt | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Данные для формирования чека в онлайн кассе. Представляет собой JSON - строку. Для корректного отображения названия товара в чеке, параметр text передавать в кодировке UTF-8.Корректно сформировать JSON-строку из массива данных можно функцией языка программирования PHP json_encode. Проверить правильность составления JSON-строки можно воспользовавшись функцией языка программирования PHP json_decode. Важно: Документы генерируются фискальным накопителем(ФН), данный факт накладывает на кодировку передаваемых строк, обмен сообщениями по http с кассой осуществляется в кодировке UTF-8, но при записи в ФН строки передаются в кодировке CP866, которая поддерживает меньший набор символов чем UTF-8, например: в CP866 отсутствуют символы «» и в ФН они не будут переданы - вместо строки "Сок «Груша»" в документе будет "Сок Груша". Экранирование символов возможно через обратный слэш "\" или функцией addslashes в PHP.
Таблица content
Таблица positions
таблица checkClose
таблица payments
|
3.6 Передача дополнительных параметров: userField_N, userFieldName_N и остальные
Multiexcerpt | ||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||
Дополнительные параметры. Дополнительные параметры нужны для передачи дополнительной информации или данных на ResultURL и страницу в личном кабинете.
Подробнее о значениях:
О том как посмотреть дополнительные поля написано в статье Просмотр дополнительных параметров в личном кабинете |
Алгоритм формирования описан в разделе
Table of Contents |
---|