Инвестиции
ИНВЕСТИРОВАТЬ С КОНСУЛЬТАНТОМРобот-советникAdvisoryAdvisory PRO
ДОВЕРИТЬ ПРОФЕССИОНАЛАМДоверительное управлениеФонды
Инвестиционная платформа №1
10% годовых в облигациях российских компаний
Подробнее
Прием платежей
ПРИЕМ ОПЛАТЫ В ТОРГОВЫХ ТОЧКАХТорговый эквайрингМобильный эквайринг
ОНЛАЙН-КАССЫВТБ-кассаВТБ-SoftPOS
СИСТЕМА БЫСТРЫХ ПЛАТЕЖЕЙПрием платежей по QR
ЭЛЕКТРОННАЯ КОММЕРЦИЯИнтернет-эквайринг
Моментальная оплата по QR коду без комиссий
Подробнее

Техническая информация о сервисе ВТБ ID

29.12.2023

Группа ВТБ

Описание сценария

Сценарий Web

  1. Клиент выбирает вход через ВТБ ID
  2. Сервис партнера перенаправляет пользователя (браузер) на url адрес ВТБ ID для аутентификации и авторизации: https://id.vtb.ru . Ссылка содержит параметры авторизации партнера, тип запрашиваемого доступа
  3. Пользователь авторизуется на id.vtb.ru и, при необходимости, дает согласие
  4. Результат авторизации — код авторизации. Подробнее в п. Запрос авторизации
  5. Приложение партнера обменивает авторизационный код на access токен и refresh токен в сервисе ВТБ ID. Адрес сервиса: https://id.vtb.ru/oauth2/token . Подробнее в п. Запрос токенов доступа (/oauth2/token). После чего сервис ВТБ ID возвращает access токен и refresh токен
  6. Приложение партнера запрашивает персональные данные пользователя, передавая access токен, подробнее в п. Получение персональных данных пользователя (/oauth2/me). Адрес сервиса: https://gost- id.vtb.ru/oauth2/me . Для получения персональных данных нужно установить КриптоПро CSP, см. документы для скачивания «Инструкция по установке КриптоПро CSP». Access токен имеет ограниченный срок жизни, если нужно повторить запрос персональных данных, приложение партнера должно хранить refresh токен и обновлять access токен после истечения его срока жизни. Подробнее в п. Обновление токенов доступа (refresh_token)
7. Клиент входит на сайт Партнера

Сценарий App

1. Клиент выбирает вход через ВТБ ID 2. Приложение Партнера перенаправляет пользователя в мобильное приложение ВТБ Онлайн по диплинку: https://online.vtb.ru/i/vtbid/ , параметры перечислены в п. Запрос авторизации
3. Пользователь выполняет авторизацию в сервисе ВТБ и, при необходимости, дает согласие на передачу данных
4. Результат авторизации — код авторизации. Приложение ВТБ перенаправляет пользователя в приложение Партнера по диплинку, указанному в параметре redirect_uri и передает код авторизации. Приложение партнера должно уметь обрабатывать диплинки (universal link/deeplink)
5. Приложение партнера должно обменять авторизационный код на access токен и refresh токен в сервисе VTBID, подробнее в п. Запрос токенов доступа (/oauth2/token).
Адрес сервиса: https://id.vtb.ru/oauth2/token . После чего сервис VTBID возвращает access токен и refresh токен
6. Приложение партнёра запрашивает персональные данные пользователя, передавая access токен, подробнее в п. Получение персональных данных пользователя (/oauth2/ me). Адрес сервиса: https://gost-id.vtb.ru/oauth2/me . Для получения персональных данных необходима установка программного обеспечения КриптоПро CSP, см. документы для скачивания «Инструкция по установке КриптоПро CSP». Access токен имеет ограниченный срок жизни, если необходимо иметь возможность повторить запрос персональных данных, приложение партнёра должно хранить refresh токен и обновлять access токен после истечения его срока жизни. Подробнее в п. Обновление токенов доступа (refresh_token)
7. Клиент входит в приложение Партнера

Описание запросов

Параметр client_id
Уникальный идентификатор приложения партнера. Выдается ВТБ при регистрации приложения партнера, как пользователя сервиса ВТБ ID
Обязательно
Параметр response_type
Указывает, какой сценарий авторизации использовать. Поддерживаемое значение — code
Обязательно
Параметр redirect_url
URL адрес, на который произойдет перенаправление пользователя после завершения авторизации (успешно или неуспешно). Этот URL должен быть внесен в список допустимых при регистрации приложения партнера. Если при регистрации приложения был указан адрес https://example.com/auth, то при авторизации должно быть передано такое же значение: redirect_uri=https://example.com/auth
Обязательно
Параметр state
Параметр для защиты от CSRF атак. Подробнее см. RFC-6749
Не обязательно
Параметр scope
Разделенный пробелами список разрешений (области разрешений), для который требуется авторизация. Это может быть доступ к определённым данным профиля пользователя, перечень доступных данных см. в документах для скачивания «Данные пользователя». Запросить можно только те данные, которые были зарегистрированы в сервисе ВТБ ID для Партнера
Обязательно

Успешный ответ:

  • Перенаправление на адрес redirect_uri с параметрами код авторизации и state
  • Для app2app приложение ВТБ попытается открыть http ссылку. Приложение Партнера должно обработать universal link/deeplink и перевести пользователя на заданную в ссылке страницу
Пример ссылки:
Параметр code
Код авторизации (результат успешного завершения сценария авторизации). Код необходимо обменять на токены доступа
Обязательно
Параметр state
Значение параметра state, которое было отправлено в запросе на авторизацию
Обязательно
Параметр error
Тип ошибки, с которым завершился процесс авторизации. Описание ошибок см. в документах для скачивания «Перечень ошибок»
Обязательно
Параметр error_message
Краткое описание ошибки
Не обязательно

2. Запрос токенов доступа (/oauth2/token)

Запрос выполняет обмен кода авторизации на токены доступа
Пример обмена кода авторизации на токены доступа: curl --location --request POST 'https: //id.vtb.ru/oauth2/token' \ --header 'Authorization: Basic YXRGb3BIWWZxRHFUd3BjTHlfdFdSWnhHbWdrYToyczNmTGFGX2tIMjVQX1E2ZkM1WXVTUHhU Mm9h' \
--header 'Content-Type: application/json' \
--data-raw '{
"grant_type": "code", 

"code": "83ca5003-a384-4858-8dca-20be4cd5eb36"
}'
Параметр grant_type
Согласно спецификации Oauth2, должно содержать значение "code"
Обязательно
Параметр code
Код авторизации, полученный на шаге авторизации или при редиректе из приложения ВТБ (в диплинке при переходе из мобильного приложения ВТБ)
Обязательно
Параметр Authorization
base64 закодированная строка, которая содержит clientId и client secret выданные партнеру на этапе регистрации приложения в ВТБ ID. Поле имеет формат: Authorization: Basic <base64 encoded client_id:client_secret>
Обязательно

Успешный ответ:

{
"scope": "openid",
"access_token": "006fad70-c36c-4995-82e0-99cd86bc0c72",
"refresh_token": "91179b52-9a6e-4601-840d-bc518b796e87",
"id_token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxMzcwNTA2MSIsImF1ZCI6ImF0Rm9wSFlmcURxV HdwY0x5X3RXUlp4R21na2EiLCJhenAiOiJhdEZvcEhZZnFEcVR3cGNMeV90V1JaeEdtZ2thIiwic3Bfb mFtZSI6InZ0Yi1nYW1lLW1hc3RlcmNhcmQiLCJpc3MiOiJodHRwczovL2lkLnZ0Yi5ydSIsIm5iZiI6MT YzNDIwMjQ1MiwiaWF0IjoxNjM0MjAyNDUyLCJleHAiOjE2MzQyMDI3NTIsImFtciI6WyJjb2RlIl0sIm FjciI6Im1zYT1leUpZTFZWelpYSXRVMlZ6YzJsdmJpMUpSQ0k2SWpaalpUTTRZamRpTFRNeFl6UXR OR1UxWmkwNU0yRXhMVGxqWkRBeE4yTmpZekZsTkNJc0luSnZkWFJsVG1GdFpTSTZJa1JKVTBG VFZFVlNJaXdpYzJoaGNtUk9ZVzFsSWpvaVJFbFRRVk5VUlZJaUxDSllMVkpQVlZSRkxVNUJUVVVpT 2lKRVNWTkJVMVJGVWlJc0lsZ3RVMGhCVWtRdFRrRk5SU0k2SWtSSlUwRlRWRVZTSWl3aVdDMU VaV0oxWnlJNkltWmhiSE5sSWl3aVdDMUpibWwwYVdGMGIzSXRTRzl6ZENJNklrNHZRU0lzSWxnd FEyaGhibTVsYkNJNklrMXZZbWxzWlVKaGJtc3lJaXdpV0MxUWJHRjBabTl5YlNJNkluZGxZaUlzSW xndFRHOW5hVzR0VFc5a1pTSTZiblZzYkN3aVdDMVdaWEp6YVc5dUlqcHVkV3hzZlE9PSIsImF1dG hvcml6YXRpb25faWQiOiI4ZWVmNWY1MS03M2U0LTRkNDgtYjIyOS1jMGQ1MTJiOTdmNzEiLCJkb 21haW4iOiJtYXN0ZXIiLCJtc2Ffc2Vzc2lvbl9pZCI6IjZjZTM4YjdiLTMxYzQtNGU1Zi05M2ExLTljZDAxN 2NjYzFlNCJ9.T27T0VkR0gMAADQKeAJLXUVzPJsS88GQ51LKW072GGaG793rj0gQu2cyz_b3xyzu7 IgzAVHjCQFGzfoedSZtBKNkq0n540ekf8oq66rK_7P3RKcEvVUrLKt1LY5sw5XgW8E3LhX4un7AIHJ xLVmofRBUbuWJskvO8qX7zeic6CktFEBJHeO b25entEtfksYQnbr6cvQKKC6NMoVtKSqZgLQaRbVcx8GoX9lGGPm PH9ZjLNH7mWU0XIhLKc4VVjud67S58dZHf34ib_ OzNXYrvuPwGor3ZS4-xL5atPxbENBZ0vIrggnxhWDHI0sBHaVnOvms Q4e6Atx1fTbDQOw"
Параметр scope
Список разрешений, для которых действуют выданные токены
Обязательно
Параметр access_token
Токен доступа. Представляет собой уникальное значение определённого формата. Токен используется для доступа к VTBID API. Имеет ограниченное время жизни
Обязательно
Параметр refresh_token
Токен обновления. Требуется для получения новых токенов доступа. Одноразовый
Обязательно
Параметр id_token
Пользовательский JWT токен, который содержит некоторую информацию о пользователе. В частности, может использоваться для доступа к внутренним сервисам ВТБ и генерируется только при запросе разрешения openid
Не обязательно

Ошибка:

{
"error": "invalid_grant",

"error_message": "No authorization code found"
}
Параметр error
Тип ошибки, с которым завершился запрос
Обязательно
Параметр error_message
Краткое описание ошибки
Не обязательно

3. Обновление токенов доступа (refresh_token)

Токены доступа имеют ограниченное время жизни. Если нужно продлить доступ к API после истечения срока действия токена, можете использовать токен обновления, полученный на этапе авторизации, выполнив запрос к /oauth2/token
Пример: curl --location --request POST 'https:// id.vtb.ru/oauth2/token' -- header 'Authorization: Basic YXRGb3BIWWZxRHFUd3BjTHlfdFdSWnhHbWdrYToyczNmTGFGX2t IMjVQX1E2ZkM1WXVTUHhUMm9h'
\
--header 'Content-Type: application/json' \
--data-raw '{
"grant_type": "refresh_token",

 "refresh_token": "91179b52-9a6e-4601-840d-bc518b796e87"
Параметр Authorization
base64 закодированная строка, которая содержит clientId и client secret, выданные партнеру на этапе регистрации приложения в VTBID. Поле имеет формат: Authorization: Basic <base64 encoded client_id:client_secret>
Обязательно
Параметр grant_type
Значение refresh_token
Обязательно
Параметр refresh_token
Токен обновления, полученный ранее на этапе запроса или обновления токенов
Обязательно

Успешный ответ:

{ "scope": "openid", "access_token": "006fad70-c36c-4995-82e0-99cd86bc0c72",
"refresh_token": "91179b52-9a6e-4601-840d-bc518b796e87", "id_token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxMzcwNTA2MSIsImF1ZCI6ImF0Rm9wSFlmcURxV HdwY0x5X3RXUlp4R21na2EiLCJhenAiOiJhdEZvcEhZZnFEcVR3cGNMeV90V1JaeEdtZ2thIiwic3Bfb mFtZSI6InZ0Yi1nYW1lLW1hc3RlcmNhcmQiLCJpc3MiOiJodHRwczovL2lkLnZ0Yi5ydSIsIm5iZiI6MT YzNDIwMjQ1MiwiaWF0IjoxNjM0MjAyNDUyLCJleHAiOjE2MzQyMDI3NTIsImFtciI6WyJjb2RlIl0sIm FjciI6Im1zYT1leUpZTFZWelpYSXRVMlZ6YzJsdmJpMUpSQ0k2SWpaalpUTTRZamRpTFRNeFl6UXR OR1UxWmkwNU0yRXhMVGxqWkRBeE4yTmpZekZsTkNJc0luSnZkWFJsVG1GdFpTSTZJa1JKVTBG VFZFVlNJaXdpYzJoaGNtUk9ZVzFsSWpvaVJFbFRRVk5VUlZJaUxDSllMVkpQVlZSRkxVNUJUVVVpT 2lKRVNWTkJVMVJGVWlJc0lsZ3RVMGhCVWtRdFRrRk5SU0k2SWtSSlUwRlRWRVZTSWl3aVdDMU VaV0oxWnlJNkltWmhiSE5sSWl3aVdDMUpibWwwYVdGMGIzSXRTRzl6ZENJNklrNHZRU0lzSWxn dFEyaGhibTVsYkNJNklrMXZZbWxzWlVKaGJtc3lJaXdpV0MxUWJHRjBabTl5YlNJNkluZGxZaUlzSW xndFRHOW5hVzR0VFc5a1pTSTZiblZzYkN3aVdDMVdaWEp6YVc5dUlqcHVkV3hzZlE9PSIsImF1dG hvcml6YXRpb25faWQiOiI4ZWVmNWY1MS03M2U0LTRkNDgtYjIyOS1jMGQ1MTJiOTdmNzEiLCJkb 21haW4iOiJtYXN0ZXIiLCJtc2Ffc2Vzc2lvbl9pZCI6IjZjZTM4YjdiLTMxYzQtNGU1Zi05M2ExLTljZDAxN 2NjYzFlNCJ9.T27T0VkR0gMAADQKeAJLXUVzPJsS88GQ51LKW072GGaG793rj0gQu2cyz_b3xyzu7 IgzAVHjCQFGzfoedSZtBKNkq0n540ekf8oq66r K_7P3RKcEvVUrLK t1LY5sw5XgW8E3LhX4un7AIHJxLVmofRBUbu WJskvO8qX7zeic6 CktFEBJHeOb25entEtfksYQnbr6cvQKKC6NMo VtKSqZgLQaRbVcx 8GoX9lGGPmPH9ZjLNH7mWU0XIhLKc4V Vjud67S58dZHf34ib_OzNXYrvuPwGor3ZS4- xL5atPxbENBZ0vIrggnxhWDHI0sBHa VnOvmsQ4e6Atx1fTbDQOw"
Параметр scope
Список разрешений, для которых действуют выданные токены
Обязательно
Параметр access_token
Токен доступа. Представляет собой уникальное значение определённого формата. Токен используется для доступа к VTBID API. Имеет ограниченное время жизни
Обязательно
Параметр refresh_token
Токен обновления. Требуется для получения новых токенов доступа. Одноразовый
Обязательно
Параметр id_token
Пользовательский JWT токен, который содержит некоторую информацию о пользователе. В частности, может использоваться для доступа к внутренним сервисам ВТБ и генерируется только при запросе разрешения openid
Не обязательно

Ошибка:

{
"error": "invalid_grant", "error_message": "No authorization code found"
}

4. Запрос на получение персональных данных пользователя (/oauth2/me)

Метод позволяет получить персональные данные клиента ВТБ. Для доступа используется access токен, полученный на этапе авторизации
Пример: curl -X GET "https:// gost-id.vtb.ru/oauth2/me?
scopes=name%20surname"
-H "accept: application/json"
-H "Authorization: Bearer a0b592b6-2d41-4ff9-9a7a-
11c7e831225a
Параметр scopes
Разделенный пробелами список разрешений (данных пользователя). Перечень доступных данных см. в документах для скачивания «Данные пользователя». Запросить можно только те данные, которые были зарегистрированы в сервисе ВТБ ID для Партнера. При отсутствии параметра возвращается весь список разрешений, которые были запрошены при регистрации Партнера
Не обязательно
Параметр Authorization
Bearer + access_token, полученный на шаге запроса токенов
Обязательно

Успешный ответ:

"surname": "Иванов",
"name": "Иван",
"patronymic": "Иванович",
"gender": "M",
"birthPlace": "г. Курск",
"birthDate": "2021-10-14",
"maritalStatus": "SINGLE",
"mainMobilePhone": "79201234567",
"mobilePhone": "79201234567",
"email": "iivanov@gmail.com",
"registrationAddress": {
"addressName": "123456, Россия, Москва, 
ул.Ленина, 23, 3, 234" }, "temporaryAddress": {
"addressName": "123456, Россия, Москва, ул.Ленина, 23, 3, 234" }, "actualAddress": {
"addressName": "123456, Россия, Москва, ул.Ленина, 23, 3, 234" }, "snils": "111-222-333 33", "inn": "7721357717689",
"rfPassport": { "series": "5414",
"number": "435685",
"issueDate": "2013-06-03",
"departmentDoc": "ГУВМ МВД России",
"lastName": "Иванов",
"firstName": "Иван",
"middleName": "Иванович",
"gender": "M",
"birthDate": "2000-05-06",
"birthPlace": "г. Курск",
"issuedBy": "Гагаринским отделением полиции №5 по г. Москве МВД России", "issueId": "540-056" }, "userId": "09B360E5D0F094D9EB48DD70F8827D72"
Параметр surname
Фамилия
Не обязательно
Параметр name
Имя
Не обязательно
Параметр patronymic
Отчество
Не обязательно
Параметр gender
Пол
Не обязательно
Параметр birthPlace
Место рождения
Не обязательно
Параметр birthDate
Дата рождения
Не обязательно
Параметр maritalStatus
Семейное положение
Не обязательно
Параметр mainMobilePhone
Основной номер телефона
Не обязательно
Параметр mobilePhone
Номер телефона
Не обязательно
Параметр email
Адрес электронной почты
Обязательно
Параметр registrationAddress
Адрес регистрации (по паспорту)
Не обязательно
Параметр temporaryAddress
Адрес временного проживания
Не обязательно
Параметр actualAddress
Адрес фактического проживания
Не обязательно
Параметр snils
Номер СНИЛС
Не обязательно
Параметр inn
Номер ИНН
Не обязательно
Параметр rfPassport
Номер Данные паспорта РФ
Не обязательно
Параметр userId
Идентификатор пользователя
Не обязательно

Ошибка:

{
"error": "invalid_scope",

"error_message": "Недопустимый список разрешений"

}
Параметр error
Тип ошибки, с которым завершился процесс авторизации. Описание ошибок см.в документах для скачивания «Перечень ошибок»
Обязательно
Параметр error_message
Краткое описание ошибки
Не обязательно

Дизайн кнопки

Описали дизайн и тексты для кнопки аутентификации пользователей по ВТБ ID

Термины и сокращения

API
Application Programming Interface — сервисный контракт между двумя приложениями, который определяет, как они взаимодействуют друг с другом, используя запросы и ответы
Банк
Банк ВТБ (ПАО)
Партнер банка
Организация, заключившая договор с банком в целях использования сервиса VTBID
Банк
Банк ВТБ (ПАО)
Пользователь
Клиент банка
VTBID
Сервис, который Банк предоставляет Партнеру
JWT
JSON Web Token — открытый стандарт (RFC 7519) для создания токенов доступа, основанный на формате JSON
universal link/deeplink
Ссылка, по которой пользователь сразу попадает в конкретный раздел приложения
Код авторизации
Уникальный набор символов (UUID/GUID), результат успешной аутентификации пользователя с помощью сервиса VTBID. Код авторизации связан с результатом аутентификации пользователя и согласием на предоставление данных пользователя банком Партнеру. Код авторизации одноразовый и имеет короткий срок действия.
Access токен, токен доступа
Уникальный набор символов (UUID/GUID). Предоставляется банком Партнёру в обмен на Код авторизации. Обеспечивает доступ к API VTB ID для получения персональных данных Пользователя. Имеет ограниченный срок действия.
Refresh токен, токен обновления
Уникальный набор символов (UUID/GUID). Используется для получение новой пары access и refresh токенов. Имеет ограниченный срок действия.
ID token
JWT токен, содержащий информацию о пользователе
Scope
Идентификатор запрашиваемого ресурса или операции. Например перечень персональных данных Пользователя, которые необходимо получить.
КриптоПро CSP
Комплекс программных средств для реализации механизмов хранения ключей и сертификатов с поддержкой ГОСТ Р 34.10-2012

Вопросы и ответы

Сколько займет подключение ВТБ ID?

Настроить интеграцию можно за 1 день. Все зависит от количества сценариев.

Где посмотреть дополнительную информацию про ВТБ ID?

Бизнес-описание и этапы подключения можете посмотреть тут

Что делать, если заявка не отправляется?

Напишите нам на почту id@vtb.ru

Техническая документация

Оставьте заявку прямо сейчас

Получите консультацию и начните интеграцию