Интерфейс MONETA.Assistant предоставляет прикладной программный интерфейс для оплаты товаров и услуг при помощи различных платежных систем. Таким образом, online-магазин реализует поддержку только интерфейса MONETA.Assistant, в то время как покупатели могут производить оплату с любой электронной платежной системы, которую поддерживает «MONETA.RU».

При помощи интерфейса MONETA.Assistant можно связать свою внутреннюю систему приема, хранения и обработки заказов с системой «MONETA.RU». На основании сформированного заказа, магазин будет создавать запрос на оплату к системе «MONETA.RU» и принимать отчет о проведенной оплате с сохранением своих внутренних параметров (например, номер заказа в системе или дополнительные информационные поля).

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

Описание процесса оплаты

Оплата без открытия счета в «MONETA.RU»:

1. Пользователь выбирает товар.
2. Магазин формирует заказ, при необходимости регистрирует в своей системе реквизиты заказа.
3. На странице интерфейса MONETA.Assistant Пользователь выбирает способ оплаты.
4. Система «MONETA.RU» подготавливает форму оплаты.
5. Пользователь подтверждает оплату выбранным способом.
6. Внешняя платежная система уведомляет систему «MONETA.RU» об оплате.
7. Система «MONETA.RU» отправляет магазину отчет о проведенной операции.
8. Система «MONETA.RU» сообщает о результате оплаты и предлагает Пользователю вернуться на сайт магазина.

Диаграмма процедуры оплаты товара без открытия Пользователем счета в системе «MONETA.RU» с использованием интерфейса MONETA.Assistant:

Demo-площадка

Для того, чтобы попробовать, как работает MONETA.Assistant, можно создать личный кабинет на demo площадке.

Вы можете использовать demo площадку Moneta.Ru https://demo.moneta.ru, чтобы протестировать работу MONETA.Assistant.

Регистрация на demo площадке

Для того, чтобы начать работу на demo площадке Вам следует создать два личных кабинета: личный кабинет магазина, который может принимать платежи и личный кабинет пользователя, который может платить в магазин. Для каждого личного кабинета используйте разные e-mail адреса.

1. Создайте личный кабинет магазина на demo площадке. Для этого перейдите по ссылке: https://demo.moneta.ru/backoffice/auth/register
2. Создайте личный кабинет пользователя на demo площадке. Для этого перейдите по ссылке: https://demo.moneta.ru/locale.htm?moneta.locale=ru&redirect=/register.htm
3. Свяжитесь со службой поддержки PayAnyWay (business@support.payanyway.ru), чтобы завершить регистрацию личного кабинета магазина, а также получить виртуальные деньги в личном кабинете пользователя.

4. После того как служба поддержки подтвердит регистрацию, создайте “расширенный” счет в личном кабинете магазина. Для этого выполните следующие шаги:
   1. Откройте https://demo.moneta.ru и зайдите в личный кабинет магазина.
   2. Перейдите Мой счет > Управление счетами.
   3. В разделе Расширенные счета, нажмите Добавить счет.
   4. Заполните форму и нажмите Сохранить.

Настройки счёта магазина

В разделе управления счетами (блок Счета в левой части обзорной страницы, ссылка Мой счет > Управление счетами) уполномоченные представители магазина могут настроить параметры взаимодействия учетной системы магазина и системы «МОНЕТА.РУ».

Тестовый режим

Признак тестового режима, в котором движения средств по операции не происходит, но обеспечивается информационный обмен.

Внимание! Тестовый режим настраивается только данным флагом. Параметр MNT_TEST_MODE устарел и не влияет на включение / отключение тестового режима.

Список платежных систем

Список (разделенный запятыми) идентификаторов платежных систем, которые необходимо показывать пользователю в MONETA.Assistant. Например, 1015,1017 - пользователю в MONETA.Assistant будут показаны только платежные системы МОНЕТА.РУ и WebMoney. Если список пустой, то будут показаны все доступные системы. Также это значение можно передать в запросе с помощью параметра paymentSystem.limitIds.

Check URL

Адрес обработчика в системе учета магазина для проверочных запросов. Если в свойствах счета указан Check URL, то магазин будет получать проверочные запросы. Дополнительная информация: Проверочные запросы (Check URL).

Pay URL

Адрес обработчика в системе учета магазина для уведомлений о проведенном платеже. Дополнительная информация: Уведомление о проведенной оплате (Pay URL).

HTTP Method

GET или POST метод отправки параметров для Check URL и Pay URL запросов.

Код проверки целостности данных

Код, обеспечивающий идентификацию отправителя и возможность проверки целостности данных, известный только системе «МОНЕТА.РУ» и учетной системе магазина. Устанавливается магазином при настройке счёта.

Подпись формы оплаты обязательна

Признак, который обязывает передавать параметр MNT_SIGNATURE в запросе на оплату. Если в настройках счета выставлен этот флаг, но параметр MNT_SIGNATURE в запросе на оплату не указан, то MONETA.Assistant завершится с ошибкой.

Внимание! Если в параметрах на оплату не указывается параметр MNT_TRANSACTION_ID, то этот флаг выставлять не следует. Запросы с параметром MNT_SIGNATURE при отсутствии параметра MNT_TRANSACTION_ID будут неверны.

Можно переопределять настройки в URL

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

Success URL

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

Примечание: MONETA.Assistant добавляет параметр MNT_TRANSACTION_ID в указанную ссылку, чтобы магазин смог определить внутренний идентификатор заказа.

Fail URL

URL страницы магазина, куда должен попасть покупатель после отмененной оплаты. Отчет об оплате в этом случае магазину не отсылается.

Примечание: MONETA.Assistant добавляет параметр MNT_TRANSACTION_ID в указанную ссылку, чтобы магазин смог определить внутренний идентификатор заказа.

InProgress URL

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

Примечание: MONETA.Assistant добавляет параметр MNT_TRANSACTION_ID в указанную ссылку, чтобы магазин смог определить внутренний идентификатор заказа.

Return URL

URL страницы магазина, куда должен вернуться покупатель при добровольном отказе от оплаты. Отчет об оплате в этом случае магазину не отсылается.

Примечание: MONETA.Assistant добавляет параметр MNT_TRANSACTION_ID в указанную ссылку, чтобы магазин смог определить внутренний идентификатор заказа.

Запрос на оплату через интерфейс MONETA.Assistant представляет собой HTML-форму. Форма должна быть подготовлена магазином, передана Пользователю, подтверждена Пользователем и отправлена на адрес https://moneta.ru/assistant.htm для обработки системой «MONETA.RU». Для тестирования работы системы можно использовать demo площадку: https://demo.moneta.ru/assistant.htm.

Новую форму достаточно поместить внутрь iframe и она сама адаптируется к размерам¹.

Уведомление об оплате MONETA.Assistant отсылает на указанную страницу магазина «Pay URL» в виде HTTP запроса методом GET или POST.

Статус приема уведомления должен быть возвращен в виде ответа на HTTP запрос. Для идентификации отправителя отчета используется «Код проверки целостности данных», который должен быть известен только системе «МОНЕТА.РУ» и учетной системе магазина. При помощи этого кода и основных параметров уведомления об оплате формируется подпись, которая однозначно идентифицирует отправителя и обеспечивает возможность проверки целостности пересылаемых данных.

В случае, если система «МОНЕТА.РУ» не получает ответ от магазина на отправленный запрос с уведомлением (например, из-за недоступности системы учёта магазина), будут произведены попытки отправить уведомление в автоматическом режиме в течение 26-27 часов. По истечении периода автоматической отправки уведомлений операция будет выполнена без подтверждения со стороны магазина.

Ответ на уведомление об оплате

Для того, чтобы сообщить MONETA.Assistant, что магазин получил информацию об оплате, скрипт магазина (PayURL) должен дать ответ соответствующим образом.

Ответ может быть в одном из форматов:

• Текстовый формат в кодировке UTF-8. Этот ответ не должен содержать HTML тэги.
• Ответ в XML формате.

Попытки отправки уведомления будут повторены:

• Если система «MONETA.RU» не смогла получить ответ от обработчика.
• Если сервер магазина был недоступен.
• Если текстовая строка начинается словом FAIL.

Если в свойствах счета магазина выставить Check URL, то магазину, кроме уведомления о проведенной оплате, будут отсылаться проверочные запросы.

Проверочные запросы служат для того, чтобы:

• Убедиться, что заказ существует, что заказ еще не оплачен, что срок действия заказа не истек.
• Указать сумму заказа, если магазин не передал сумму заказа в HTML-форме.
• Проверить статус заказа, если товар уже оплачен.

Проверочные запросы MONETA.Assistant отсылает на указанную страницу магазина Check URL в виде HTTP запроса методом GET или POST. Ответ на HTTP запрос должен быть в формате XML. Во время оплаты одного заказа MONETA.Assistant может несколько раз отсылать проверочные запросы.

Ответ на проверочный запрос

При вызове проверочного запроса (Check URL) магазину следует послать ответ в XML формате.

При получении ответа на проверочный запрос в системе MONETA.RU анализируются поля ответа. MONETA.Assistant прекращает обработку оплаты:

• Если система MONETA.RU не смогла получить ответ от обработчика.
• Если ответ содержит неверный формат.
• Если MNT_ID или MNT_TRANSACTION_ID не соответствуют параметрам запроса.
• Если MNT_RESULT_CODE не соответствует списку возможных кодов.
• Если MNT_SIGNATURE не сходится с ключом, сгенерированным в MONETA.RU.

В обычном режиме работы MONETA.Assistant пользователь может:

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

Например, пользователь выбирает платежную систему WebMoney, затем выбирает в качестве источника оплаты WebMoney WMR, затем видит детали операции, и только после этого попадает на сайт «WebMoney».

MONETA.Assistant позволяет в автоматическом режиме выбрать необходимую платежную систему, заполнить параметры этой платежной системы и перейти на сайт выбранной платежной системы.

Для этого необходимо заполнить дополнительные параметры запроса на оплату заказа.

Дополнительные параметры запроса на оплату

followup

Пройти весь MONETA.Assistant с предустановленными значениями. Для этого необходимо выбрать платежную систему и заполнить параметры платежной системы (если они есть).

Возможные значения:

• true - Использовать дополнительные параметры, чтобы пропустить шаги MONETA.Assistant.
• false - Пользователь сам заполняет формы MONETA.Assistant.

Значение по умолчанию: false.

javascriptEnabled

Признак возможности использовать javascript для автоматической обработки форм (true или false). Если будет передано значение true, а на самом деле у пользователя javascript выключен, то пользователь увидит пустую страницу. Важно передавать действительное значение – «включен» или «выключен» javascript в браузере пользователя. Используется совместно с параметром followup.

paymentSystem.accountId

Номер счета платежной системы. Например, тип кошелька WebMoney, 2 – WMR, 3 – WMZ, 4 – WME.

Примеры запросов на оплату

Пример 1

Пример формы для оплаты заказа «FF790ABCD» в магазине «MAGAZIN.RU» (номер счета 00000001) на сумму 120.25 рублей с автоматической обработкой диалогов. Оплата будет производиться через систему WebMoney, средства будут списаны с WMR кошелька. Пользователь будет перенаправлен на страницу оплаты системы WebMoney.

<form method="post" action="https://moneta.ru/assistant.htm">
  <input type="hidden" name="MNT_ID" value="00000001">
  <input type="hidden" name="MNT_TRANSACTION_ID" value="FF790ABCD">
  <input type="hidden" name="MNT_CURRENCY_CODE" value="RUB">
  <input type="hidden" name="MNT_AMOUNT" value="120.25">
  <input type="hidden" name="paymentSystem.accountId" value="2">
  <input type="hidden" name="javascriptEnabled" value="true">
  <input type="hidden" name="followup" value="true">
  <input type="submit" value="Pay with Webmoney WMR">
</form>

Если в браузере пользователя выключен javascript и в MONETA.Assistant придет параметр javascriptEnabled = false, то пользователь попадет на последний шаг MONETA.Assistant – просмотр деталей операции. Для перехода на сайт системы WebMoney пользователь должен нажать кнопку Продолжить.

Пример 2

Пример формы для оплаты заказа «FF790ABCD» в магазине «MAGAZIN.RU» (номер счета 00000001) на сумму 120.25 рублей с автоматической обработкой диалогов. Оплата будет производиться через систему Яндекс.Деньги.

<form method="post" action="https://moneta.ru/assistant.htm">
  <input type="hidden" name="MNT_ID" value="00000001">
  <input type="hidden" name="MNT_TRANSACTION_ID" value="FF790ABCD">
  <input type="hidden" name="MNT_CURRENCY_CODE" value="RUB">
  <input type="hidden" name="MNT_AMOUNT" value="120.25">
  <input type="hidden" name="followup" value="true">
  <input type="submit" value="Pay with Yandex.Money">
</form>

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

Проверочные запросы служат для того, чтобы:

1. Получить от поставщика данные которые зависят от уже введенных данных (например, по лицевому счету вернуть адрес и показания счетчиков).
2. Указать сумму заказа, если сумма зависит от введенных параметров.

Основные принципы взаимодействия

Запросы на получение данных MONETA.Assistant отсылает на указанный в «Check URL» адрес в виде HTTP запроса методом GET или POST. Ответ на HTTP запрос должен быть в формате XML.

Во время оплаты одного заказа MONETA.Assistant может несколько раз отсылать проверочные запросы на получение данных.

При получении ответа на проверочный запрос в системе MONETA.RU анализируются поля ответа. Проверочный запрос считается не отправленным, и дальнейшая обработка заказа будет прервана:

• Если система MONETA.RU не смогла получить ответ от обработчика.
• Если ответ содержит неверный формат.
• Если MNT_ID или MNT_TRANSACTION_ID не соответствуют параметрам запроса.
• Если MNT_RESULT_CODE не соответствует списку возможных кодов.
• Если MNT_SIGNATURE не сходится с ключом, сгенерированным в MONETA.RU.

302

При отправке проверочного запроса в адрес партнера получен некорректный ответ (стандартная html-страница, страница с сообщением об ошибке и т.п.) или перенаправление на другой адрес (HTTP Status 301, 302).

Убедитесь, что ваш сервис доступен по адресу, указанному в Check URL, и в ответ на запрос вы возвращаете корректный XML.

-1

Запроса не было. В настройках счета задан параметр Check URL, но не задан параметр Pay URL.

-600

Невозможно отправить уведомление. Неверный Check URL или Pay URL или невозможно установить соединение.

Убедитесь, что в разделе управления счетами в настройках Check URL и Pay URL заданы верно, например: http://www.merchant-site.com/script

Примечание: Адрес должен быть доступен для нашей системы (например, нельзя задавать локальные имена внутренних серверов “localhost”, “my-pc” и т.п.).

-700

Невозможно обработать ответ. Неверный xml формат ответа или неверно сформированная подпись ответа.

Убедитесь, что ваш сервис возвращает xml в корректном формате, при формировании подписи вы используете тот же код проверки целостности данных, что указан в настройках счёта.

Виджет https://moneta.ru/assistant.widget - это форма оплаты, у которой визуальное представление организовано таким образом, чтобы посетитель интернет-магазина мог бы ввести его платежные данные прямо в корзине своего интернет-магазина.

Если Вы не используете виджет, то посетитель должен будет перейти из корзины на отдельную страницу оплаты заказа по кнопке “Оплатить”, размещенной в корзине.

Кнопка “Оплатить” в корзине должна формироваться динамически и представляет собой форму, у которой имеется ряд скрытых полей.

Таким образом, видна остается лишь только кнопка для отправки формы, т.е. кнопка “Оплатить”:

<form method='post' action='https://moneta.ru/assistant.htm'>
  <input type='hidden' name='MNT_ID' value='19312235'>
  <input type='hidden' name='MNT_CURRENCY_CODE' value='RUB'>
  <input type='hidden' name='MNT_AMOUNT' value='10.25'>
  <input type='submit' value='Pay order'>
</form>

Чтобы вместо кнопки “Оплатить” сразу показать форму оплаты, надо поместить в корзину код iframe:

<iframe src='https://moneta.ru/assistant.widget?MNT_ID=19312235&MNT_CURRENCY_CODE=RUB&MNT_AMOUNT=10.25'>
  Ваш браузер не поддерживает плавающие фреймы!
</iframe>

Таким образом, мы “просим” MONETA.Assistant показать форму для оплаты заказа внутри iframe.

Если корзина интернет-магазина может быть изменена без перезагрузки страницы, то следует так же менять и параметры, передаваемые в iframe, в частности сумму заказа.

Особенности использования

Ссылка assistant.widget отличается от assistant.htm только дизайном - в assistant.widget не показываются хидеры, футеры и т.д. Это та же кнопка “Оплатить”, но уже “развёрнутая”.

SuccessUrl и FailUrl вызываются также, но нужно учитывать, что они покажутся в Вашем фрейме. Так как SuccessUrl и FailUrl - это страницы с Вашим дизайном, то Вам следует их оформить так, чтобы они хорошо смотрелись в iframe. Если Вам необходимо иметь разные SuccessUrl и FailUrl для работы с одним счетом (показывать в iframe и в браузере), то Вы можете передавать параметры MNT_SUCCESS_URL и MNT_FAIL_URL необходимые для данного конкретного случая (на счете в таком случае должна стоять галочка - “Можно переопределять параметры в запросе”).

Содержимое iframe можно стилизовать индивидуально по Вашему усмотрению. Примеры страниц, на которых выводится виджет MONETA.Assistant с измененным внешним видом при помощи дополнительного css-кода можно увидеть здесь.

Там же есть листинги css-кода по каждому из приведенных примеров. Для установки стилей на Вашем расширенном счете, необходимо прислать css-код для review в техническую поддержку. Примеры использования: http://payanyway.ru/info/w/ru/public/w/partnership/demo/var2.html

Добавление платёжной формы на сайт магазина

Подключим скрипт

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

<script type="text/javascript" src="https://payanyway.ru/assistant-builder"></script>

Определим параметры платежа

Теперь на этой же странице нужно подготовить параметры для платёжной формы:

<script type="text/javascript">
    let options = {
        account: 32691195,
        amount: 12.34,
        transactionId: '1234567890-abcdef'
    };

    // ...

</script>

В этом примере параметров всего три, но может быть и больше – вот они все:

account

Номер вашего бизнес-счёта.

amount

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

transactionId

Номер заказа в магазине.

operationId

ID операции в Монете.

description

Описание заказа.

signature

Подпись запроса.

subscriberId

ID клиента в магазине.

testMode

Признак тестового платежа. Значения:

• 0 – платёж настоящий (по умолчанию)
• 1 – платёж тестовый

amount

Язык интерфейса. Значения:

• ru – русский (по умолчанию)
• en – английский

theme

Цветовая тема интерфейса. Значения:

• light – светлая (по умолчанию)
• dark – тёмная

customParams

Укажите любые другие параметры, если необходимо. Например:

customParams: {
    param1: "value1",
    param2: "value2"
}

Все параметры из блока customParams будут присутствовать в запросах на Check и Pay URL.

Отрисуем платёжную форму

После того, как все параметры платёжной формы определены – отрисуем её:

let assistant = new Assistant.Builder();
assistant.build(options, 'payment-form');

Обратите внимание на второй параметр в функции build. Это id контейнера, в котором будет отрисована платёжная форма. В данном примере нам предварительно нужно было создать следующий html-элемент и разместить его на странице:

<div id="payment-form"></div>

Если не указывать второй параметр в функции build – платёжная форма будет отрисована в модальном окне поверх всей страницы.

Добавим обработчики

И ещё один момент – после успешной оплаты или в случае ошибки (а иногда – во время обработки платежа) бывает необходимо совершить какие-либо действия: уйти на другую страницу и так далее. Для этого можно добавить обработчики:

// платёж прошёл успешно
assistant.setOnSuccessCallback(function(operationId, transactionId) {
    // здесь можно сделать что угодно – например,
    // перенаправить на другую страницу
    location.replace("https://domain.domain");
});

// платёж не прошёл
assistant.setOnFailCallback(function(operationId, transactionId) {
    // действия по обработке ошибок
});

// платёж обрабатывается
assistant.setOnInProgressCallback(function(operationId, transactionId) {
    // действия по обработке промежуточного статуса операции
});

Здесь:

• operationId – номер операции в Монете
• transactionId – номер заказа в магазине

Код целиком

<div id="payment-form"></div>

<script type="text/javascript" src="https://payanyway.ru/assistant-builder"></script>

<script type="text/javascript">
    let options = {
        account: 32691195,
        amount: 12.34,
        transactionId: '1234567890-abcdef'
    };

    let assistant = new Assistant.Builder();

    // платёж прошёл успешно
    assistant.setOnSuccessCallback(function(operationId, transactionId) {
        // здесь можно сделать что угодно – например,
        // перенаправить на другую страницу
        location.replace("https://domain.domain");
    });

    // платёж не прошёл
    assistant.setOnFailCallback(function(operationId, transactionId) {
        // действия по обработке ошибок
    });

    // платёж обрабатывается
    assistant.setOnInProgressCallback(function(operationId, transactionId) {
        // действия по обработке промежуточного статуса операции
    });

    assistant.build(options, 'payment-form');
</script>