Получение платежных инструментов и информации о платеже

Введение

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

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

Необходимо учитывать, что в разделе получение списка платежных инструментов передается информация обо всех ПИ в электронном кошельке, здесь только те, по которым возможно провести оплату в рамках созданной сессии. Так же позволяет отобразить пользователю информацию о предстоящей оплате.

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

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

POST
Endpoint: /payment/info HTTP/1.1
Content-Type: application/json
Session-Id: {значение}
<Основные параметры>

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

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

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

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

Тело запроса

Поле	Тип	Обяз.	Описание
ssoTokenId	base64	нет	Идентификатор токена МТС Логин (id_token)
ssoCookie	base64	нет	Идентификатор сессии пользователя МТС Логин (значение куки MTSWebSSO)
selectedPaymentTool	object	нет	Объект с данными о предвыбранном платежном инструменте

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

Структура selectedPaymentTool

Поле	Тип	Обяз.	Описание
type	string	да	Предвыбранный тип платежного инструмента
id	string	условно Обязателен, при выборе selectedPaymentTool.type=ewalletBinding	Предвыбранный идентификатор платежного инструмента

Поле

Тип

Обяз.

Описание

type

string

да

Предвыбранный тип платежного инструмента

string

условно

Обязателен, при выборе selectedPaymentTool.type=ewalletBinding

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

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

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

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

Тело ответа

Поле	Тип	Обяз.	Описание
merchantName	string	да	Наименование Мерчанта
serviceName	string	да	Наименование услуги
amount	amount	да	Сумма первого платежа
amountInfo	object	да	Данные о суммах оплаты
scenarioType	string (enum)	да	Тип сценария платежа: payment subscriptionCreate subscriptionCreateDelayed subscriptionPaymentToolUpdate subscriptionRecovery paymentTokenCreate сardTokenCreate preAuthPayment
serviceCategoryType	string(enum)	да	Тип категории оплачиваемой услуги: payment refill
isVerifyPayment	boolean	да	Признак первого платежа: тестовый или обычный (true/false соответственно)
currency	string [3]	да	Валюта платежа
conditions	string	нет	Описания целевого действия клиента на фронт
subscription	object	нет	Наличие данного блока - сообщает, что пользователь оформляет подписку. В блоке представлена информация по регулярным списаниям
paymentMethods	object	да	Структура с информацией по доступным платежным методам
paymentTools	array	да	Структура с информацией по доступным платежным инструментам
loyalty	object	нет	Данные о программе лояльности, которая может быть применена к платежу
payerData	object	нет	Набор данных с параметрами плательщика
userSupportUrl	string	нет	Ссылка на страницу регистрации обращения в службу поддержки

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

Поле	Тип	Обяз.	Описание
merchantMnemonic	string	нет	Наименование подписки на стороне Мерчанта
userMnemonic	string	да	Наименование подписки на стороне Пользователя
amount	amount	да	Сумма платежа по подписке (регулярного списания)
startDate	dateTime	да	Дата и время начала подписки
endDate	dateTime	нет	Дата и время окончания подписки
nextPaymentDate	dateTime	да	Дата и время следующего списания
period	int32	да	Периодичность списания
periodType	periodTypeEnum	да	Единицы периода списания, может принимать значения "day", "week", "month"
trialPeriod	int32	нет	Количество дней триального периода
retryAttemptsQty	int32	нет	Количество попыток повторений, по выполнению проведения платежа
promo	object	нет	Набор параметров отвечающих за промо период подписки

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

Поле	Тип	Обяз.	Описание
amount	amount	да	Сумма при списании в течение промо периода
durationType	durationTypeEnum	да	Тип учета промо, quant или date
period	int34	условно	Кол-во периодов, в течении которого списывается промо сумма
endDate	dateTime	условно	Дата окончания промо периода

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

Поле	Тип	Обяз.	Описание
isAuthUser	boolean	да	Признак авторизации пользователя в сессии через МТС Логин
ssoUserId	guid	нет	Идентификатор пользователя в системе WebSSO. авторизация по id_token: Идентификатор пользователя - значение в параметре sub авторизация по cookie: Идентификатор пользователя - значение в параметре profile:guid
profile	object	нет	Набор данных профиля пользователя

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

Поле	Тип	Обяз.	Описание
isPremiumActive	boolean	да (default=false)	Признак подписки пользователя на Premium.
phone	string[11]	да	Номер телефона авторизованного покупателя
title	string	да	Наименование профиля
subTitle	string	да	Доп информация профиля
type	string (enum)	да	Тип профиля MOBILE - Мобильная связь FIX - Фиксированная связь VIRTUAL - Виртуальный номер LBSV - Региональный интернет и телевидение MGTS - МГТС (интернет и телевидение Москва и частично МО) IOT - IOT-номер GS - Госуслуги UNKNOWN

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

Поле	Тип	Обяз.	Описание
card	object	нет	Структура с параметрами метода оплаты новой картой
sbp	object	нет	Структура с параметрами метода оплаты СБП
sberPay	object	нет	Структура с параметрами метода sberpay

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

Поле	Тип	Обяз.	Описание
needSaveCardCheckboxIsShowed	boolean	да	Признак возможности выбора опции сохранения карты. Для сценариев работы с подписками (subscriptionCreate и subscriptionPaymentToolUpdate) не показываем чекбокс выбора опции сохранения карты. Для сценария оплаты (payment) необходимо взять параметр из конфигурации платежного пакета.
needSaveCardCheckboxIsSelected	boolean	да	Признак для сохранения карты в кошельке. Для сценариев работы с подписками (subscriptionCreate и subscriptionPaymentToolUpdate) всегда сохраняется данные карты. Для сценария оплаты (payment) необходимо взять параметр из конфигурации платежного пакета.
isLoyaltyAvailable	boolean	да	Признак доступности системы лояльности для данного метода оплаты
isBnplAvailable	boolean	да	Признак возможности оплаты этим инструментом в BNPL
order	int32	нет	Порядковый номер для сортировки, по умолчанию 999
toolTipText	string	нет	Описание предложения для вывода у способа оплаты

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

Поле	Тип	Обяз.	Описание
order	int32	да	Порядковый номер для сортировки, по умолчанию 999
isLoyaltyAvailable	boolean	да	Признак доступности системы лояльности для данного метода оплаты
isBnplAvailable	boolean	да	Признак возможности оплаты этим инструментом в BNPL
toolTipText	string	нет	Описание предложения для вывода у способа оплаты

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

Поле	Тип	Обяз.	Описание
isLoyaltyAvailable	boolean	да	Признак доступности системы лояльности для данного метода оплаты. Всегда false
isFiscalDeliveryAvailable	boolean	да	Признак доступности отправки фискального чека. Из настроек Core
isBnplAvailable	boolean	да	Признак возможности оплаты этим инструментом в BNPL. Всегда false
order	int32	да	Порядковый номер для сортировки, по умолчанию 999 .Из настроек Core
isAutoPaymentAvailable	boolean	нет	Признак доступности подключения АП по платежу с использование инструмента. Всегда false

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

Поле

Тип

Обяз.

Описание

string

да

Идентификатор платежного инструмента, присвоенный шлюзом

title

string

нет

Наименование платежного инструмента. Поле mnemonic в платежном инструменте МТС Деньги

complexType

string

да

Тип платежного инструмента

complexType	Описание
mtsBankCard	Привязанная карта МТС банка
mtsDengiBankCard	Привязанная карта банка МТС Деньги (виртуальная)
boundCard	Привязанная банковская карта стороннего банка (не МТС Банк)
mtsCharging	Оплата с лицевого счета через систему ChargingEP
mtsMobileCommerce	Денежные средства на лицевом счете абонента МТС
extMobileCommerce	Оплата с лицевого счета через систему StreamPayments
emoneyAccount	Денежные средства в кошельке МТС Деньги
applePay	Токенизированная карта в системе Apple Pay
googlePay	Токенизированная карта в системе Google Pay
samsungPay	Токенизированная карта в системе Samsung Pay
sbpToken	Привязанный счет системы быстрых платежей
newCard	Непривязанная банковская карта
ewalletBinding	Неизвестный инструмент кошелька.

subTitle

string

нет

Дополнительное наименование платежного инструмента. Поле userCardMnemonic в платежном инструменте МТС Деньги

imageUrl

string

нет

Ссылка на изображение платежного инструмента

cardType

string

нет

Тип карты

isSelected

boolean

нет

Признак что данный ПИ используется у текущей подписки. Для сценариев:

смена ПИ
восстановлении подписки после неуспешных попыток списаний по регулярным платежам

isLoyaltyAvailable

boolean

да

Признак доступности системы лояльности для данного метода оплаты

balance

object

нет

Структура с данными баланса ПИ. Доступно только для mstAccount и chargingEP

order

int32

нет

Порядковый номер для сортировки, по умолчанию 999

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

Поле	Тип	Обяз.	Описание
amount	amount	да	Сумма баланса
currency	string[3]	да	Валюта платежа, по умолчанию 643

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

Поле	Тип	Обяз.	Описание
title	string	нет	Наименование программы лояльности
isUserRegistered	boolean	да	Признак регистрации пользователя в системе программы лояльности
info	object	нет	Параметры программы лояльности

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

Поле	Тип	Обяз.	Описание
cashBackValue	amount	нет	Сумма баллов программы лояльности пользователя, доступная для использования
repaymentRatio	decimal	да	Максимальная часть стоимости покупки, которая может быть покрыта кэшбэком. Минимальное значение: 0. Максимальное значение: 1. Пример: 0.2

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

Поле	Тип	Обяз.	Описание
currentAmount	amount	да	Текущий сумма к оплате
initialAmount	amount	нет	Исходная сумма оплаты

Пример

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

POST
Endpoint: /payment/info HTTP/1.1
Content-Type: application/json
Session-Id: d6946779-dd1a-4e91-8e21-e0ddc8a00288
<Основные параметры> (пример в описании)

Тело

{
  "ssoCookie": "00d2a25f-bdd7-49a2-9444-0c167bcac67b.....",
  "selectedPaymentTool": {
    "type": "ewalletBinding",
    "id": "D61BD4F7F5E64181957DE2DE6A034788"
  }
}

{
  "ssoTokenId": "00d2a25f-bdd7-49a2-9444-0c167bcac67b.....",
  "selectedPaymentTool": {
    "type": "sbp"
  }
}

{
  "ssoTokenId": "00d2a25f-bdd7-49a2-9444-0c167bcac67b....."
}

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

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

Тело

{
  "merchantName": "Самый лучший Провайдер",
  "serviceName": "Самый лучший тариф",
  "serviceCategoryType": "payment",
  "amount": 100.5,
  "amountInfo": {
    "currentAmount": 0,
    "initialAmount": 80.5
  },
  "isVerifyPayment": false,
  "currency": "643",
  "payerData": {<пример_в_описании>},
  "conditions": "ежедневно до 01.01.24, затем 999 ₽",
  "subscription": {
    "merchantMnemonic": "скоростной интернет за сотку",
    "userMnemonic": "инет за сотку",
    "amount": 100.5,
    "startDate": "2020-11-18T19:06:16",
    "endDate": "2021-11-18T19:06:16",
    "nextPaymentDate": "2021-03-26T00:00:00Z",
    "period": 2,
    "periodType": "week",
    "trialPeriod": 3,
    "retryAttemptsQty": 4
  },
  "paymentMethods": {
    "card": {
      "isShowSaveCard": true,
      "needSaveCard": false,
      "isLoyaltyAvailable": true,
      "order": 5
    },
    "sbp": {
      "isLoyaltyAvailable": false,
      "order": 6
    }
  },
  "paymentTools": [
    {
      "id": "c102381950b540d5a964565be5573981",
      "title": "карта подписок",
      "complexType": "boundCard",
      "cardType": "MI R",
      "subTitle": "VISA *0180",
      "imageUrl": "http://localhost/cardsVIsa.png",
      "isLoyaltyAvailable": true,
      "order": 8
    },
    {
      "id": "8df44628-5fe8-40b8-8a2d-e214209a5cae",
      "title": "Карта для игр",
      "complexType": "boundCard",
      "cardType": "MIR",
      "imageUrl": "http://localhost/cards.png",
      "isLoyaltyAvailable": true,
      "order": 11
    }
  ],
  "userSupportUrl": "http://i.love.mts.ru/bestSupport?source=mtspay&id=smth"
}

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

code	message	userMessage
00199997	Operation processing error	Ошибка обработки операции
00199998	Validation error	Не пройдена валидация данных
00199999	An unexpected error has occurred	Непредвиденная ошибка
00100001	Session {0} not found	Сессия не найдена
00100002	WEBSSOTokenId not valid	WEBSSOTokenId не прошел проверку
00100003	The payment is already completed within this session {0}	Платеж уже завершен в рамках этой сессии
00100004	The sequence of operations is broken. {0}	В процессе проведения операции произошла ошибка. Попробуйте позже
00100017	There are no available payment methods	В процессе проведения операции произошла ошибка. Обратитесь в службу поддержки.
00100019	The operation is prohibited for unauthorized users	Операция запрещена для неавторизованных пользователей