Двухстадийная оплата (сессия)

Сценарий создания платежной сессии, на холдирование средств

Плательщик на сайте магазина выбирает услугу и условия платежа. Сайт предварительно передает реквизиты платежа в платежный шлюз МТС, а в ответ получает идентификатор платежной сессии (вызов метода идет с backend магазина, при вызове метода необходимо использовать SSL сертификат - полученный при интеграции). После чего пользователю отображается виджет, в котором проводится прием оплаты. По завершению сценария, средства на счете холдируются, Платежный шлюз МТС уведомляет сайт по указанному адресу о завершении этапа холдирования платежа. После этого вы сможете выполнить дополнительные операции над платежами.

Процесс взаимодействия

Для проведения платежа вам необходимо создать платежную сессию.
С полученным после создания платежной сессии sessionId инициализируйте виджет (веб-виджет, iOS, Android).
Получите уведомление о результате платежа (холдирования).
Подтвердите списания средств - Метод для проведения списания после успешной предавторизации
Отмените холдирование - Метод для отмены холдирования средств
При необходимости можно:
1. убедиться, что уведомление пришло от нас, получив самостоятельно информацию о платеже (статус платежа);
2. отменить платеж или вернуть денежные средства.

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

Заголовок запроса

POST
Endpoint: https://sandbox.pay.mts.ru/private/v1/payments/sessions/preauth/create HTTP/1.1
Content-Type: application/json
<Основные параметры>

Так же, передается SSL сертификат.

Основные параметры

Поле	Тип	Обязат.	Описание
Request-Id	guid	да	Идентификатор конкретного запроса
Requestor-Name	string	нет	Наименование сервиса. Для веба - домен, на котором запущен виджет. Для SDK - идентификатор приложения. Для API - имя вызывающей системы.
Requestor-Type	string	нет	Тип витрины. API Web Widget Web Page SDK Apple SDK Android
Requestor-Version	string	нет	Версия виджета/sdk

Тело запроса

Поле	Тип	Обязат.	Описание
serviceId	int64	да	ID сервиса
serviceParams{}	object	нет	Набор пар "параметр":"значение", описывающих реквизиты платежа (специфичных для каждого поставщика)
sessionParams	object	нет	Набор дополнительных настроек платежной сессии
amount	amount	да	Сумма платежа, положительное значение.
amountInfo	object	нет	Данные о суммах оплаты
currency	string[3]	нет	Валюта платежа, по умолчанию 643
description	string[256]	нет	Описание к платежу
extClientId	string[256]	да	Идентификатор пользователя в системе Мерчанта
paymentToolsFilter	object	нет	Набор инструкция для фильтрации ПМ/ПИ
receiptId	int64	нет	id операции фискализации

Описание структуры amountInfo

Поле	Тип	Обяз.	Описание
initialAmount	amount	нет	Исходная сумма оплаты, положительное значение.

Описание структуры sessionParams

Поле	Тип	Обяз.	Описание
lifeTime	int64	нет	Время жизни сессии (в минутах)
requestedCloseAt	datetime (UTC)	нет	Дата и время окончания сессии. Если заполнены оба поля requestedCloseAt и lifeTime, сессия будет завершена в соответствии со значением параметра requestedCloseAt

Описание структуры paymentToolsFilter

Поле	Тип	Обяз.	Описание
allowedPaymentTools	array	нет	Допустимые платежный инструмент mtsBankCard mtsDengiBankCard boundCard newСard

Поле

Тип

Обяз.

Описание

allowedPaymentTools

array

нет

Допустимые платежный инструмент

mtsBankCard
mtsDengiBankCard
boundCard
newСard

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

Заголовок ответа

Content-Type: application/json; charset=utf-8
http-code: 200
http-status: OK

Тело ответа

Поле	Тип	Обяз.	Описание
sessionId	string[32]	да	Идентификатор платежной сессии

Пример

Заголовок запроса

POST https://sandbox.pay.mts.ru/private/v1/payments/sessions/create HTTP/1.1
Host:
Content-Type: application/json
Request-Id: 8df44628-5fe8-40b8-8a2d-e214209a5cae

Тело запроса

{
  "serviceId": "5560",
  "sessionParams": {
    "lifeTime": 14
  },
  "amount": 13.4,
  "currency": "643",
  "extClientId": "89150123456@box.net"
}

{
  "serviceId": "5560",
  "paymentToolsFilter": {
    "allowedPaymentTools": [
      "boundCard"
    ]
  },
  "sessionParams": {
    "lifeTime": 14
  },
  "amount": 13.4,
  "currency": "643",
  "extClientId": "89150123456@box.net"
}

Заголовок ответа

Content-Type: application/json; charset=utf-8
http-code: 200
http-status: OK

Тело ответа

{
  "sessionId": "0b722ef4eb6b4cbe999e1c5bbcb4e456"
}

Возможные коды ошибок

code	message	userMessage
00299998	Validation error	Не пройдена валидация данных
00299999	An unexpected error has occurred	Непредвиденная ошибка
01000002	Inactive merchant	Мерчант не активный
01000003	Service not found	Услуга (serviceId) не найдена
01000004	Service not available	Выбранный сервис недоступен мерчанту
00200037	Payment with pre-authorization is not available for the service	Операция холдирования недоступна для сервиса