Mir Pay
Введение
Платежная система Мир предоставляет возможность принимать платежи из приложений мерчанта или мобильных версий сайтов с использованием сервиса Mir Pay.
Если у вас есть разрешение на создание связок, то во время оплаты через Mir Pay вы можете создавать связки (сохраненные данные карты) для дальнейших регулярных платежей (рекуррентных платежей или платежей в рассрочку).
В следующих разделах описывается интеграция метода оплаты Mir Pay In-Application.
Чтобы принимать платежи через Mir Pay, у вас должна быть включена эта функция.
Схемы интеграции
Платежная страница на стороне Платежного шлюза
- Клиент формирует заказ на сайте мерчанта.
- Продавец направляет в платежный шлюз запрос регистрации заказа.
a. При одностадийном платеже - register.do;
b. При двухстадийном платеже - registerPreAuth.do - Платежный шлюз регистрирует заказ и отправляет мерчанту ответ, содержащий параметр
formUrl
(платежный URL-адрес, на который мерчант должен перенаправить клиента) и параметрorderId
(уникальный номер заказа в системе платежного шлюза). - Интернет-магазин перенаправляет клиента на URL, полученный в параметре
formUrl
. - Браузер клиента открывает полученный URL.
- Платежная страница запрашивает список возможных способов оплаты у платежного шлюза.
- Платежный шлюз формирует Universal link.
- Платежный шлюз в ответе возвращает опцию мерчанта Mir Pay и Universal link.
- Клиент получает платежную форму с отрисованной кнопкой оплаты MirPay.
- Клиент выбирает способ оплаты Mir Pay на платежной странице.
- Платежная страница запускает Universal link на устройстве клиента.
- Mir Pay проверяет подпись продавца и его участие в программе.
- Mir Pay отображает список карт клиенту.
- Клиент выбирает карту для оплаты в приложении Mir Pay.
- Mir Pay передает браузеру клиента redirect на URL платежной страницы.
- Mir Pay формирует данные платежа и отправляет зашифрованные данные платежа в платежный шлюз.
- Платежный шлюз расшифровывает данные платежа.
- Платежный шлюз осуществляет оплату.
- Браузер клиента обращается к платежной странице для получения результата оплаты.
- Платежная страница запрашивает у платежного шлюза результат оплаты.
- Платежный шлюз возвращает результат оплаты на платежную страницу.
- Платежная страница отображает результат оплаты клиенту.
Платежная страница/приложение на стороне мерчанта
Необходимые условия
Для того, чтобы иметь возможность принимать платежи Mir Pay через платежный шлюз, у вас должен быть выпущенный для вас сертификат. Для получения данного сертификата обратитесь в службу технической поддержки.
Вместе с конечным сертификатом вы должны получить от службы технической поддержки следующее:
- Документ «Стандарт платежной системы «Мир». Описание реализации Mir Pay Android In-Application операций для ТСП».
- Библиотека MirPaySDK.aar для встраивания в мобильное приложение продавца.
- Описание API в виде yaml-файла;
- URL-адрес файла конечного сертификата ТСП на общедоступном Web-ресурсе Агрегатора (https://<хост участника>/jwks/-jwks.json), если данное ТСП поддерживает технологию In-Application Web-based операций.
- Клиент выбирает способ оплаты Mir Pay на платежной странице мерчанта.
- Продавец запускает скрипт подготовки операции In-Application через MirPaySDK в приложении Mir Pay / Продавец запускает скрипт подготовки операции In-Application через Deeplink или Universal Link в приложении Mir Pay.
- Mir Pay проверяет подпись продавца и его участие в программе.
- Mir Pay отображает список карт клиенту.
- Клиент выбирает карту для оплаты в приложении Mir Pay.
- Mir Pay формирует данные платежа и отправляет зашифрованные данные платежа продавцу.
- Продавец запрашивает платеж, отправляя API-запрос /mir/payment.do в платежный шлюз.
- Платежный шлюз расшифровывает данные платежа.
- Платежный шлюз осуществляет оплату.
- Платежный шлюз возвращает результат оплаты мерчанту.
- Мерчант отображает результат оплаты клиенту.
Расшифровка платежных данных на стороне продавца
- Клиент выбирает способ оплаты Mir Pay на платежной странице.
- Продавец запускает скрипт подготовки операции In-Application через MirPaySDK в приложении Mir Pay / Продавец запускает скрипт подготовки операции In-Application через Deeplink или Universal Link в приложении Mir Pay.
- Mir Pay проверяет подпись продавца и его участие в программе.
- Mir Pay отображает список карт клиенту.
- Клиент выбирает карту для оплаты в приложении Mir Pay.
- Mir Pay формирует данные платежа и отправляет зашифрованные данные платежа в мерчанту.
- Продавец расшифровывает данные платежа.
- Продавец создает запрос на проведение платежа /mir/paymentDirect.do, содержащий расшифрованные платежные данные, и отправляет его платежному шлюзу.
- Платежный шлюз осуществляет оплату.
- Платежный шлюз возвращает результат оплаты мерчанту.
- Мерчант отображает результат оплаты клиенту.
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 | Параметр, определяющий необходимость предварительной авторизации (блокирования средств на счете клиента до их списания). Доступны следующие значения:
|
Обязательно | 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 означает, что запрос был обработан, а не что заказ был оплачен.Более подробная информация о том, как узнать, был ли платеж успешным или нет, доступна здесь. |
Условие | data |
Object | Этот параметр возвращается только в случае успешной обработки платежа. См. описание ниже. |
Условие | error |
Object | Этот параметр возвращается только в случае ошибки платежа. См. описание ниже. |
Блок data
содержит следующие элементы.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | orderId |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Необязательно | bindingId |
String [1..255] | Идентификатор связки, созданной при оплате заказа или использованной для оплаты. Доступно, только если продавцу разрешено создавать связки. В качестве указания целевой карты для перевода денежных средств необходимо обязательно передать один из следующих параметров - |
Блок 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 | Параметр, определяющий необходимость предварительной авторизации (блокирования средств на счете клиента до их списания). Доступны следующие значения:
|
Обязательно | 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 означает, что запрос был обработан, а не что заказ был оплачен.Более подробная информация о том, как узнать, был ли платеж успешным или нет, доступна здесь. |
Условие | data |
Object | Этот параметр возвращается только в случае успешной обработки платежа. См. описание ниже. |
Условие | error |
Object | Этот параметр возвращается только в случае ошибки платежа. См. описание ниже. |
Блок data
содержит следующие элементы.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | orderId |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Необязательно | bindingId |
String [1..255] | Идентификатор связки, созданной при оплате заказа или использованной для оплаты. Доступно, только если продавцу разрешено создавать связки. В качестве указания целевой карты для перевода денежных средств необходимо обязательно передать один из следующих параметров - |
Блок 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
}