Mir Pay

Введение

Платежная система Мир предоставляет возможность принимать платежи из приложений мерчанта или мобильных версий сайтов с использованием сервиса Mir Pay.

Если у вас есть разрешение на создание связок, то во время оплаты через Mir Pay вы можете создавать связки (сохраненные данные карты) для дальнейших регулярных платежей (рекуррентных платежей или платежей в рассрочку).

В следующих разделах описывается интеграция метода оплаты Mir Pay In-Application.

Чтобы принимать платежи через Mir Pay, у вас должна быть включена эта функция.

Схемы интеграции

Платежная страница на стороне Платежного шлюза

sequenceDiagram participant C as Клиент participant M as Мерчант participant P as Платежная страница participant G as Платежный шлюз participant MP as Mir Pay C->>M: 1. Формирование заказа M->>G: 2. Запрос на регистрацию заказа G-->>M: 3. Ответ на запрос M-->>C: 4. Перенаправление на платежную страницу C->>P: 5. Получение платежной формы P->>G: 6. Запрос возможных способов оплаты G->>G: 7. Формирование Universal link G-->>P: 8. Опция продавца Mir Pay, Universal link P-->>C: 9. Платежная форма C->>P: 10. Выбор способа оплаты Mir Pay P->>MP: 11. Universal link MP->>MP: 12. Проверка MP-->>C: 13. Список карт C->>MP: 14. Выбор карты MP-->>C: 15. Перенаправление клиента на платежную страницу MP-->>G: 16. Платежные данные G->>G: 17. Расшифровка данных G->>G: 18. Оплата токеном C->>P: 19. Запрос результата платежа P->>G: 20. Запрос результата платежа G-->>P: 21. Результат оплаты P-->>C: 22. Результат оплаты
  1. Клиент формирует заказ на сайте мерчанта.
  2. Продавец направляет в платежный шлюз запрос регистрации заказа.
    a. При одностадийном платеже - register.do;
    b. При двухстадийном платеже - registerPreAuth.do
  3. Платежный шлюз регистрирует заказ и отправляет мерчанту ответ, содержащий параметр formUrl (платежный URL-адрес, на который мерчант должен перенаправить клиента) и параметр  orderId  (уникальный номер заказа в системе платежного шлюза).
  4. Интернет-магазин перенаправляет клиента на URL, полученный в параметре  formUrl.
  5. Браузер клиента открывает полученный URL.
  6. Платежная страница запрашивает список возможных способов оплаты у платежного шлюза.
  7. Платежный шлюз формирует Universal link.
  8. Платежный шлюз в ответе возвращает опцию мерчанта Mir Pay и Universal link.
  9. Клиент получает платежную форму с отрисованной кнопкой оплаты MirPay.
  10. Клиент выбирает способ оплаты Mir Pay на платежной странице.
  11. Платежная страница запускает Universal link на устройстве клиента.
  12. Mir Pay проверяет подпись продавца и его участие в программе.
  13. Mir Pay отображает список карт клиенту.
  14. Клиент выбирает карту для оплаты в приложении Mir Pay.
  15. Mir Pay передает браузеру клиента redirect на URL платежной страницы.
  16. Mir Pay формирует данные платежа и отправляет зашифрованные данные платежа в платежный шлюз.
  17. Платежный шлюз расшифровывает данные платежа.
  18. Платежный шлюз осуществляет оплату.
  19. Браузер клиента обращается к платежной странице для получения результата оплаты.
  20. Платежная страница запрашивает у платежного шлюза результат оплаты.
  21. Платежный шлюз возвращает результат оплаты на платежную страницу.
  22. Платежная страница отображает результат оплаты клиенту.

Платежная страница/приложение на стороне мерчанта

Необходимые условия

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

Вместе с конечным сертификатом вы должны получить от службы технической поддержки следующее:

  1. Документ «Стандарт платежной системы «Мир». Описание реализации Mir Pay Android In-Application операций для ТСП».
  2. Библиотека MirPaySDK.aar для встраивания в мобильное приложение продавца.
  3. Описание API в виде yaml-файла;
  4. URL-адрес файла конечного сертификата ТСП на общедоступном Web-ресурсе Агрегатора (https://<хост участника>/jwks/-jwks.json), если данное ТСП поддерживает технологию In-Application Web-based операций.
sequenceDiagram participant C as Клиент participant M as Мерчант participant G as Платежный шлюз participant MP as Mir Pay C->>M: 1. Выбор способа оплаты Mir Pay M->>MP: 2. Вызов Mir Pay MP->>MP: 3. Проверка подписи MP-->>C: 4. Список карт C->>MP: 5. Выбор карты MP-->>M: 6. Зашифрованные платежные данные M->>G: 7. Запрос на оплату Mir Pay G->>G: 8. Расшифровка данных G->>G: 9. Оплата G-->>M: 10. Результат оплаты M-->>C: 11. Результат оплаты
  1. Клиент выбирает способ оплаты Mir Pay на платежной странице мерчанта.
  2. Продавец запускает скрипт подготовки операции In-Application через MirPaySDK в приложении Mir Pay / Продавец запускает скрипт подготовки операции In-Application через Deeplink или Universal Link в приложении Mir Pay.
  3. Mir Pay проверяет подпись продавца и его участие в программе.
  4. Mir Pay отображает список карт клиенту.
  5. Клиент выбирает карту для оплаты в приложении Mir Pay.
  6. Mir Pay формирует данные платежа и отправляет зашифрованные данные платежа продавцу.
  7. Продавец запрашивает платеж, отправляя API-запрос /mir/payment.do в платежный шлюз.
  8. Платежный шлюз расшифровывает данные платежа.
  9. Платежный шлюз осуществляет оплату.
  10. Платежный шлюз возвращает результат оплаты мерчанту.
  11. Мерчант отображает результат оплаты клиенту.

Расшифровка платежных данных на стороне продавца

sequenceDiagram participant C as Клиент participant M as Мерчант participant G as Платежный шлюз participant MP as Mir Pay C->>M: 1. Выбор способа оплаты Mir Pay M->>MP: 2. Вызов Mir Pay MP->>MP: 3. Проверка подписи MP-->>C: 4. Список карт C->>MP: 5. Выбор карты MP-->>M: 6. Зашифрованные платежные данные M->>M: 7. Расшифровка данных M->>G: 8. Запрос на оплату Mir Pay G->>G: 9. Оплата G-->>M: 10. Результат оплаты M-->>C: 11. Результат оплаты
  1. Клиент выбирает способ оплаты Mir Pay на платежной странице.
  2. Продавец запускает скрипт подготовки операции In-Application через MirPaySDK в приложении Mir Pay / Продавец запускает скрипт подготовки операции In-Application через Deeplink или Universal Link в приложении Mir Pay.
  3. Mir Pay проверяет подпись продавца и его участие в программе.
  4. Mir Pay отображает список карт клиенту.
  5. Клиент выбирает карту для оплаты в приложении Mir Pay.
  6. Mir Pay формирует данные платежа и отправляет зашифрованные данные платежа в мерчанту.
  7. Продавец расшифровывает данные платежа.
  8. Продавец создает запрос на проведение платежа /mir/paymentDirect.do, содержащий расшифрованные платежные данные, и отправляет его платежному шлюзу.
  9. Платежный шлюз осуществляет оплату.
  10. Платежный шлюз возвращает результат оплаты мерчанту.
  11. Мерчант отображает результат оплаты клиенту.

API-запросы Mir Pay

Регистрация заказа Mir Pay Pay

Для регистрации и оплаты заказа используется запрос https://vtb.rbsuat.com/payment/mir/payment.do. Запрос доступен, если мерчант имеет соответствующее разрешение.


При выполнении запроса необходимо использовать заголовок: Content-Type: application/json

Параметры запроса

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

merchant String Логин продавца в системе платежного шлюза. Обязательно, если авторизация осуществляется через merchant.
Условие

username String [1..100] Логин учетной записи API продавца. Обязательно, если авторизация осуществляется через username и password.
Условие

password String [1..200] Пароль учетной записи API продавца. Обязательно, если авторизация осуществляется через username и password.
Обязательно

orderNumber String [1..32] Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа.
Необязательно

description String [1..598] Описание заказа в любом формате.
Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки.
В этом поле недопустимо передавать персональные данные или платежные данные (номера карт т.п.). Данное требование связано с тем, что описание заказа нигде не маскируется.
Необязательно

language String [2] Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина.
Поддерживаемые языки: ru, en.
Необязательно

additionalParameters Object Дополнительные параметры заказа, которые хранятся в личном кабинете продавца для последующего просмотра. Каждая новая пара имени параметра и его значения должна быть разделена запятой. Ниже приведен пример использования.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
При создании связки в этом тэге могут быть переданы параметры, определяющие тип создаваемой связки. См. список параметров.
Необязательно

preAuth Boolean Параметр, определяющий необходимость предварительной авторизации (блокирования средств на счете клиента до их списания). Доступны следующие значения:
  • true - включена двухстадийная оплата;
  • false - включена одностадийная оплата (деньги списываются сразу).
Если параметр отсутствует, производится одностадийная оплата.
Обязательно

ip String [1..39] IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов).
Необязательно

clientId String [0..255] Номер клиента (ID) в системе мерчанта — до 255 символов. Используется для реализации функциональности связок. Может возвращаться в ответе, если мерчанту разрешено создавать связки.
Указание этого параметра при обработке платежей по связке обязательно. В противном случае платеж будет невозможен.
Обязательно

paymentToken String [1..8192] Строка в формате JWE Compact Serialization с данными операции In-Application.
Необязательно

clientId String [0..255] Номер клиента, для которого следует создать связку для проведения регулярных платежей.
Следует указывать, только если проводится технический платёж для последующих регулярных платежей.
Необязательно

tii String Идентификатор инициатора транзакции. Параметр, указывающий, какой тип операции будет выполнять инициатор (Клиент или Мерчант). Указывается при создании связки для регулярных платежей. Возможные значения.

Дополнительные параметры, определяющие тип создаваемой связки и передаваемые в additionalParameters:

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

installments Integer [3] Максимальное количество разрешенных авторизаций для платежей в рассрочку.
Указывается в случае создания связки для выполнения платежей в рассрочку.
Условие

recurringFrequency Integer [2] Минимальное количество дней между авторизациями. Целое положительное число от 1 до 28 включительно.
Указывается в случае создания связки для выполнения рекуррентных платежей.
Условие

recurringExpiry String [8] Дата, после которой дальнейшие авторизации не должны выполняться. Формат: YYYYMMDD.
Указывается в случае создания связки для выполнения рекуррентных платежей.

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

Значение tii Описание Тип транзакции Инициатор транзакции Данные карты для транзакции Сохранение данных карты после транзакции Примечание
Пусто Обычный Покупатель Вводится покупателем Нет Транзакция электронной коммерции без сохранения связки.
CI Инициирующий - Обычный (CIT) Инициирующая Покупатель Вводится покупателем Да Транзакция электронной коммерции с сохранением связки.
F Внеплановый платеж (CIT) Последующая Покупатель Клиент выбирает карту вместо ручного ввода Нет Транзакция электронной коммерции, использующая ранее сохраненную обычную связку.
U Внеплановый платеж (MIT) Последующая Продавец Нет ручного ввода, продавец передает данные Нет Транзакция электронной коммерции, использующая ранее сохраненную обычную связку.
RI Инициирующий - Рекурентные (CIT) Инициирующая Покупатель Вводится покупателем Да Транзакция электронной коммерции с сохранением связки.
R Рекуррентный платеж (MIT) Последующая Продавец Нет ручного ввода, продавец передает данные Нет Рекуррентная операция, использующая сохраненную связку.
II Инициирующий - Рассрочка (CIT) Инициирующая Покупатель Вводится покупателем Да Транзакция электронной коммерции с сохранением связки.
I Платеж по рассрочке (MIT) Последующая Продавец Нет ручного ввода, продавец передает данные Нет Операция рассрочки, использующая сохраненную связку.

Параметры ответа

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

success Boolean Основной параметр, который указывает на то, что запрос прошел успешно. Доступны следующие значения:
  • true - запрос успешно обработан;
  • false - запрос не прошел.

Обратите внимание, что значение true означает, что запрос был обработан, а не что заказ был оплачен.
Более подробная информация о том, как узнать, был ли платеж успешным или нет, доступна здесь.
Условие data Object Этот параметр возвращается только в случае успешной обработки платежа. См. описание ниже.
Условие error Object Этот параметр возвращается только в случае ошибки платежа. См. описание ниже.

Блок data содержит следующие элементы.

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

orderId String [1..36] Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.
Необязательно

bindingId String [1..255] Идентификатор связки, созданной при оплате заказа или использованной для оплаты. Доступно, только если продавцу разрешено создавать связки.

В качестве указания целевой карты для перевода денежных средств необходимо обязательно передать один из следующих параметров - bindingId/pan/seToken.

Блок error содержит следующие элементы.

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

code Integer [1..3] Код как информационный параметр, сообщающий об ошибке.
Обязательно

description String [1..598] Подробное техническое объяснение ошибки - содержимое этого параметра не предназначено для отображения пользователю.
Обязательно

message String [1..512] Информационный параметр, являющийся описанием ошибки для отображения пользователю. Параметр может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде.

Примеры

Пример запроса

curl --location 'https://vtb.rbsuat.com/payment/mir/payment.do' \
--header 'Content-Type: application/json' \
--data '{
    "username": "test_user",
    "password": "test_user_password",
    "orderNumber": 3229,
    "description": "description",
    "language": "RU",
    "tii" : "II",
    "clientId":"202403122",
    "additionalParameters": {
        "installments": "5",
        "recurringFrequency": "5",
        "recurringExpiry": "20241004"
    },
    "preAuth": false,
    "paymentToken": "eyJhbGciOiJSU0...9HDxLg",
    "ip": "127.0.0.1"
}'

Ответ в случае успешной оплаты

{
    "success": true,
    "data": {
        "orderId": "243ec139-4b5a-7859-b409-bbcb4806bc81",
        "bindingId": "7c1d7969-bf01-7f34-be04-c6904806bc81"
    }
}

Ответ в случае неудачной оплаты

{
  "error": {
    "code": 1,
    "description": "Processing Error",
    "message": "Insufficient amount on card"
  },
  "success": false
}

Mir Pay Direct

Запрос, используемый для осуществления прямого платежа через Mir Pay - https://vtb.rbsuat.com/payment/mir/paymentDirect.do. Запрос доступен, если мерчант имеет соответствующее разрешение.

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


При выполнении запроса необходимо использовать заголовок: Content-Type: application/json

Параметры запроса

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

merchant String Логин продавца в системе платежного шлюза. Обязательно, если авторизация осуществляется через merchant.
Условие

username String [1..100] Логин учетной записи API продавца. Обязательно, если авторизация осуществляется через username и password.
Условие

password String [1..200] Пароль учетной записи API продавца. Обязательно, если авторизация осуществляется через username и password.
Обязательно

orderNumber String [1..32] Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа.
Необязательно

description String [1..598] Описание заказа в любом формате.
Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки.
В этом поле недопустимо передавать персональные данные или платежные данные (номера карт т.п.). Данное требование связано с тем, что описание заказа нигде не маскируется.
Необязательно

language String [2] Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина.
Поддерживаемые языки: ru, en.
Необязательно

additionalParameters Object Дополнительные параметры заказа, которые хранятся в личном кабинете продавца для последующего просмотра. Каждая новая пара имени параметра и его значения должна быть разделена запятой. Ниже приведен пример использования.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
При создании связки в этом тэге могут быть переданы параметры, определяющие тип создаваемой связки. См. список параметров.
Необязательно

preAuth Boolean Параметр, определяющий необходимость предварительной авторизации (блокирования средств на счете клиента до их списания). Доступны следующие значения:
  • true - включена двухстадийная оплата;
  • false - включена одностадийная оплата (деньги списываются сразу).
Если параметр отсутствует, производится одностадийная оплата.
Обязательно

ip String [1..39] IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов).
Обязательно

paymentToken String [1..8192] Токен, полученный от MirPay. Значение должно быть закодировано в Base64.
Необязательно

clientId String [0..255] Номер клиента, для которого следует создать связку для проведения регулярных платежей.
Следует указывать, только если проводится технический платёж для последующих регулярных платежей.
Необязательно

tii String Идентификатор инициатора транзакции. Параметр, указывающий, какой тип операции будет выполнять инициатор (Клиент или Мерчант). Указывается при создании связки для регулярных платежей. Возможные значения.

Дополнительные параметры, определяющие тип создаваемой связки и передаваемые в additionalParameters:

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

installments Integer [3] Максимальное количество разрешенных авторизаций для платежей в рассрочку.
Указывается в случае создания связки для выполнения платежей в рассрочку.
Условие

recurringFrequency Integer [2] Минимальное количество дней между авторизациями. Целое положительное число от 1 до 28 включительно.
Указывается в случае создания связки для выполнения рекуррентных платежей.
Условие

recurringExpiry String [8] Дата, после которой дальнейшие авторизации не должны выполняться. Формат: YYYYMMDD.
Указывается в случае создания связки для выполнения рекуррентных платежей.

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

Значение tii Описание Тип транзакции Инициатор транзакции Данные карты для транзакции Сохранение данных карты после транзакции Примечание
Пусто Обычный Покупатель Вводится покупателем Нет Транзакция электронной коммерции без сохранения связки.
CI Инициирующий - Обычный (CIT) Инициирующая Покупатель Вводится покупателем Да Транзакция электронной коммерции с сохранением связки.
F Внеплановый платеж (CIT) Последующая Покупатель Клиент выбирает карту вместо ручного ввода Нет Транзакция электронной коммерции, использующая ранее сохраненную обычную связку.
U Внеплановый платеж (MIT) Последующая Продавец Нет ручного ввода, продавец передает данные Нет Транзакция электронной коммерции, использующая ранее сохраненную обычную связку.
RI Инициирующий - Рекурентные (CIT) Инициирующая Покупатель Вводится покупателем Да Транзакция электронной коммерции с сохранением связки.
R Рекуррентный платеж (MIT) Последующая Продавец Нет ручного ввода, продавец передает данные Нет Рекуррентная операция, использующая сохраненную связку.
II Инициирующий - Рассрочка (CIT) Инициирующая Покупатель Вводится покупателем Да Транзакция электронной коммерции с сохранением связки.
I Платеж по рассрочке (MIT) Последующая Продавец Нет ручного ввода, продавец передает данные Нет Операция рассрочки, использующая сохраненную связку.

Параметры ответа

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

success Boolean Основной параметр, который указывает на то, что запрос прошел успешно. Доступны следующие значения:
  • true - запрос успешно обработан;
  • false - запрос не прошел.

Обратите внимание, что значение true означает, что запрос был обработан, а не что заказ был оплачен.
Более подробная информация о том, как узнать, был ли платеж успешным или нет, доступна здесь.
Условие data Object Этот параметр возвращается только в случае успешной обработки платежа. См. описание ниже.
Условие error Object Этот параметр возвращается только в случае ошибки платежа. См. описание ниже.

Блок data содержит следующие элементы.

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

orderId String [1..36] Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.
Необязательно

bindingId String [1..255] Идентификатор связки, созданной при оплате заказа или использованной для оплаты. Доступно, только если продавцу разрешено создавать связки.

В качестве указания целевой карты для перевода денежных средств необходимо обязательно передать один из следующих параметров - bindingId/pan/seToken.

Блок error содержит следующие элементы.

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

code Integer [1..3] Код как информационный параметр, сообщающий об ошибке.
Обязательно

description String [1..598] Подробное техническое объяснение ошибки - содержимое этого параметра не предназначено для отображения пользователю.
Обязательно

message String [1..512] Информационный параметр, являющийся описанием ошибки для отображения пользователю. Параметр может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде.

Примеры

Пример запроса

curl --location 'https://vtb.rbsuat.com/payment/mir/paymentDirect.do' \
--header 'Content-Type: application/json' \
--data '{
    "username": "test_user",
    "password": "test_user_password",
    "orderNumber": 243ec139-4b5a-7859-b409-bbcb4806bc81,
    "description": "description",
    "language": "RU",
    "tii" : "II",
    "clientId":"202403112",
    "additionalParameters": {
        "installments": "5",
        "recurringFrequency": "5",
        "recurringExpiry": "20241231"
    },
    "preAuth": false,
    "paymentToken": "eyJ0YW4iOiIyMj...wifQ==",
    "ip": "127.0.0.1"
}'

Ответ в случае успешной оплаты

{
    "success": true,
    "data": {
        "orderId": "243ec139-4b5a-7859-b409-bbcb4806bc81",
        "bindingId": "7c1d7969-bf01-7f34-be04-c6904806bc81"
    }
}

Ответ в случае неудачной оплаты

{
  "error": {
    "code": 1,
    "description": "Processing Error",
    "message": "Insufficient amount on card"
  },
  "success": false
}

Категории:
eCommerce API V1
Категории
Результаты поиска