Привязка карты

Введение

Представленные ниже методы позволяют привязать карту для последующих оплат.

Привязка карты с подтверждением по 3ds/3ds2

Регистрация карты

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

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

POST
Endpoint: /service/ewallet/card/register HTTP/1.1
Content-Type: application/json
<Основные параметры>

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

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

Тело запроса

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

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

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

Поле	Тип	Обяз.	Описание
number	string	да	Данные платежного инструмента
expiryMonth	int32[2]	да	Месяц действия карты (MM)
expiryYear	int32[4]	да	Год действия карты (YYYY)
cvc	string[3]	да	СVC-код
ownerName	string[200]	нет	Имя держателя карты
mnemonic	string[100]	нет	Мнемоническое имя карты

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

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

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

Тело ответа

Поле	Тип	Обяз.	Описание
sessionId	guid	да	Идентификатор сессии
binding	object	нет	Структура данных привязанной карты
finish3ds	object	нет	Структура данных для подтверждения
finish3ds2	object	нет	Структура данных для подтверждения

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

Поле	Тип	Обяз.	Описание
acsUrl	string	да	URL-адрес банка эмитента (сервер ACS), на который клиент должен быть перенаправлен
PaReq	string	да	Параметр для проведения процедуры 3DSecure
termUrl	string	да	URL-адрес для передачи PaRes от банка эмитента

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

Поле	Тип	Обяз.	Описание
threeDsServerTransId	string	нет	Уникальный идентификатор транзакции 3DS 2.0
threeDsMethodUrl	string	нет	URL 3D Secure метода ACS-сервера эмитента
threeDsMethodData	string	нет	BASE-64 данные для 3D Secure метода

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

Поле	Тип	Обяз.	Описание
bindingId	string[36]	да	Идентификатор способа оплаты
mnemonic	string[100]	да	Мнемоническое имя карты
cardType	string[10]	да	Тип карты
userCardMnemonic	string[100]	да	Составное значение из bindings.maskedPan и bindings.cardType: "MIR *0101"

Пример

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

POST
Endpoint: /service/ewallet/card/register HTTP/1.1
Content-Type: application/json
Request-Id: 83fc026e-ce7f-4f8f-a73a-d093da1726b1

Тело запроса

{
  "ssoTokenId": "00d2a25f-bdd7-49a2-9444-0c167bcac67b.....",
  "card": {
    "number": "5366720491618146",
    "expiryMonth": 7,
    "expiryYear": 2023,
    "cvc": "251",
    "ownerName": "Ivan Ivanov"
  }
}

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

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

Тело ответа

3ds

{
    "sessionId": "0b722ef4eb6b4cbe999e1c5bbcb4e456",
    "binding": {
        "bindingId": "A0000000000000000000000000000002",
        "mnemonic": "карта подписок",
        "cardType": "MIR",
        "UserCardMnemonic": "MIR *0101"
    },
    "finish3ds": {
        "paReq": "eJxVkm1vgjA....",
        "acsUrl": "https://localhost/acs/auth/start.do",
        "termUrl": "https://localhost/acs/confirm/id"
    }
}

3ds 2.0 (со сбором данных о устройстве)

{
    "finish3ds2": {
        "threeDsServerTransId": "string",
        "threeDsMethodUrl": "string",
        "threeDsMethodData": "string"
    }
}

3ds 2.0 (без сбора данных о устройстве)

{
    "finish3ds2": {
        "mdOrder": "215838886711"
    }
}

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

code	message	userMessage
00199998	Validation error	Не пройдена валидация данных
00199999	An unexpected error has occurred	Непредвиденная ошибка
00100002	WEBSSO: Authentication is not taken place	WEBSSO: Аутентификация не пройдена
50200002	It was not succeeded to link the card to a purse, the card is not involved in 3DS	Операция не выполнена. Попробуйте позже
50205002	Card binding after payment is failed	Операция не выполнена. Попробуйте позже
50205004	Processing: Invalid CVC value	Операция не выполнена. Ошибка ввода кода безопасности. Попробуйте снова
50205005	Processing: Invalid card expiration date	Операция не выполнена. Ошибка ввода срока действия карты. Попробуйте снова
50205006	Processing: Invalid card number	Операция не выполнена. Ошибка ввода номера карты. Попробуйте снова
50205007	Processing: The card is already linked on the identifier	Карта ранее была сохранена. Выберите карту из ранее сохраненных.

Передача информации об устройстве

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

Витрина должна создать невидимый iframe, с формой, содержащей поле threeDsMethodData, и автоматически отправить её на threeDsMethodUrl. Это должен быть HTTP POST с Content-Type=application/x-www-form-urlencoded, в теле один параметр threeDsMethodData со значением, полученным от Платежного шлюза в параметре threeDSMethodData (внимание на регистр).

Передача информации о браузере устройства

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

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

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

POST
Endpoint: service/ewallet/cards/3ds2/proceed HTTP/1.1
Content-Type: application/json
Request-Id: {значение}
Session-Id: {значение}
Accept: {значение}
User-Agent: {значение}

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

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

Поле	Тип	Обяз.	Описание
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 [36]	да	Идентификатор платежной сессии
User-Agent	string	да	Содержимое HTTP-заголовка
Accept	string	да	User-Agent браузера, содержимое HTTP-заголовка user-agent

Тело запроса

Поле	Тип	Обяз.	Описание
threeDsRequestorUrl	string (1024)	да	URL адрес ТСП
browserJavaEnabled	boolean	нет	Признак доступности JAVA в браузере клиента, необязательный, если JavaScript недоступен
browserJavascriptEnabled	boolean	да	Признак доступности JavaScript в браузере клиента
browserLanguage	string	да	Язык браузера клиента (свойство navigator.language)
browserColorDepth	Int32	нет	Глубина цвета в браузере клиента: 1, 4, 8, 15, 16, 24, 32, 48. Необязательно, если JavaScript недоступен. Если полученное значение не соответствует одному из разрешенных значений, необходимо осуществить округление в меньшую сторону. Например, если получено значение 30, преобразовываем его в 24
browserScreenHeight	string	нет	Разрешение экрана по высоте в пикселях
browserScreenWidth	string	нет	Разрешение экрана по ширине в пикселях
browserTZ	string	нет	Тайм-зона браузера. Разница во времени между UTC и локальным временем клиента в минутах
challengeWindowSize	string	нет	Размер окна для запроса паролей эмитентом: 01 = 250 x 400; 02 = 390 x 400; 03 = 500 x 600; 04 = 600 x 400; 05 = Полный экран

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

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

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

Тело ответа

Поле	Тип	Обяз.	Описание
sessionId	guid	да	Идентификатор сессии
binding	object	нет	Структура данных привязанной карты
finish3ds2	object	нет	Структура данных для подтверждения

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

Поле	Тип	Обяз.	Описание
acsUrl	string	да	URL-адрес банка эмитента (сервер ACS), на который клиент должен быть перенаправлен
cReq	string	да	Параметр для проведения процедуры 3DSecure

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

Поле	Тип	Обяз.	Описание
bindingId	string[36]	да	Идентификатор способа оплаты
mnemonic	string[100]	да	Мнемоническое имя карты
cardType	string[10]	да	Тип карты
userCardMnemonic	string[100]	да	Составное значение из bindings.maskedPan и bindings.cardType: "MIR *0101"

Пример

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

POST
Endpoint: service/ewallet/cards/3ds2/proceed HTTP/1.1
Content-Type: application/json
Request-Id: 5cdd933a-48d0-4f59-a1a0-3b76f3fae658
Session-Id: d6946779-dd1a-4e91-8e21-e0ddc8a00288
Accept: application/json
User-Agent: okhttp/4.9.0

Тело запроса

{
    "threeDsRequestorUrl": "https://threeDsRequestorUrl/ECB6CA7FA3194C7FAEF5F32D6836939C",
    "browserAcceptHeader": "acceptHeader_ECB6CA7FA3194C7FAEF5F32D6836939C",
    "browserIP": "1.12.123.255",
    "browserJavaEnabled": true,
    "browserJavascriptEnabled": true,
    "browserLanguage": "ru",
    "browserColorDepth": "32",
    "browserScreenHeight": "1920",
    "browserScreenWidth": "1080",
    "browserTZ": "0",
    "browserUserAgent": "browserUserAgent_ECB6CA7FA3194C7FAEF5F32D6836939C",
    "challengeWindowSize": "05"
}

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

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

Тело ответа

{
    "finish3ds2": {
        "сReq": "eJxVkm1vgjA....",
        "acsUrl": "https://localhost/acs/auth/start.do"
    }
}

Ответ для Frictionless flow

{
    "binding": {
        "bindingId": "A0000000000000000000000000000002",
        "mnemonic": "карта подписок",
        "cardType": "MIR",
        "UserCardMnemonic": "MIR *0101"
    }
}

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

code	message	userMessage
00199998	Validation error	Не пройдена валидация данных
00199999	An unexpected error has occurred	Непредвиденная ошибка

Подтверждение

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

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

POST
Endpoint: /service/ewallet/cards/confirm 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 [36]	да	Идентификатор платежной сессии

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

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

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

Тело ответа

Поле	Тип	Обяз.	Описание
paymentToolId	string	да	Идентификатор платежного инструмента, присвоенный шлюзом
bindingId	string[36]	да	Идентификатор способа оплаты
mnemonic	string[100]	да	Мнемоническое имя карты
cardType	string[10]	да	Тип карты
userCardMnemonic	string[100]	да	Составное значение из bindings.maskedPan и bindings.cardType: "MIR *0101"
cardInfo	object	нет	Блок с информацией по ПИ, специфичные для карты
userId	string	нет	Уникальный идентификатор пользователя в ПЦ ЭК

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

Поле	Тип	Обяз.	Описание
maskedPan	string	нет	Маскированный номер карты

Пример

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

POST
Endpoint: /service/ewallet/cards/confirm HTTP/1.1
Content-Type: application/json
Request-Id: 5cdd933a-48d0-4f59-a1a0-3b76f3fae658
Session-Id: d6946779-dd1a-4e91-8e21-e0ddc8a00288

Тело запроса

{}

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

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

Тело ответа

{
    "bindingId": "A0000000000000000000000000000002",
    "mnemonic": "карта подписок",
    "cardType": "MIR",
    "UserCardMnemonic": "MIR *0101"
}

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

code	message	userMessage
00199998	Validation error	Не пройдена валидация данных
00199999	An unexpected error has occurred	Непредвиденная ошибка
00100002	WEBSSOTokenId not valid	WEBSSOTokenId не прошел проверку
00100004	The sequence of operations is broken. {0}	В процессе проведения операции произошла ошибка. Попробуйте позже.
00100005	Missing required header {0}	Отсутствует обязательный заголовок
00100006	Required header has invalid format. {0}	Обязательный заголовок имеет невалидный формат
50205008	Processing: It was not succeeded to confirm	Операция не выполнена. Попробуйте позже.
50205009	Processing: Insufficient funds	Недостаточно средств. Измените способ оплаты и попробуйте снова.