I. Введение

Универсальная платежная платформа МОБИ.Деньги предоставляет Предприятиям возможность автоматического приeма платежей за предоставленные товары/услуги при помощи программного интерфейса  ShopAPI. При проведении полного цикла платежа Система взаимодействует с Предприятием для достижения согласованного решения о логике и результате прохождения платежа. Взаимодействие осуществляется по SOAP поверх HTTPS с клиентской авторизацией (авторизация сторон осуществляется на основе SSL-сертификатов).

II. Основные понятия

Оператор — оператор подвижной связи, заключивший договор с Банком «Об оказании информационных услуг».
Система — универсальная платежная платформа МОБИ.Деньги — комплекс технических, программных и других средств и персонала, обеспечивающий информационную поддержку участникам расчетов. Система обслуживается ООО НКО «МОБИ.Деньги» при взаимодействии с сетью подвижной связи Оператора.
Банк — кредитная организация, осуществляющая расчеты с организациями торговли (услуг) по проводимым операциям, и (или) выдающая наличные денежные средства клиентам.
Предприятие — юридическое лицо или предприниматель без образования юридического лица, оказывающий услуги и продающий товары физическим лицам — Клиентам.
Клиент — физическое лицо, принявшее Правила пользования Системой, условия банковского обслуживания эмитента и получившее право совершать платежные операции.
Правила пользования Системой — описание условий обмена информацией в электронном виде с помощью абонентского номера (кода идентификации) согласно технологическим процедурам и требованиям безопасности Системы.
Заказ — предложение на поставку товаров, выполнение работ или оказание услуг с указанием сроков, объемов, количества, ассортимента, качества и других необходимых данных.

III. Порядок информационного взаимодействия

Информационное взаимодействие осуществляется в два этапа:

• проведение платежа (см. 3.1);
• расчет с Предприятием (см. 3.2).

3.1 Проведение платежа

1. Клиент направляет Системе заказ на совершение покупки, указывая в запросе параметры товара. О способах инициации заказа см. пункт  Дополнительная информация
2. Система отправляет Предприятию запрос контракта на оплату товара, используя метод  PaymentContract . В качестве параметров метода передаются параметры товара, указанные Клиентом при заказе, и служебные параметры.
3. Предприятие формирует контракт и возвращает его Системе, контракт содержит описание товара, его стоимость и срок действия контракта. Контракт является документом в электронной форме, описывающим условия сделки между Клиентом и Предприятием. Обязательными условиями контракта являются:
   a) указание суммы и описание товара/услуги;
   b) обязанность Предприятия предоставить Клиенту оплаченную по контракту товар/услугу.
4. Система проводит авторизацию платежа на сумму, указанную в контракте. При этом у Предприятия возникают обязательства в отношении Клиента предоставить товар/услугу, а у Банка — выполнить денежный перевод в пользу Предприятия за счет средств Клиента.
5. Система отправляет запрос Предприятию предоставить Клиенту оплаченный товар, используя метод  PaymentAuthorization . Набор параметров функции составляет электронный документ, содержащий обязательства Банка по переводу денежных средств в пользу Предприятия, а так же предъявляемые Клиентом к Предприятию требования по выполнению контракта.
6. Предприятие предоставляет оплаченный товар/услугу.
7. Система сообщает Клиенту об успешно завершенной операции и передаёт Клиенту товар/услугу.

Примечание:

• запросы от Системы по разным платежам могут поступать параллельно. Запросы по одному платежу идут последовательно;
• в случае задержки ответа на запрос  PaymentAuthorization  вызывается  процедура принудительного завершения процесса платежа.

3.2 Расчет с Предприятием

Расчет с Предприятием происходит приблизительно один раз в неделю. В дальнейшем планируется производить расчет с Предприятием чаще.

В ходе проведения данной процедуры Оператор формирует реестр зачислений и подготавливает денежные средства для перевода. Когда все собранные данные и средства готовы, Оператор отправляет их в Банк. Обработав информацию, Банк сначала отправляет денежные средства, а затем реестры зачислений Предприятию.

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

3.3 Возврат денежных средств

На данном этапе работы Платежной платформы возврат денежных средств осуществляется внесистемным способом, по следующей схеме:

1. (Предусловие) Клиент оплатил товар или услугу Предприятия. Магазин не предоставил оплаченный товар или услугу.
2. Клиент информирует Систему о не предоставлении Предприятием оплаченного товара в должном объеме.
3. Система информирует Предприятие о поступившей претензии.
4. Система выполняет возврат денег клиенту на счет, с которого был выполнен платеж, по заявлянию на возврат от Предприятия.

IV. Требования информационного обмена

Настоящий Документ определяет действия и обязанности Предприятия по электронному документообороту в Платёжной платформе МОБИ.Деньги. Обмен информацией осуществляется путем пересылки электронных документов в формате и по каналам, определенным настоящим Документом.

4.1 Требования к Предприятию

Интерфейс Предприятия реализуется в виде SOAP-сервера и поддерживает функции ShopAPI (см.  shop.wsdl).
Прием и передача данных осуществляется в кодировке UTF-8.
Веб-сервер, на котором установлен интерфейс Предприятия, должен принимать запросы от Системы только по HTTPS с клиентской авторизацией.
Обмен информацией ведется в режиме запрос-ответ, при этом задержка ответа не должна превышать 60 секунд, в противном случае Система может разорвать соединение по таймауту.
Если предполагаемое количество платежей ожидается достаточно интенсивным (более 2 платежей в секунду), желательно, чтобы интерфейс спокойно переносил более чем 10 одновременных соединений в многопоточном режиме.

4.2 Требование к протоколу

Интерфейс ShopAPI удовлетворяет исключительно спецификации протокола SOAP 1.1.

V. Программный интерфейс Предприятия (ShopAPI)

Для взаимодействия с Системой Предприятию на своей стороне необходимо реализовать следующие методы:

1. PaymentContract - запрос к Предприятию на выдачу контракта для оплаты товара;
2. PaymentAuthorization - запрос к Предприятию на выдачу оплаченного товара/услуги по контракту;

shop.wsdl - WSDL-описание программного интерфейса Предприятия.

Доступ к сервису осуществляется по SOAP поверх HTTPS с клиентской авторизацией (авторизация сторон осуществляется на основе SSL-сертификатов).

5.1 PaymentContract

запрос к Предприятию на выдачу контракта для оплаты товара. Время ожидания ответа на данный запрос — 60 с. Обязательные параметры выделены жирным.

Входные параметры

Выходные параметры

Возвращаемые ошибки

5.2 PaymentAuthorization

запрос к Предприятию на выдачу оплаченного товара/услуги по контракту

Эта функция вызывается Системой после того, как средства перечислены со счёта Клиента на счёт Предприятия.
Может вызываться несколько раз при повторах. Предприятие должно само отслеживать повторы по  PaymentID или  PayeeRegData/ PayeeRegDataEx или использовать параметр IsRepeat.
Время ожидания Системой ответа Предприятия на PaymentAuthorization — 60c. Обязательные параметры выделены жирным.

Входные параметры

Выходные параметры

Возвращаемые ошибки

VI. Примеры

Указанные коды являются примерами и могут быть изменены при согласовании с сотрудником службы поддержки. После реализации Предприятие должно следить за их исполнением.

6.1 Форма оплаты

используется для инициации платежа с сайта Предприятия
Пример:

• Если тип Предприятия "Пополнение лицевого счёта", то
  [lt]form method="post" action="https://pay.mobi-money.ru/[lt]Аббревиатура_товара[gt]"[gt]
  Номер счёта: [lt]input type="text" name="account" value=""[gt][lt]br/[gt]
  
  Сумма: [lt]input type="text" name="sum" value="100"[gt][lt]br/[gt]
  [lt]input type="submit" value="Оплатить"/[gt]
  [lt]/form[gt]

• Если тип Предприятия "Интернет-магазин", то
  [lt]form method="post" action="https://pay.mobi-money.ru/[lt]Аббревиатура_товара[gt]"[gt]
  Номер заказа: [lt]input type="text" name="orderID" value=""[gt][lt]br/[gt]
  [lt]input type="submit" value="Оплатить"/[gt]
  [lt]/form[gt]

Подробнее о форме оплаты см. страницу  Форма оплаты.

6.2 Контракт на платёж

Под контрактом на платёж подразумевается обязательство Предприятия выдать описанный в контракте товар или услугу, если Клиент его оплатит.
При инициации платежа, Система вызывает функцию интерфейса Предприятия  PaymentContract , в которую передаёт идентификатор платежа и данные с формы оплаты, а в ответ получает сумму, краткое и полное описание платежа в XML-формате вида:

• Если тип Предприятия "Пополнение лицевого счёта", то
  [lt]?xml version="1.0" encoding="utf-8"?[gt]
  [lt]contract[gt]
  [lt]param id="sum" label="Сумма, к зачислению на лицевой счёт"[gt]100[lt]/param[gt]
  [lt]param id="account" label="Номер лицевого счёта"[gt]234523453453[lt]/param[gt]
  [lt]/contract[gt]

• Если тип Предприятия "Интернет-магазин", то
  [lt]?xml version="1.0" encoding="utf-8"?[gt]
  [lt]contract[gt]
  [lt]param id="orderID" label="Номер заказа"[gt]234523453453[lt]/param[gt]
  [lt]param id="comment" label="Описание заказа"[gt]Описание заказа[lt]/param[gt]
  [lt]/contract[gt]

6.3 Описание оплаченного товара или услуги

Если платёж успешно принят, то Предприятие должно в качестве выходного параметра  ReplyResource функции  PaymentAuthorization выдать описание товара или услуги в XML-формате вида:

• Если тип Предприятия "Пополнение лицевого счёта", то
  [lt]?xml version="1.0" encoding="utf-8"?[gt]
  [lt]success[gt]
  [lt]param id="sum" label="Лицевой счёт пополнен на сумму"[gt]100[lt]/param[gt]
  [lt]param id="account" label="Номер лицевого счёта"[gt]234523453453[lt]/param[gt]
  [lt]/success[gt]
• Если тип Предприятия "Интернет-магазин", то
  [lt]?xml version="1.0" encoding="utf-8"?[gt]
  [lt]success[gt]
  [lt]param id="orderID" label="Номер заказа"[gt]234523453453[lt]/param[gt]
  [lt]param id="comment" label="Описание"[gt]Описание оплаченного товара[lt]/param[gt]
  [lt]/success[gt]

6.4 Детализация ошибки Предприятия (error)

Если Предприятие выдало ошибку в виде SOAP-exception, то имеется возможность в тэге SoapFault\detail указать подробности возникновения ошибки в формате XML:

6.5 Учётная информация Предприятия по платежу

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

PayeeRegData - задаётся только в функции  PaymentContract и передаётся всем остальным функциям Предприятия, может быть перезаписан.

PayeeRegDataEx - задаётся в функции  PaymentContract, передаётся и может изменяться всеми остальными функциями Предприятия (зарезервирован).

ShopParams - учётные параметры Предприятия, задаются при конфигурации Предприятия на портале. Передаются Предприятию при вызове всех функций  ShopAPI.

Формат - URL-кодированная строка вида Param1=Value1&...&ParamN=ValueN.

Способ применения: в учётных параметрах Предприятия можно хранить параметры настройки Предприятия, например пароли и пр.

VII.  Дополнительная информация

7.1 Способы инициации платежа

• Платеж может быть инициирован  Клиентом следующими способами:

1. при помощи формы оплаты с сайта Предприятия;
2. при помощи формы оплаты c сайта Системы;
3. при помощи SMS с мобильного телефона.

• Платеж может быть инициирован  Предприятием. Предоставление данной возможности для определенных типов Предприятий оговаривается с куратором.

• Платеж может быть инициирован  Cистемой для определенных типов Предприятий по запросу Предприятия.

7.2 Международный стандарт для представления даты и времени в ISO 8601

Пример 1994-11-05T08:15:30+03:00 соответствует 5 ноября 1994, 8:15:30, Московское время.

Более подробно смотрите:

• http://www.w3.org/TR/NOTE-datetime
• http://en.wikipedia.org/wiki/ISO_Time

7.3  Процедура принудительного завершения процесса платежа

Данная процедура приводится в действие службой технической поддержки Системы в случае превышения временных границ ожидания ответа от Предприятия на первый отправленный запрос  PaymentAuthorization .
При этом:

• Система, не дождавшись ответа Предприятия на запрос, уведомляет Клиента об успешно завершенной операции;
• Предприятие, получив запрос  PaymentAuthorization, обязуется предоставить Клиенту товар/услугу;
• Система повторно - вплоть до получения ответа - отправляет запрос PaymentAuthorization Предприятию;

Получение ответа от Предприятия необходимо для корректного завершения процесса прохождения платежа.

7.4  Описание параметров функций ShopAPI с примерами

PaymentID - идентификатор платежа, генерируется Cистемойю Целое число, до 20 знаков.

Пример 286797792696461001

Account - номер учётной записи Предприятия. Выдается Системой, внутренний цифровой идентификатор Предприятия, номер счета внутри Системы. Целое число, до 33 знаков.

Пример 41013306094

Currency - код валюты. Внутри системы все операции производятся в российских рублях. Код различается для демо-режима (10643) и боевого режима (643). Целое число.

Пример 643

PaymentTime - время создания платежа. Генерируется Системой. Строка, время в формате ISO 8601.
AuthorizationTime - время авторизации платежа. Генерируется Системой. Строка, время в формате ISO 8601.

Пример 2009-02-01T10:03:12+00:00

PayerAddress - ip-адрес, с которого Система осуществляет запрос к Предприятию. Генерируется Системой. Строка, содержащая ip-адрес.

Пример 84.204.97.145

ShopParams - параметры Предприятия. Параметры, используемые для конфигурации Предприятия на стороне Системы. Передаются Системой Предприятию при совершении платежных операций. Как пример применения : если один скрипт на стороне предприятия осуществляет прием платежей за несколько товаров, настройки товаров можно вынести в ShopParams. В текущем примере предприятию передается путь к xml-описанию определенного товара. URL-encoded строка.

Пример pathToGoodXML=http%3A%2F%2Fshop.demo.mobi-money.ru%2FShopWindow%2Farticles%2Finterzet.xml

UserParams - параметры товара. Реквизиты платежа, в примере это account - номер лицевого счета и sum - сумма платежа. Система также присылает телефон плательщика в параметре payerPhone. URL-encoded строка.

Пример account=14979&sum=103.09&payerPhone=9062276078

Demo - признак деморежима. Устанавливается Системой при тестировании на демо-стенде. true/false.

Пример true

Sum - сумма платежа. Выдается Предприятием в ответ на запрос контракта. Число, разделитель целой и дробной части ".", дробная часть максимум имеет 2 знака.

Пример 103.09

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

Пример a:4: {s:7:"account";s:5:"14979";s:3:"sum";s:6:"103.09";s:14:"payLinkVersion";s:10:"1226304943";s:10:"payerPhone";s:10:"9062276078";}

Contract - xml-описание контракта. Выдается Предприятием в ответ на запрос контракта.

Пример [lt]?xml version="1.0" encoding="utf-8"?[gt] [lt]contract[gt] [lt]param id="account" ref="account" label="Номер лицевого счета"[gt]14979[lt]/param[gt] [lt]param id="sum" ref="sum" label="Сумма"[gt]103.09[lt]/param[gt] [lt]/contract[gt]

PayeeRegDataEx - учётные данные Предприятия о платеже. В отличие от PayeeRegData может быть изменен при вызовах PaymentAuthorization. При первом вызове PaymentAuthorization всегда приходит пустым. Строка.

IsRepeat - признак повторной авторизации платежа. При первом запросе PaymentAuthorization равен  false, при последующих равен  true.

ReplyResource - XML-описание оплаченного товара/услуги. В случае ошибки при авторизации платежа содержит ее описание

Пример [lt]?xml version="1.0" encoding="utf-8"?[gt] [lt]success[gt] [lt]param id="account" ref="account" label="Номер лицевого счета"[gt]14979[lt]/param[gt] [lt]param id="sum" ref="sum" label="Сумма"[gt]103.09[lt]/param[gt] [lt]/success[gt]

ReplyResourceIsFailure - если произошла ошибка при авторизации платежа должен быть равен  false. Устанавливается Предприятием.