ПОСТАНОВЛЕНИЕ ПРАВЛЕНИЯ НАЦИОНАЛЬНОГО БАНКА РЕСПУБЛИКИ БЕЛАРУСЬ
26 августа 2022 г. № 314
Об утверждении стандартов проведения расчетов
Изменения и дополнения:
Постановление Правления Национального банка Республики Беларусь от 11 января 2023 г. № 8 (Национальный правовой Интернет-портал Республики Беларусь, 02.03.2023, 8/39546) <B22339546p>;
Постановление Правления Национального банка Республики Беларусь от 30 сентября 2025 г. № 286 (Национальный правовой Интернет-портал Республики Беларусь, 10.10.2025, 10-3/6088) <B22506088p>
На основании абзаца шестьдесят восьмого статьи 26 и части первой статьи 39 Банковского кодекса Республики Беларусь Правление Национального банка Республики Беларусь ПОСТАНОВЛЯЕТ:
1. Утвердить:
стандарт проведения расчетов СПР 6.02-1-2022 «Банковская деятельность. Информационные технологии. Открытые банковские API. Платежные API. Спецификация» (прилагается);
стандарт проведения расчетов СПР 6.02-2-2022 «Банковская деятельность. Информационные технологии. Открытые банковские API. Платежные API. Информационная безопасность» (прилагается).
2. Настоящее постановление вступает в силу после его официального опубликования.
Председатель Правления | П.В.Каллаур |
| УТВЕРЖДЕНО Постановление Правления |
СТАНДАРТ ПРОВЕДЕНИЯ РАСЧЕТОВ
СПР 6.02-1-2022 «Банковская деятельность. Информационные технологии. Открытые банковские API. Платежные API. Спецификация»
Раздел I
Общие положения
1. Настоящий стандарт проведения расчетов (далее – стандарт) устанавливает требования к открытым платежным банковским интерфейсам программирования приложений (интерфейсам прикладного программирования, API) (далее, если не указано иное, – API), методам и параметрам API, посредством которых предоставляется:
1.1. получение информации о банковском счете (далее – счет) (счетах) клиента:
создание и получение статуса согласия для получения информации о счете (счетах) клиента;
удаление (отзыв) согласия на получение информации о счете (счетах) клиента;
получение информации о счете (счетах);
получение информации о балансе счета (всех счетов);
создание выписки по счету и получение выписки по счету по созданному идентификатору выписки;
создание перечня транзакций по счету и получение перечня транзакций по счету по созданному идентификатору списка транзакций;
1.2. инициирование платежей:
создание и получение статуса согласия на инициирование всех видов платежей;
создание и получение статуса платежного указания на инициирование платежа плательщиком за товары, работы, услуги;
создание и получение статуса платежного указания на инициирование платежа плательщиком в бюджет;
создание и получение статуса платежного указания на инициирование платежа плательщиком, содержащего список бенефициаров с указанием счетов бенефициаров;
создание и получение статуса платежного указания на инициирование платежа плательщиком, содержащего список бенефициаров при осуществлении перевода без открытия счета;
создание и получение статуса платежного указания на инициирование платежа бенефициаром за товары, работы, услуги;
создание и получение статуса платежного указания на инициирование платежа бенефициаром (взыскателем) в бюджет;
создание и получение статуса платежного указания на инициирование платежа из состава рекуррентных платежей;
отзыв платежного указания на инициирование всех видов платежей.
2. Настоящий стандарт предназначен для участников экосистемы открытого банкинга с целью реализации процессов на этапе разработки API. Настоящий стандарт не распространяется на инициирование платежей посредством программно-технической инфраструктуры, предназначенной для приема банковских платежных карточек на физическом носителе.
3. Настоящий стандарт применяется совместно со стандартом проведения расчетов СПР 6.01-2020 «Банковская деятельность. Информационные технологии. Открытые банковские API. Регламент взаимодействия поставщиков API и пользователей API», утвержденным постановлением Правления Национального банка Республики Беларусь от 31 декабря 2019 г. № 552 (далее – СПР 6.01).
4. В настоящем стандарте используются термины в значениях, установленных в нормативных правовых актах Национального банка, в том числе принятых совместно с иными государственными органами, СПР 6.01, а также следующие термины и их определения:
долгосрочное согласие – согласие, которое предоставляется клиентом на стороне поставщика API для осуществления обмена данными между пользователем API и поставщиком API на длительный срок (не более трех лет);
краткосрочное согласие – однократное согласие, которое предоставляется клиентом на стороне поставщика API для осуществления обмена данными между пользователем API и поставщиком API на инициирование только одного платежа;
идемпотентность – свойство объекта или операции при повторном применении операции к объекту давать тот же результат, что и при первом;
открытый банкинг – комплекс подходов к предоставлению банковских услуг, основанный на простом, удобном, эффективном, мгновенном и безопасном способе оказания пользователям таких услуг, в том числе посредством предоставления их юридическим лицам, не являющимся финансовыми организациями, доступа к информации о банковских услугах и клиентах банков в соответствии с требованиями, установленными законодательством;
пагинация – механизм разбивки списка записей на страницы при предоставлении больших наборов данных через API;
полезная нагрузка – часть пакета данных (сообщения) без служебной информации (без заголовка, битов синхронизации иной служебной информации);
пользователь API второго типа – юридическое лицо, использующее API для предоставления услуг клиентам, получающий монетизацию за счет дополнительных сервисов поставщиков API;
пользователь API первого типа – клиент, использующий API в личных целях, а также для получения конкурентных преимуществ в процессе последующего производства товаров, выполнения работ, оказания услуг (без непосредственного использования API для оказания услуг клиентам);
поставщик информационных платежных услуг – пользователь API второго типа, предоставляющий клиенту услугу получения информации о счете (счетах) клиента;
поставщик платежных услуг инициирования платежа – пользователь API второго типа, предоставляющий клиенту услугу инициирования перевода денежных средств;
рекуррентный платеж – платеж, инициируемый с определенной периодичностью пользователем API второго типа на основании предоставленного ему согласия клиента посредством использования реквизитов счета клиента;
ресурс – любая сущность (платеж, счет, транзакция) в определенном формате (JSON или ином). Каждый ресурс идентифицируется посредством постоянного идентификатора, который не меняется при изменении состояния ресурса;
согласие – согласие клиента на предоставление данных клиента, данных, необходимых для проведения транзакций клиента, на инициирование платежа клиента пользователю API второго типа от поставщика API и/или на передачу данных пользователю API второго типа поставщику API от имени клиента, выраженное в письменной форме лично поставщику API, либо согласие, представленное поставщику API в электронном виде с применением программно-аппаратных средств и технологий, позволяющих достоверно установить, что оно исходит от соответствующих лиц;
токен доступа – свидетельство, представляющее авторизацию, выданную клиенту сервером авторизации с одобрения владельца ресурса. Токен доступа содержит указание на конкретные области действия, к которым разрешен доступ, длительность доступа и другие параметры;
экосистема открытого банкинга – взаимосвязанная группа лиц, взаимодействующих в процессе создания, реализации, использования и вывода из эксплуатации открытых API для достижения взаимовыгодных целей, непосредственно сами открытые API, а также программные продукты, внедряемые при их использовании.
В настоящем стандарте используются следующие обозначения:
О – наличие компонента и (или) элемента данных обязательно;
Н – наличие компонента и (или) элемента данных необязательно;
У – наличие компонента и (или) элемента данных определяется по условию;
DELETE – метод HTTP для удаления указанного ресурса;
GET – метод HTTP для запроса содержимого указанного ресурса;
HTTPS – расширение протокола HTTP для поддержки шифрования в целях повышения безопасности;
JSON – текстовый формат обмена данными, основанный на JavaScript;
OAuth 2.0 – открытый протокол (схема) авторизации, который позволяет предоставить пользователю API ограниченный доступ к защищенным ресурсам клиента без необходимости передавать ему (пользователю API) логин и пароль;
POST – метод HTTP для отправки содержимого указанного ресурса на сервер;
REST – архитектурный стиль взаимодействия компонентов распределенного приложения в сети. REST представляет собой согласованный набор ограничений, учитываемых при проектировании распределенной системы;
XML – расширяемый язык разметки, определяющий набор правил для кодирования документов в формате, который удобен для чтения как человеком, так и компьютером.
5. Для API определена архитектура, соответствующая концепции RESTful API.
6. Для обеспечения структурного контроля сообщений на физическом уровне применяются JSON-схемы соответствующих электронных сообщений.
7. Текст сообщения должен быть сформирован в кодовой странице UTF-8.
8. Участники экосистемы открытого банкинга взаимодействуют согласно логической структуре. Структура взаимодействия участников в случае участия пользователя API второго типа представлена на рисунке 1.
Рисунок 1
Структура взаимодействия участников в случае участия пользователя API первого типа представлена на рисунке 2.
Рисунок 2
9. Клиент предоставляет долгосрочное согласие поставщику API для осуществления обмена данными между пользователем API второго типа и поставщиком API в рамках согласия на длительный срок (не более трех лет). В любой момент клиент может отозвать долгосрочное согласие как через открытые API, так и через предоставляемые средства поставщика API.
10. Клиент предоставляет краткосрочное согласие поставщику API для инициирования платежа.
11. Поставщик API при применении настоящего стандарта руководствуется банковским законодательством, законодательством об информации, информатизации и защите информации, в том числе о персональных данных.
Раздел II
Общие требования к API
Глава 1
Требования к элементам данных
12. Разрешенное к использованию символьное множество элементов данных включает в себя следующий набор символов:
A…Z – прописные латинские буквы;
a…z – строчные латинские буквы;
А…Я – прописные буквы кириллицы, включая I, Ё и Ў;
а…я – строчные буквы кириллицы, включая i, ё и ў;
0…9 – цифры;
/ \ – + = _ . , : ; ' ‘ ’ ‘‘ ’’ « » ~ ! @ # № $ % ^ ? * ( ) [ ] { } – специальные графические символы: пробел, дробная черта правая и левая, дефис (минус), плюс, равно, нижнее подчеркивание, точка, запятая, двоеточие, точка с запятой, апостроф, одиночные, парные и угловые кавычки (левые и правые), тильда, восклицательный знак, коммерческое at, решетка, знак номера, знак доллара, процент, карет, знак вопроса, звездочка, круглые, квадратные и фигурные скобки (левые и правые).
Десятичные числа указываются в следующем формате: m<=decimal<=M td=T fd=F, где m – минимальное значение, M – максимальное значение, Т – общее количество цифр, F – количество цифр в дробной части.
13. Обозначения размерности заключаются в фигурные скобки и указываются после перечисления допустимых символов:
{m} – точно m символов;
{m,n} – не менее чем m символов, но не более чем n символов;
text{m,n} – минимальная (m) и максимальная (n) длина текстового элемента данных, состоящего из разрешенного набора символов.
14. Для указания кратности повторений (или множественности) компонентов или элементов данных используются обозначения, заключаемые в квадратные скобки [ ]:
[1..1] – элемент данных обязателен, повторения не допускаются;
[1..*] – элемент данных обязателен, может повторяться без ограничений;
[1..n] – элемент данных обязателен, может повторяться не более n раз (n > 1);
[m..*] – элемент данных обязателен, должен повторяться не менее m раз (m > 1);
[m..n] – элемент данных обязателен, должен повторяться не менее m раз и не более n раз (m > 0, n > m);
[0..1] – элемент данных необязателен, повторения не допускаются;
[0..n] – элемент данных необязателен, может повторяться не более n раз (n > 1).
Если кратность повторения компонента или элемента данных не указана, то они заполняются однократно.
15. Необязательная часть значения элемента данных заключается в круглые скобки, после которых ставится знак вопроса «?», например: [A-Z0-9]{9}([A-Z]{3})?.
16. В API используются основные элементы данных и компоненты, формат которых является одинаковым для всех API, если об этом не указано отдельно в описании конкретного API.
16.1. Элемент данных «Наименование».
Элемент данных «Наименование» (name) должен содержать краткое наименование банка, организации или фамилию, собственное имя и отчество (при наличии) физического лица или наименование описываемого компонента.
Элемент данных «Наименование» имеет неструктурированный тип данных Max140Text.
16.2. Элемент данных «Международный номер банковского счета».
Элемент данных «Международный номер банковского счета» должен соответствовать требованиям государственного стандарта Республики Беларусь СТБ ISO 13616-1-2015 «Финансовые услуги. Международный номер банковского счета (IBAN). Часть 1. Структура IBAN», утвержденного постановлением Государственного комитета по стандартизации Республики Беларусь от 7 октября 2015 г. № 47.
Элемент данных «Международный номер банковского счета» для номера банковского счета, открытого в банке-участнике системы BISS, за исключением банков-нерезидентов Республики Беларусь, имеет тип данных IBAN2007Identifier и формат фиксированной длины, равный 28 символам: [A-Z]{2}[0-9]{2}[A-Z0-9]{4}[0-9]{4}[A-Z0-9]{16}, где:
[A-Z]{2} – международный код страны согласно справочнику N013 (таблица 80);
[0-9]{2} – контрольные цифры номера банковского счета, которые используются для проверки его достоверности и вычисляются согласно СТБ ISO 13616-1-2015;
[A-Z0-9]{4} – первые четыре символа банковского идентификационного кода банков, их филиалов;
[0-9]{4} – балансовый счет согласно плану счетов бухгалтерского учета;
[A-Z0-9]{16} – номер индивидуального счета.
Элемент данных «Международный номер банковского счета» для номера банковского счета, открытого в банке-нерезиденте Республики Беларусь, имеет тип данных IBAN2007Identifier и формат: [A-Z]{2}[0-9]{2}[a-zA-Z0-9]{1,30}.
16.3. Элемент данных «Зарегистрированный код BIC».
Элемент данных «Зарегистрированный код BIC» должен соответствовать требованиям государственного стандарта Республики Беларусь СТБ ISO 9362-2015 «Банковская деятельность. Сообщения, передаваемые по каналам связи. Бизнес-идентификационные коды (BIC)», утвержденного постановлением Государственного комитета по стандартизации Республики Беларусь от 7 октября 2015 г. № 47.
Элемент данных «Зарегистрированный код BIC» (BICFI) банков-участников системы BISS имеет формат [A-Z0-9]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?, где:
[A-Z0-9]{4} – цифробуквенный код, однозначно идентифицирующий банк Республики Беларусь, банк-нерезидент (префикс бизнес-участника);
[A-Z]{2} – буквенный код страны согласно справочнику N013 (таблица 80);
[A-Z0-9]{2} – цифробуквенный код местоположения участника расчетов (суффикс бизнес-участника);
[A-Z0-9]{3} – необязательные разряды, которые могут содержать значение условного номера участника расчетов, который используется только для идентификации филиалов.
Элемент данных «Зарегистрированный код BIC» (BICFI) банков не участников системы BISS имеет формат [A-Z0-9]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?.
16.4. Элементы данных, содержащие значения суммы, валюты, обменного курса денежных средств и процентов.
Элементы данных, содержащие значения сумм денежных средств (amount, chargeAmount, balanceAmount и т.д.), должны иметь формат 0<=decimal td=18 fd=5 и формироваться в соответствии со следующими правилами:
значение состоит из целой части, разделителя и дробной части;
в качестве разделителя целой и дробной частей используется символ «.» (точка);
общее количество цифр не должно превышать 18, разделитель не учитывается;
целая часть должна содержать хотя бы одну цифру;
в целой части ноли перед первой значащей цифрой отсутствуют;
дробная часть указывается, если в данной валюте она присутствует;
количество цифр в дробной части суммы не может превышать пяти и должно соответствовать общегосударственному классификатору Республики Беларусь ОКРБ 016-99 «Валюты», утвержденному постановлением Государственного комитета по стандартизации, метрологии и сертификации Республики Беларусь от 16 июня 1999 г. № 8 (далее – ОКРБ 016);
если дробная часть в данной валюте присутствует и равна нолю, то количество символов «0» в дробной части должно быть равно максимально допустимому количеству знаков в дробной части для данной валюты, например: 126.00.
Значения сумм денежных средств, представленных в белорусских рублях (amount, equivalentAmount, balanceEquivalentAmount и т.д.), должны иметь формат 0<=decimal td=18 fd=2.
Элементы данных, содержащие значения обменного курса валют (exchangeRate), должны иметь формат 0<=decimal td=11 fd=10 и формироваться в соответствии со следующими правилами:
значение состоит из целой части, разделителя и дробной части;
в качестве разделителя целой и дробной частей используется символ «.» (точка);
общее количество цифр не должно превышать 11, разделитель не учитывается;
целая и дробная части должны содержать хотя бы одну цифру;
в целой части ноли перед первой значащей цифрой отсутствуют;
в дробной части ноли после последней значащей цифры отсутствуют.
Курс белорусского рубля указывается к единице той или иной валюты без использования шкалы курса, например: 0.034539 соответствует 3,4539 BYN за 100 RUB.
Элементы данных, содержащие значения процентов (rate), должны иметь формат 0<=decimal<=100 td=11 fd=10 и формироваться в соответствии со следующими правилами:
значение состоит из целой части, разделителя и дробной части;
в качестве разделителя целой и дробной частей используется символ «.» (точка);
общее количество цифр не должно превышать 11, разделитель не учитывается;
целая и дробная части должны содержать хотя бы одну цифру;
в целой части ноли перед первой значащей цифрой отсутствуют;
в дробной части ноли после последней значащей цифры отсутствуют;
максимальное значение не должно превышать 100.
Например: 20.0 соответствует 20 %; 0.05 соответствует 0,05 %.
Элемент данных «Валюта» (currency, sourceCurrency, targetCurrency, unitCurrency и т.д.) содержит значение кода валюты, указывается согласно ОКРБ 016 (справочник N003, таблица 80), имеет тип данных CurrencyCode и формат [A-Z]{3}, например: BYN.
16.5. Элементы данных, содержащие значения даты и времени.
Элемент данных «Дата» (valueDate, fromBookingDate, toBookingDate, expirationDate, transactionFromDate, transactionToDate и т.д.) – элемент данных, содержащий значение даты, указывается согласно расширенному формату межгосударственного стандарта ГОСТ ИСО 8601-2001 «Система стандартов по информации, библиотечному и издательскому делу. Представление дат и времени. Общие требования», утвержденного постановлением Комитета по стандартизации, метрологии и сертификации при Совете Министров Республики Беларусь от 22 августа 2002 г. № 37 (далее – ГОСТ ИСО 8601), имеет тип данных ISODate и формат YYYY-MM-DD (год-месяц-день).
Элемент данных «Дата и время» (toBookingDateTime, fromBookingDateTime, creationDateTime, statusUpdateDateTime и т.д.) – элемент данных, содержащий значение даты и времени, указывается согласно расширенному формату ГОСТ ИСО 8601, имеет тип данных ISODateTime и формат YYYY-MM-DDThh:mm:ss±hh:mm. Например, для указания даты и времени 26 марта 2021 года 17 ч. 19 мин. 33 сек. (по Минскому времени): 2021-03-26Т17:19:33+03:00.
Элемент данных «Время» – элемент данных, содержащий значение времени, указывается согласно формату ГОСТ ИСО 8601, имеет тип данных ISOTime и формат hh:mm:ss±hh:mm.
Время указывается с учетом часового пояса страны, в случае Республики Беларусь используется GMT+3.
16.6. Элемент данных «Страна».
Элемент данных «Страна» (country) указывается в кодированной форме согласно общегосударственному классификатору Республики Беларусь ОКРБ 017-99 «Страны мира», утвержденному постановлением Государственного комитета по стандартизации, метрологии и сертификации Республики Беларусь от 16 июня 1999 г. № 8 (далее – ОКРБ 017), (справочник N013, таблица 80), имеет структурированный тип данных CountryCode и формат [A-Z]{2}, например: PL.
Элемент данных «Страна» должен указываться при идентификации нерезидентов Республики Беларусь.
16.7. Элемент данных «Идентификационный налоговый номер».
В элементе данных «Идентификационный налоговый номер» (taxIdentification) указываются статус стороны и учетный номер плательщика (далее – УНП), присвоенный налоговыми органами, в формате [A-Z]{3}[A-Z0-9]{9}, где:
[A-Z]{3} – значение статуса стороны согласно справочнику N061, таблица 80 (INB, INI, INN, INP, INU, INZ);
[A-Z0-9]{9} – УНП.
Глава 2
Требования к структуре API
17. Структура пути URI.
Путь URI соответствует следующей структуре:
[participant-path-prefix]/open-banking/[version]/[resource]/[resource-id]/[sub-resource].
Структура URI пути состоит из следующих элементов:
[participant-path-prefix] – необязательный префикс поставщика API;
open-banking – постоянное значение «open-banking»;
[version] – версия API, выраженная в виде /v[major-version].[minor-version]/;
[resource]/[resource-id] – наименование ресурса и его идентификатор;
[sub-resource] – наименование подресурса (ресурса 2-го уровня).
Поставщик API использует один и тот же participant-path-prefix и host name для всех своих ресурсов.
Примеры:
https://api.bank.by/oapi-channel/open-banking/v1.0/payments;
https://api.bank.by/oapi-channel/open-banking/v1.0/accountConsents;
https://api.bank.by/oapi-channel/open-banking/v1.0/accounts;
https://api.bank.by/oapi-channel/open-banking/v1.0/accounts/1234;
https://api.bank.by/oapi-channel/open-banking/v1.0/accounts/1234/transactions.
18. Заголовки запросов (headers).
Применяемость атрибутов заголовка в зависимости от метода указана в таблице 1.
Таблица 1
Параметр | Определение и правила использования | Метод | Метод | Метод |
Content-Type | Стандартный заголовок HTTP, представляет формат полезной нагрузки в запросе. | О | – | – |
Accept | Стандартный HTTP заголовок, определяющий тип контента, который требуется от сервера. | Н | Н | – |
Authorization | Стандартный заголовок HTTP, используется для пользователей API второго типа. | О | О | О |
x-jws-signature | Указывает, что JSON запрос подписан | У | У | У |
x-fapi-auth-date | Дата последней авторизации в систему пользователя API второго типа. | Н | Н | Н |
x-fapi-customer-ipaddress | IP-адрес клиента, если клиент в данный момент подключен к пользователю API второго типа (в приложении пользователя API второго типа) | Н | Н | Н |
x-fapi-interaction-id | RFC4122 UID, используемый в качестве идентификатора корреляции. | О | О | О |
x-idempotency-key | Уникальный идентификатор запроса для поддержки идемпотентности. | Н | – | – |
x-customer-useragent | В заголовке указывается тип устройства (user-agent), который использует клиент. | Н | Н | Н |
x-api-key | Идентификатор Apikey, сгенерированный в системе дистанционного банковского обслуживания (далее – СДБО) поставщика API, и предназначенный для идентификации и авторизации запросов пользователя API первого типа | О | О | О |
x-accountConsentId | Идентификатор согласия, в рамках которого отправляется запрос. Предназначен для идентификации и авторизации запросов на получение информации по счету (счетам) пользователя API первого типа | Н | Н | Н |
19. Атрибуты заголовков ответов указаны в таблице 2.
Таблица 2
Параметр | Определение и правила использования | Применяемость |
Content-Type | Стандартный параметр заголовка HTTP. Представляет формат полезной нагрузки, возвращаемой в ответе | О |
Retry-After | Параметр заголовка, указывающий время (в секундах), в течение которого пользователь API второго типа ожидает перед повторением операции. | Н |
x-jws-signature | Указывает, что JSON запрос подписан | У |
x-fapi-interaction-id | RFC4122 UID, используемый в качестве идентификатора корреляции. | О |
20. Коды статусов исполнения запросов.
В таблице 3 приведены коды статусов исполнения запросов HTTP для различных методов HTTP, которые могут быть получены в результате работы определенных запросов. Перечень ответов не является исчерпывающим.
Таблица 3
Код HTTP статуса | Наименование | Описание | Метод | Метод | Метод |
200 | OK | Запрос успешно выполнен | нет | да | нет |
201 | Created | Операция создания выполнена успешно. Результатом операции является создание нового ресурса | да | нет | нет |
204 | No Content | Операция удаления успешно завершена | нет | нет | да |
400 | Bad Request | Запрос имеет неверные отсутствующее или несовместимое тело JSON, параметры URL или поля заголовка. Запрошенная операция не будет выполнена | да | да | да |
401 | Unauthorized | Заголовок авторизации отсутствует или неверный токен доступа. | да | да | да |
403 | Forbidden | Токен доступа имеет неверную область действия или была нарушена политика безопасности. | да | да | да |
404 | (Not Found) | 1. Пользователь API второго типа пытается получить ресурс, который указан в спецификации, но не реализован на стороне поставщика API (например, поставщик API решил не реализовывать конечную точку API статуса для внутренних запланированных платежей). | да | да | да |
405 | Method Not Allowed | Пользователь API второго типа попытался получить доступ к ресурсу с помощью метода, который не поддерживается | да | да | да |
406 | Not Acceptable | Запрос содержал параметр заголовка Accept, отличный от разрешенных media types, и набор символов, отличный от UTF-8 | да | да | да |
415 | Unsupported Media Type | Операция была отклонена, поскольку полезная нагрузка находится в формате, не поддерживаемом этим методом на целевом ресурсе | да | нет | нет |
429 | Too Many Requests | Операция была отклонена, так как слишком много запросов было сделано в течение определенного периода времени. | да | да | да |
500 | Internal Server Error | Внутренняя ошибка сервера. | да | да | да |
503 | Service Unavailable | Устаревшая версия сервера. | да | да | да |
Глава 3
Общая модель данных
21. В настоящей главе описана общая верхнеуровневая структура полезной нагрузки запросов и ответов. Подробные структуры запросов и ответов для конкретных методов API приведены в соответствующих разделах стандарта.
21.1. Структура запросов.
Структура верхнего уровня для запросов API имеет следующий вид:
Request Line
Message Headers
{
"data": {
...
},
"risk": {
...
}
}
Строка запроса содержит метод передачи, путь URI для обращения к конкретному запросу API и версию протокола HTTP.Request Line.
Заголовки запросов (Message Headers) характеризуют тело сообщения, параметры передачи и прочие сведения.
Раздел «data» содержит данные для конкретного запроса API. Структура этого элемента отличается для каждой конечной точки API.
Раздел «risk» содержит индикаторы риска для конкретного запроса API, предоставленного пользователем API второго типа.
Индикаторы риска, содержащиеся в этом элементе, могут отличаться для каждой конечной точки API.
21.2. Структура ответов.
Верхнеуровневая структура ответов API имеет следующий вид:
Response Line
Message Headers
{
"data": {
...
},
"risk": {
...
}
"links": {
...
},
"meta": {
...
}
}
В ответы включаются следующие дополнительные верхнеуровневые разделы:
links – данный блок содержит ссылку на текущий запрос и может для системы пагинации содержать ссылки на первую страницу, текущую и на следующую страницу;
meta – данный блок содержит метаинформацию о странице: сколько страниц в системе пагинации и, например, для транзакций, дата и время первой и последней транзакции по счету.
В соответствии с принципом RESTful API полный ресурс воспроизводится как часть ответа.
21.3. В объектах, где значение для необязательного поля [0..1] не указано, поле исключается из полезной нагрузки JSON.
Например, не допускаются следующие варианты:
"unstructed": "";
"unstructed": 0;
"unstructed": {};
"unstructed": "null".
В объектах, где поле массива определено как имеющее значения 0..n, поле массива включается в полезную нагрузку с пустым массивом.
Например, правильный вариант: «balances»: [ ].
21.4. В настоящем стандарте некоторые модели запросов и ответов включают в себя объект дополнительных данных (Supplementary Data).
Данный объект позволяет поставщику API принимать или передавать данные, которые не входят в структурированные блоки.
Объект дополнительных данных (Supplementary Data) определяется как пустой объект JSON в настоящем стандарте.
Если поставщик API использует структуру с дополнительными данными (Supplementary Data), то он выкладывает детальное описание структуры в своих ресурсах. Поставщик API не использует структуру Supplementary Data, если добавляемый туда элемент уже существует в структурированных блоках.
22. Структура ответов с ошибками указана общая для всех методов API, описанных в данном документе.
22.1. Структура для ответов с ошибками API имеет следующий вид:
{
"code": "...",
"id": "...",
"message": "...",
"errors": [
{
"errorCode": "...",
"message": "...",
"path": "...",
"url": "..."
}
]
}
22.2. Описание элементов данных ответов с ошибками приведено в таблице 4.
Таблица 4
Наименование | Описание | Кратность | Тип данных/ | |
errorResponse | Массив подробных кодов ошибок сообщений и URL-адресов к документации для помощи в исправлении | – | – | |
code | Высокоуровневый код ошибки, необходимый для классификации | [1..1] | Max40Text | |
id | Уникальный идентификатор ошибки | [0..1] | Max40Text | |
message | Краткое описание ошибки. Например: «Что-то не так с предоставленными параметрами запроса» | [1..1] | Max500Text | |
errors | Массив ошибок с описанием | [1..n] | – | |
| errorCode | Низкоуровневое описание ошибки | [1..1] | errorCode |
message | Детализированное описание ошибки. Например: «Обязательное поле не указано» | [1..1] | Max500Text | |
path | Путь к элементу с ошибкой в JSON объекте | [0..1] | Max500Text | |
url | URL для помощи в устранении проблемы. В данном элементе может быть ссылка на веб-страницу, объясняющую правильное поведение. | [0..1] | xs:anyURI | |
22.3. Примерный список кодов низкоуровневых ошибок представлен в таблице 5 с учетом кода ответа HTTP.
Таблица 5
Значение | HTTP-статус | Описание |
BY.NBRB.Field.Expected | 400 | Если элементы передаются парой (ключ-значение) и значение не было передано. В элементе path должен передаваться путь к ожидаемому элементу (например, errorResponse. errors.path «accountResponse.data.account.accountDetails.identification»). Например, для допустимого значения элемента «schemeName» должно передаваться соответствующее значение идентификатора в элементе «identification» |
BY.NBRB.Field.Invalid | 400 | В элементе указано недопустимое значение или длина предоставленного значения превышает соответствующую максимальную длину элемента в домене поставщика API. Ссылка на недопустимый элемент должна быть указана в элементе path (например, errorResponse.errors.path «accountResponse.data.account.accountDetails. schemeName»). Проблема должна быть подробно описана в сообщении об ошибке, указан конкретный элемент |
BY.NBRB.Field.InvalidDate | 400 | Указана неверная дата. В сообщении можно указать актуальную проблему с датой. Ссылка на недопустимый элемент должна быть указана в элементе path |
BY.NBRB.Field.Missing | 400 | Обязательный элемент отсутствует. Данный код ошибки можно использовать, если ошибка еще не определена при проверке BY.NBRB.Resource.InvalidFormat. Ссылка на отсутствующий элемент должна быть указана в элементе path |
BY.NBRB.Header.Invalid | 400 | В элементе заголовка HTTP указано неверное значение. Элемент заголовка HTTP должен быть указан в элементе path |
BY.NBRB.Header.Missing | 400 | Обязательный элемент HTTP-заголовка не был предоставлен. Элемент заголовка HTTP должен быть указан в элементе path |
BY.NBRB.Resource.ConsentMismatch | 400 | Несоответствие ресурсов согласия и платежного указания. Например, если элемент в разделе «initiation» или «risk» ресурса платежного указания не совпадает с одноименным элементом в соответствующем разделе ресурса согласия. Элемент path должен быть заполнен элементом ресурса платежного указания, который не соответствует согласию |
BY.NBRB.Resource.InvalidConsentStatus | 400 | Согласие, соответствующее ресурсу, находится в некорректном статусе, который бы позволил создать ресурс или выполнить запрос. Например, если ресурс согласия имеет статус AwaitingAuthorisation или Rejected, то ресурс не может быть создан с таким статусом соответствующего ему согласия. Элемент path должен быть заполнен элементом ресурса согласия, который является недопустимым |
BY.NBRB.Resource.InvalidFormat | 400 | Когда json-схема полезной нагрузки не соответствует конечной точке. Например, конечная точка POST/payments вызывается с полезной нагрузкой JSON, которая не может быть проанализирована в классе запроса платежного указания |
BY.NBRB.Resource.NotFound | 400 | Ресурс с указанным идентификатором не существует (ресурс не может быть обработан) |
BY.NBRB.Resource.NotCreated | 400 | Ресурс с указанным идентификатором еще не создан и не может быть передан в ответном сообщении. Для асинхронных вызовов. Например, получение выписки по счету, где сначала создается ресурс выписки (метод POST/statements/{accountId}) и в ответном сообщении приходит идентификатор созданного ресурса выписки, но для наполнения выписки данными поставщика API требуется некоторое время. Соответственно будет приходить данное сообщение об ошибке |
BY.NBRB.Resource.NotCancel | 400 | Ресурс не может быть отозван |
BY.NBRB.Rules.AfterCutOffDateTime | 400 | Ресурс согласия или ресурс платежного указания запрашивается после даты cutOffDateTime |
BY.NBRB.Signature.Invalid | 400 | Заголовок подписи x-jws-signature был проанализирован и имеет действительный заголовок JOSE, соответствующий спецификации, но сама подпись не может быть проверена |
BY.NBRB.Signature.InvalidClaim | 400 | Заголовок JOSE в элементе x-jws-signature имеет одно или несколько утверждений (claim) с недопустимым значением (например, утверждение kid, которое не принимает сертификат). Наименование отсутствующего утверждения должно передаваться в элементе path ответа об ошибке |
BY.NBRB.Signature.MissingClaim | 400 | Заголовок JOSE в элементе x-jws-signature имеет одно или несколько обязательных утверждений, которые не указаны. Имя пропущенного утверждения должно быть указано в элементе path ответа об ошибке |
BY.NBRB.Signature.Malformed | 400 | x-jws-signature в заголовке запроса была искажена и не могла быть проанализирована как допустимый JWS |
BY.NBRB.Signature.Missing | 400 | Запрос API предполагает x-jws-signature в заголовке, но элемент отсутствовал |
BY.NBRB.Unsupported.AccountIdentifier | 400 | Идентификатор счета не поддерживается для данной схемы. Элемент path содержит путь к элементу accountIdentifier |
BY.NBRB.Unsupported.LocalInstrument | 400 | Указанный localInstrument не поддерживается поставщиком API. Элемент path содержит путь к элементу localInstrument. Элемент URL должен быть заполнен ссылкой на документацию поставщика API со списком поддерживаемых localInstrument |
BY.NBRB.Reauthenticate | 403 | Для обработки запроса требуется повторная аутентификация клиента |
BY.NBRB.Rules.ResourceAlreadyExists | 409 | Ресурс с такими же параметрами уже существует |
BY.NBRB.UnexpectedError | 5хх | Возникновение непредвиденной ошибки. Поставщик API должен заполнить сообщение детальным описанием ошибки, не раскрывая конфиденциальную информацию |
Перечень низкоуровневых текстовых ошибок не является исчерпывающим и может быть дополнен поставщиком API, используя свою схему нумерации ошибок «BY.NAME_BANK.errorCode».
Пример:
{
"code": "400 Bad Request",
"id": "2b5f0fb2-730b-11e8-adc0-fa7ae0ghfsfh",
"message": "Невалидные параметры запроса",
"errors": [
{
"errorCode": "BY.NBRB.Resource.ConsentMismatch",
"message": "Элементы initiation в paymentConsents и в payments не совпадают между собой",
"path": "data.initiation"
}
]
}
23. Система пагинации для больших json ответов.
Поставщик API предоставляет постраничный ответ для методов GET, которые возвращают множественные записи.
Если существует следующая страница записей, то поставщик API предоставляет ссылку на следующую страницу записей в элементе links.next ответа. Отсутствие следующей ссылки будет означать, что текущая страница является последней страницей записей.
Для многостраничных ответов поставщик API гарантирует, что количество записей на одной странице составляет минимум 25 записей (кроме последней страницы, где больше нет записей) и максимум 100 записей.
Поставщик API включает «self» ссылку на ресурс в элементе links.self.
Дополнительно поставщик API предоставляет:
ссылку на первую страницу записей в элементе links.first;
общее количество страниц в элементе meta.totalPages.
Настоящий стандарт не определяет, каким образом параметры перелистывания страниц передаются поставщиком API. Каждый поставщик API может использовать свои собственные механизмы для разбивки ответа. Если исходный запрос от пользователя API включал параметры фильтра, то в ответе возвращаются только те результаты (разбитые на страницы), которые соответствуют фильтру.
Пример второй страницы из многостраничного ответа:
{
"data": {
...
},
"links": {
"self": "https://api.bank.by/oapi-channel/open-banking/v1.0/accounts/98765/transactions/23?pg=2",
"first": "https://api.bank.by/oapi-channel/open-banking/v1.0/accounts/98765/transactions/23",
"next": "https://api.bank.by/oapi-channel/open-banking/v1.0/accounts/98765/transactions/23?pg=3"
},
"meta": {
"totalPages": 6,
"firstAvailableDateTime": «2019-05-03T00:00:00+00:00»,
"lastAvailableDateTime": «2019-12-03T00:00:00+00:00»
}
}
Пример ответа, когда нет данных:
{
"data": {
"transactionListId": "23",
"transaction": [ ] },
"links": {
"self": "https://api.bank.by/oapi-channel/open-banking/v1.0/accounts/98765/transactions/23"
},
"meta": {
"totalPages": 1
}
}
Глава 4
Общие требования к Информационной безопасности
24. Для получения доступа к конечным точкам пользователи API второго типа должны использовать HTTP заголовок Authorization с токеном доступа на предъявителя.
25. Токен доступа на предъявителя может генерироваться следующими двумя способами: централизованным сервером авторизации клиентов (общий для всех поставщиков API) или локальным сервером авторизации клиентов (у каждого поставщика API свой).
26. Требования для генерации токена доступа централизованным сервером авторизации клиентов и его использования приводятся в соответствующей документации поставщика централизованного сервера авторизации клиентов. В настоящем стандарте рассматривается только локальный сервер авторизации клиентов.
27. Токен доступа на предъявителя на локальном сервере авторизации клиентов генерируется с использованием FAPI (Financial-grade API) – расширения семейства протоколов OpenID Connect/OAuth 2.0 по обеспечению безопасности финансовых сервисов.
28. Пользователи API второго типа и поставщики API должны использовать реализацию FAPI, которая соответствует требованиям законодательства.
29. API «Получение информации о счетах клиента» доступны через область действия (scope) – accounts.
30. API «Инициирование платежей» доступны через область действия (scope) – payments.
31. Пользователи API второго типа должны использовать поток Client Credentials Grant для получения доступа к следующим конечным точкам: accountConsents и paymentConsents.
32. Пользователи API второго типа должны использовать поток Authorization Code для получения доступа ко всем остальным конечным точкам.
33. Согласия (accountConsents и paymentConsents) создаются через поток Client Credentials Grant в статусе «AwaitingAuthorisation» и не привязаны к клиенту.
34. Клиент перенаправляется с помощью потока перенаправления (redirection flow) к поставщику API, где он аутентифицируется и авторизует согласие.
35. Поставщик API применяет риск-ориентированный подход при выборе подходящего метода авторизации согласия для клиента.
36. После авторизации согласия клиентом поставщик API меняет статус согласия на «Authorised», привязывает согласие к данному клиенту и перенаправляет поток к пользователю API второго типа.
37. Пользователи API второго типа в рамках потока Authorization Code и авторизованного согласия получают доступ к конечным точкам клиента.
38. Пользователи API первого типа могут использовать заголовок x-api-key с Apikey для получения доступа к конечным точкам.
39. Клиент генерирует Apikey в СДБО поставщика API и использует его как пользователь API первого типа во всех запросах к конечным точкам.
40. Поставщики API и пользователи API для обеспечения приемлемого уровня информационной безопасности должны применять комплексный подход, предполагающий планомерное использование правовых, организационных, программно-технических и других мер обеспечения информационной безопасности на единой концептуальной и методической основах.
41. Защита осуществляется путем установления и соблюдения мер (требований) по защите информации от неправомерного доступа, уничтожения, модификации (изменения) и блокирования правомерного доступа к ней. Выделяют организационные и технические (в том числе программные) меры. Объем и характер мер защиты определяется категорией информации, обрабатываемой в информационных системах поставщиков API и пользователей API, и должны удовлетворять требованиям законодательства в области защиты информации.
42. К организационным мерам по защите относятся обеспечение особого режима допуска в помещения, где может быть осуществлен доступ к информации (материальным носителям информации), а также разграничение доступа к информации по кругу лиц и характеру информации.
43. К техническим мерам по защите относятся меры по использованию средств (модулей) технической и криптографической защиты информации, а также меры по контролю защищенности информации.
Раздел III
Требования к API, используемым для получения информации о счетах клиента
Глава 5
Основные положения
44. Описанные в настоящем разделе методы и модели API дают возможность пользователям API первого и второго типа (поставщикам информационных платежных услуг) (далее для целей настоящего раздела – пользователи API):
создать согласие на получение информации о счетах клиента;
получить данные о счетах и транзакциях.
Требования к особенностям работы с пользователем API первого типа описаны в главе 9 настоящего стандарта.
45. Клиент дает согласие на предоставление доступа пользователю API к данным по своим счетам. Клиент:
выбирает определенные разрешения (permissions);
указывает срок действия разрешений на использование данных;
определяет дату начала и окончания, которые будут использоваться при построении отчетов по спискам транзакций.
46. Клиент должен иметь возможность выбрать счета, на которые предоставляет согласие.
47. Процесс получения клиентом информации о счете (счетах) включает 4 этапа:
1) запрос на получение информации. Клиент инициирует запрос на получение информации о своем счете (счетах);
2) создание согласия. Пользователь API подготавливает и регистрирует согласие на стороне поставщика API;
3) авторизация согласия. Пользователь API перенаправляет клиента на сторону поставщика API и передает созданное ранее согласие. Поставщик API аутентифицирует клиента и ознакомляет клиента с согласием. Клиент авторизует согласие и указывает счета, на которые оно распространяется. Поставщик API после авторизации согласия предоставляет токен доступа пользователю API для дальнейшего получения информации в рамках действия согласия. Клиенту должна быть предоставлена возможность отклонить согласие;
4) запрос данных. Пользователь API выполняет запрос на получение необходимой информации.
В дальнейшем пользователь API имеет возможность отправлять запрос на получение информации в рамках указанного согласия как по инициативе клиента, так и самостоятельно с определенной периодичностью.
Поставщик API должен предоставить возможность клиенту в СДБО ознакомиться со списком действующих согласий, а также возможность их отозвать. По каждому согласию необходимо дополнительно предоставлять информацию о времени последнего использования согласия.
Поставщик API должен поддерживать работу с архивом согласий.
Глава 6
Описание процесса получения информации о счете (счетах) клиента
48. Схема процесса получения информации о счете (счетах) клиента представлена на рисунке 3.
Рисунок 3
49. Описание этапов и шагов процесса получения информации о счете (счетах) клиента.
49.1. Этап 1. Запрос на получение информации.
Клиент инициирует запрос на получение информации о своем счете (счетах).
49.2. Этап 2. Создание согласия.
Пользователь API подготавливает и регистрирует согласие на стороне поставщика API:
1) установление защищенного канала связи между пользователем API и сервером авторизации поставщика API;
2) пользователь API с помощью потока Client Credentials Grant получает токен доступа от сервера авторизации поставщика API;
3) пользователь API авторизуется у поставщика API, который обслуживает счет (счета) клиента и создает согласие на получение информации о счете (счетах);
4) поставщик API генерирует и возвращает идентификатор согласия.
49.3. Этап 3. Авторизация согласия.
Пользователь API отправляет запрос клиенту на авторизацию согласия по следующему сценарию:
1) пользователь API перенаправляет клиента на страницу к поставщику API с указанием идентификатора согласия;
2) клиент аутентифицируется на стороне поставщика API, просматривает согласие, указывает счета, на которые оно распространяется и авторизует согласие;
3) после авторизации согласия клиент перенаправляется на сторону пользователя API с кодом авторизации;
4) после установления защищенного канала связи между пользователем API и сервером авторизации поставщика API, на сервере авторизации поставщика API пользователь API производит обмен кода авторизации на токен доступа.
На этом этапе клиент не может изменять параметры согласия на получение информации о счете (счетах). Он может только полностью авторизовать или отклонить согласие.
49.4. Этап 4. Запрос данных.
Пользователь API выполняет запрос с помощью метода GET для соответствующего счета (счетов). Уникальные идентификаторы счетов, которые соответствуют согласию (согласиям) на доступ к информации о счетах, будут возвращены при вызове GET.
Глава 7
Модели данных общих объектов, используемых в методах API
50. Объекты debtor и creditor используются в запросах и ответах при получении информации о счетах клиента и при инициировании платежей. Объекты ultimateDebtor и ultimateCreditor используются при инициировании платежей. Модели данных объектов debtor, creditor, ultimateDebtor, ultimateCreditor совпадают и представлены на рисунке 4.
Рисунок 4
Атрибутный состав объектов debtor, creditor, ultimateDebtor, ultimateCreditor приведен в таблице 6.
Таблица 6
Наименование | Путь | Кратность | Тип данных/ | Описание | ||
debtor (creditor, ultimateDebtor, ultimateCreditor) | debtor |
|
| Информация о плательщике (бенефициаре, фактическом плательщике, фактическом бенефициаре). Если плательщик (бенефициар, фактический плательщик, фактический бенефициар) являются юридическим лицом, то применяемость элемента данных organisationIdentification будет обязательной | ||
| name | debtor/name | [1..1] | Max140Text | Наименование плательщика (бенефициара, фактического плательщика, фактического бенефициара) | |
countryOfResidence | debtor/countryOfResidence | [0..1] | CountryCode | Страна резидентства юридического лица, место регистрации физического лица | ||
organisationIdentification | debtor/organisationIdentification | [0..3] |
| Уникальный и однозначный способ идентификации организации | ||
| code | debtor/organisationIdentification/code | [1..1] | [A-Z]{4} | Наименование схемы идентификации в кодированной форме, опубликованной во внешнем списке (согласно справочнику E009, таблица 80) | |
identification | debtor/organisationIdentification/identification | [1..1] | Max35Text | Уникальная идентификация организации. | ||
privateIdentification | debtor/privateIdentification | [0..3] |
| Уникальная и однозначная идентификация физического лица | ||
| code | debtor/privateIdentification/code | [1..1] | [A-Z]{4} | Наименование схемы идентификации в кодированной форме, опубликованной во внешнем списке. | |
identification | debtor/privateIdentification/identification | [1..1] | Max35Text | Идентификация физического лица. | ||
issuer | debtor/privateIdentification/issuer | [0..1] | Max35Text | Наименование или код органа, выдавшего документ | ||
postalAddress | debtor/postalAddress | [0..1] |
| Адрес, информация, которая позволяет найти и идентифицирует конкретный адрес в формате, устанавливаемом почтовыми службами | ||
| country | debtor/postalAddress/country | [1..1] | CountryCode | Страна, указывается в кодированной форме (согласно ОКРБ 017 и справочнику N013, таблица 80) | |
countrySubDivision | debtor/postalAddress/countrySubDivision | [0..1] | Max35Text | Регион/область страны | ||
districtName | debtor/postalAddress/districtName | [0..1] | Max35Text | Название административно-территориальной единицы, например: район, сельсовет | ||
townName | debtor/postalAddress/townName | [0..1] | Max35Text | Название населенного пункта, может заполняться согласно единому реестру административно-территориальных и территориальных единиц Республики Беларусь с указанием типа населенного пункта (согласно справочнику N091, таблица 80) перед его названием через пробел | ||
townLocationName | debtor/postalAddress/townLocationName | [0..1] | Max35Text | Конкретное наименование места в населенном пункте. Используется при необходимости для указания кода СОАТО в соответствии с общегосударственным классификатором Республики Беларусь ОКРБ 003-2017 «Система обозначений объектов административно-территориального деления и населенных пунктов», утвержденным постановлением Государственного комитета по стандартизации Республики Беларусь от 6 марта 2017 г. № 17 (далее – ОКРБ 003), и согласно справочнику N058, таблица 80 | ||
postCode | debtor/postalAddress/postCode | [0..1] | Max16Text | Почтовый код (индекс) | ||
streetName | debtor/postalAddress/streetName | [0..1] | Max70Text | Наименование улицы, может заполняться согласно реестру улиц и дорог с указанием типа элемента улично-дорожной сети (согласно справочнику N098, таблица 80) перед его названием через пробел | ||
buildingNumber | debtor/postalAddress/buildingNumber | [0..1] | Max16Text | Номер дома | ||
room | debtor/postalAddress/room | [0..1] | Max16Text | Номер квартиры, помещения или комнаты | ||
addressLine | debtor/postalAddres/addressLine | [0..3] | Max70Text | Информация, которая позволяет найти и идентифицирует конкретный адрес в соответствии с данными почтовых служб, в произвольном текстовом формате | ||
contactDetails | debtor/contactDetails | [0..1] |
| Контактная информация, набор элементов, используемых для указания того, как связаться со стороной | ||
| name | debtor/contactDetails/name | [1..1] | Max140Text | Наименование, под которым известна сторона и которое обычно используется для ее идентификации | |
phoneNumber | debtor/contactDetails/phoneNumber | [0..1] | \+[0-9]{1,3}-[0-9()+\-]{1,30} | Набор данных, который определяет номер телефона в формате, устанавливаемом операторами электросвязи | ||
mobileNumber | debtor/contactDetails/mobileNumber | [0..1] | \+[0-9]{1,3}-[0-9()+\-]{1,30} | Набор данных, который определяет номер мобильного телефона в формате, устанавливаемом операторами электросвязи | ||
faxNumber | debtor/contactDetails/faxNumber | [0..1] | \+[0-9]{1,3}-[0-9()+\-]{1,30} | Набор данных, который определяет номер факса в формате, устанавливаемом операторами электросвязи | ||
emailAddress | debtor/contactDetails/emailAddress | [0..1] | Max140Text | Адрес электронной почты | ||
Глава 8
Требования к методам и моделям API для получения информации о счете (счетах) клиента
51. Список ресурсов API для получения информации о счете (счетах) либо транзакциях по счету указаны в таблице 7.
Таблица 7
API | Ресурсы | Конечные точки (endpoints) | Описание |
Согласия | accountConsents | POST/accountConsents | Создание согласия на получение информации о счете (счетах) клиента (согласно описанию в пункте 52 настоящего стандарта) |
GET/accountConsents/{accountConsentId} | Получение статуса согласия на получение информации о счете (счетах) клиента (согласно описанию в пункте 52 настоящего стандарта) | ||
DELETE/accountConsents/ | Удаление (отзыв) согласия на получение информации о счете (счетах) клиента (согласно описанию в пункте 52 настоящего стандарта) | ||
Счета | accounts | GET/accounts | Получение информации о счетах (согласно описанию в пункте 53 настоящего стандарта) |
GET/accounts/{accountId} | Получение информации о счете (согласно описанию в пункте 53 настоящего стандарта) | ||
Баланс | balances | GET/balances | Получение информации о балансе счетов (согласно описанию в пункте 54 настоящего стандарта) |
GET/accounts/{accountId}/balances | Получение информации о балансе счета (согласно описанию в пункте 54 настоящего стандарта) | ||
Транзакции | transactions | POST/accounts/{accountId}/transactions | Создание перечня транзакций по счету (согласно описанию в пункте 56 настоящего стандарта) |
GET/accounts/{accountId}/transactions/ | Получение перечня транзакций по счету по созданному идентификатору списка транзакций (согласно описанию в пункте 56 настоящего стандарта) | ||
Выписки | statements | POST/statements/{accountId} | Создание выписки по счету (согласно описанию в пункте 55 настоящего стандарта) |
GET/accounts/{accountId}/statements/ | Получение выписки по счету по созданному идентификатору выписки (согласно описанию в пункте 55 настоящего стандарта) |
52. Согласие на получение информации о счете (счетах) клиента.
52.1. Предоставление согласия.
Пользователь API отправляет запрос с помощью метода POST на создание согласия на получение информации о счете (счетах) клиента. Ответ поставщика API на данный запрос содержит идентификатор согласия accountConsentId, который в дальнейшем будет использоваться для отображения согласия клиента и его авторизации.
В рамках процесса авторизации согласия происходят следующие действия:
1. поставщик API аутентифицирует клиента;
2. поставщик API передает согласие, зарегистрированное на стороне пользователя API, клиенту для получения от него авторизации напрямую;
3. клиент авторизует или отклоняет согласие;
4. клиент выбирает список счетов, на которое распространяется согласие;
5. после этого согласие считается авторизованным клиентом.
52.2. Элементы данных параметра accountConsent.
Согласие на получение информации о счете (счетах) клиента будет включать в себя элементы данных, представленные в таблице 8.
Поставщик API может разработать общую политику на предоставление согласий для всех пользователей API и (или) индивидуальную по элементам данным, предоставляемым в согласии.
Таблица 8
Наименование элемента данных | Описание |
transactionToDate | Необязательный элемент данных, дата окончания периода, после которого нельзя получить транзакции клиента на стороне поставщика API. Если элемент данных transactionFromDate отсутствует, список транзакций может быть возвращен до даты последней транзакции (с учетом параметров в запросе по созданию списка транзакций) |
transactionFromDate | Необязательный элемент данных, дата начала периода, с которого можно получить транзакции клиента на стороне поставщика API. Если элемент данных transactionToDate отсутствует, список транзакций может быть возвращен с даты первой транзакции (с учетом параметров в запросе по созданию списка транзакций) |
permissions | Обязательный элемент данных, список разрешений к данным клиента, к которым имеет доступ пользователь API |
expirationDate | Необязательный элемент данных, так как согласие может быть бессрочным. Дата, до которой согласие действительно. Срок действия доступа пользователя API к данным клиента |
Разрешения используются для ограничения данных, возвращаемых в ответ на запрос, и указаны в таблице 9. Разрешения могут быть основными и детальными. Если клиент дал доступ к детальным разрешениям, тогда соответствующие основные разрешения считаются доступными по умолчанию. Массив разрешений должен состоять как минимум из ReadAccountsBasic или ReadAccountsDetail разрешений.
Поставщик API отклонит согласие и вернет в ответе ошибку с кодом 400, если:
согласие содержит пустое значение;
поставщик API не получил ни одного разрешения;
согласие содержит разрешение, которое отсутствует у поставщика API;
в случае нарушений политики на предоставление согласий поставщика API;
в согласии содержится ReadTransactionsBasic, но не содержится ни ReadTransactionsCredits, ни ReadTransactionsDebits;
в согласии содержится ReadTransactionsDetail, но не содержится ни ReadTransactionsCredits, ни ReadTransactionsDebits;
в согласии содержится ReadTransactionsCredits, но не содержится ни ReadTransactionsBasic, ни ReadTransactionsDetail;
в согласии содержится ReadTransactionsDebits, но не содержится ни ReadTransactionsBasic, ни ReadTransactionsDetail.
Таблица 9
Разрешение | Путь | Описание назначения разрешения | Правила использования |
ReadAccountsBasic | /accounts | Просмотр основной информации о счете (счетах) клиента |
|
/accounts/{accountId} | |||
ReadAccountsDetail | /accounts | Просмотр детальной информации о счете (счетах) клиента | Доступ к основным и дополнительным параметрам, указанным в ответе запроса accountDetails и debtorAgent |
/accounts/{accountId} | |||
ReadBalances | /balances | Просмотр информации о балансе счета (счетах) клиента |
|
/accounts/{accountId}/balances | |||
ReadStatementsBasic | /statements/accounts/{accountId}/ | Просмотр основной информации о выписке |
|
ReadStatementsDetail | /statements/accounts/{accountId}/ | Просмотр детальной информации о выписке |
|
ReadTransactionsBasic | /accounts/{accountId}/transactions/ | Просмотр основной информации о транзакциях | Дополнительно должно быть указано ReadTransactionsCredits и (или) ReadTransactionsDebits |
ReadTransactionsDetail | /accounts/{accountId}/transactions/ | Просмотр детальной информации о транзакциях | Дополнительно должно быть указано ReadTransactionsCredits и (или) ReadTransactionsDebits |
ReadTransactionsCredits | /accounts/{accountId}/transactions/ | Просмотр только кредитовых транзакций | Доступ к кредитовым транзакциям. Дополнительно должно быть указано ReadTransactionsBasic или ReadTransactionsDetail |
ReadTransactionsDebits | /accounts/{accountId}/transactions/ | Просмотр только дебетовых транзакций | Доступ к дебетовым транзакциям. Дополнительно должно быть указано ReadTransactionsBasic или ReadTransactionsDetaill |
52.3. Отзыв согласия.
Клиент может отозвать согласие на получение информации о счете (счетах) в любой момент времени.
Клиент может отозвать согласие через пользователя API или напрямую на стороне поставщика API через СДБО.
После отзыва клиентом согласия на получение информации о счете (счетах) на стороне поставщика API при запросе с помощью метода GET/accountConsents/{accountConsentId} в ответе будет возвращаться статус Revoked.
Если согласие будет отозвано на стороне пользователя API, то пользователь API отправляет запрос с помощью метода DELETE/accountConsents/{accountConsentId} для информирования поставщика API об отзыве согласия.
52.4. Статусы согласия на получение информации о счете (счетах) клиента.
Статусы параметра accountConsents при авторизации согласия, после авторизации согласия, после отзыва согласия представлены в таблице 10.
Таблица 10
Наименование статуса | Описание статуса |
AwaitingAuthorisation | Согласие на получение информации о счете (счетах) ожидает авторизации клиента |
Authorised | Согласие на получение информации о счете (счетах) успешно авторизовано клиентом |
Rejected | Согласие на получение информации о счете (счетах) было отклонено клиентом |
Revoked | Согласие на получение информации о счете (счетах) было отозвано клиентом |
Expired | Согласие на получение информации о счете (счетах) недействительно, истек срок действия |
Смена состояний статусов согласия на получение информации о счете (счетах) клиента при определенных действиях представлена на рисунке 5.
Рисунок 5
52.5. Модель данных согласия на получение информации о счете (счетах) клиента.
Модель запроса на создание согласия на получение информации о счете (счетах) клиента представлена на рисунке 6.
Рисунок 6
52.6. Атрибутный состав запроса на создание согласия на получение информации о счете (счетах) клиента представлен в таблице 11.
Таблица 11
Наименование | Путь | Крат- | Тип данных/ | Описание | ||
consent | consent |
| ||||
| data | consent/data | [1..1] |
| ||
| permissions | consent/data/permissions | [1..n] | Max70Text text{1,70} | Список разрешений к данным клиента, к которым имеет доступ пользователь API. Разрешения должны быть запрошены для авторизации на стороне поставщика API и одобрены клиентом | |
expirationDate | consent/data/expirationDate | [0..1] | ISODate, формат | Дата окончания срока действия согласия. | ||
transactionFromDate | consent/data/transactionFromDate | [0..1] | ISODate, формат | Дата начала периода, с которого можно получить транзакции клиента на стороне поставщика API. Если он не указан, данные будут возвращены с самой первой из доступных транзакций | ||
transactionToDate | consent/data/transactionToDate | [0..1] | ISODate, формат | Дата окончания периода, после которого нельзя получить транзакции клиента на стороне поставщика API. Если он не указан, данные будут возвращены до самой последней доступной транзакции | ||
52.7. Модель ответа на запросы на создание POST/accountConsents и получение статуса согласия GET/accountConsents/{accountConsentId} на получение информации о счете (счетах) клиента представлена на рисунке 7.
Рисунок 7
52.8. Атрибутный состав ответа на запросы на создание POST/accountConsents и получение статуса согласия GET/accountConsents/{accountConsentId} на получение информации о счете (счетах) клиента представлен в таблице 12.
Таблица 12
Наименование | Путь | Кратность | Тип данных/ | Описание | ||
consentResponse | consentResponse |
| ||||
| data | consentResponse/data | [1..1] |
| ||
| accountConsentId | consentResponse/data/accountConsentId | [1..1] | Max35Text text{1,35} | Идентификатор согласия | |
link | consentResponse/data/link | [1..1] | Max140Text text{1,140} | Ссылка на согласие | ||
creationDateTime | consentResponse/data/creationDateTime | [1..1] | ISODateTime, формат | Дата и время создания согласия | ||
status | consentResponse/data/status | [1..1] | Max35Text text{1,35} | Статусы согласия на получение информации о счете (счетах) (согласно описанию в таблице 10) | ||
statusUpdateDateTime | consentResponse/data/statusUpdateDateTime | [1..1] | ISODateTime, формат | Дата и время обновления согласия | ||
permissions | consentResponse/data/permissions | [1..n] | Max70Text text{1,70} | Список разрешений к данным клиента, к которым имеет доступ пользователь API. Разрешения должны быть запрошены для авторизации на стороне поставщика API и одобрены клиентом | ||
expirationDate | consentResponse/data/expirationDate | [0..1] | ISODate, формат YYYY-MM-DD | Дата окончания срока действия согласия | ||
transactionFromDate | consentResponse/data/transactionFromDate | [0..1] | ISODate, формат YYYY-MM-DD | Дата начала периода, с которого можно получить транзакции клиента на стороне поставщика API. Если она не указана, данные будут возвращены с самой первой из доступных транзакций | ||
transactionToDate | consentResponse/data/transactionToDate | [0..1] | ISODate, формат YYYY-MM-DD | Дата окончания периода запроса транзакции. Если она не указана, данные будут возвращены до самой последней доступной транзакции | ||
53. Получение информации о счете (счетах) клиента.
Счет имеет уникальный и неизменный идентификатор accountId.
Возможны следующие запросы:
GET/accounts – получение информации о счетах;
GET/accounts/{accountId} – получение информации о счете.
Модель данных и атрибутный состав ответа на запросы.
Модель данных ответа на запросы GET/accounts и GET/accounts/{accountId} представлена на рисунке 8.
Рисунок 8
Атрибутный состав ответа на запросы GET/accounts и GET/accounts/{accountId} представлен в таблице 13.
Таблица 13
Наименование | Путь | Кратность | Тип данных/ | Описание | ||||
accountResponse | accountResponse |
| ||||||
| data | accountResponsed/data | [1..1] |
| ||||
| account | accountResponse/data/account | [0..n] |
| ||||
| accountId | accountResponse/data/account/accountId | [1..1] | Max35Text | Идентификатор счета | |||
status | accountResponse/data/account/status | [1..1] | Max35Text | Статус счета (согласно описанию справочника AccountStatusStaticType. Статус счета в таблице 69) | ||||
statusUpdateDateTime | accountResponse/data/account/statusUpdateDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время последнего обновления статуса счета | ||||
currency | accountResponse/data/account/currency | [1..1] | тип данных ActiveCurrencyCode, формат [A-Z]{3} | Валюта счета (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||||
accountType | accountResponse/data/account/accountType | [1..1] | Max35Text | Тип счета (принадлежность физическому или юридическому лицу) (согласно описанию справочника AccountTypeStaticType. Тип счета в таблице 67) | ||||
accountSubType | accountResponse/data/account/accountSubType | [1..1] | Max35Text | Вид счета/банковских продуктов/условий (согласно описанию справочника AccountSubTypeStaticType. Вид счета/банковских продуктов/условий в таблице 68) | ||||
creationDateTime | accountResponse/data/account/creationDateTime | [1..1] | ISODateTime, | Дата и время открытия счета | ||||
accountDescription | accountResponse/data/account/accountDescription | [0..1] | Max2048Text | Дополнительное описание счета, дополнительная информация о счете | ||||
accountDetails | accountResponse/data/account/accountDetails | [0..1] |
| Блок доступен при разрешении (permissions) клиента ReadAccountsDetail | ||||
| schemeName | accountResponse/data/account/accountDetails/ | [1..1] | Max140Text | Наименование схемы идентификации. | |||
identification | accountResponse/data/accountDetails/identification | [1..1] | IBAN2007Identifier (для schemeName= BY.NBRB.IBAN), | Уникальная и однозначная идентификация счета, согласованная между владельцем счета и банком, обслуживающим счет (IBAN или идентификация в иной форме) | ||||
name | accountResponse/data/account/accountDetails/name | [0..1] | Max140Text | Наименование счета | ||||
substatus | accountResponse/data/account/accountDetails/substatus | [0..1] | Max35Text | Детализированный статус счета (дополнительная информация о счете) (согласно описанию справочника AccountSubstatusStaticType. Детализированный статус счета в таблице 70). Используется когда элемент данных status принимает значение Disabled, предоставляется при ограничении проведений расчетов по счету | ||||
reason | accountResponse/data/account/accountDetails/name | [0..1] | Max520Text | Причина детализированного статуса счета, описание дополнительной информации о счете | ||||
debtorAgent | accountResponse/data/account/debtorAgent | [0..1] |
| Информация о банке, обслуживающим счет клиента. Блок доступен при разрешении (permissions) клиента ReadAccountsDetail | ||||
| identificationClearingSystem | accountResponse/data/account/debtorAgent/ | [0..1] | Согласно справочнику E005 (таблица 80): [A-Z]{5}, | Идентификация клиринговой системы: в кодированной форме (согласно справочнику E005, таблица 80) или собственная идентификация | |||
identification | accountResponse/data/account/debtorAgent/ | [1..1] | BICFIIdentifier (для кода BIC): | Зарегистрированный код BIC (BICFI) или идентификация участника клиринговой системы. | ||||
|
|
| name | accountResponse/data/account/debtorAgent/name | [1..1] | Max140Text | Наименование банка | |
54. Получение информации о балансе счета (счетов).
Счет может иметь несколько типов баланса. Если поставщик API включает кредит в доступный баланс, то в структуре баланса будет специальный раздел для суммы и типа кредита.
Для счета может быть возвращено несколько значений баланса, поскольку баланс разного типа может иметь разные значения. У баланса с типом «доступный» может быть несколько кредитов, соответственно баланс будет содержать несколько разделов creditLine.
Модели запросов:
GET/accounts/{accountId}/balances – получение информации о балансе счета;
GET/balances – получение информации о балансе счетов.
Модель данных и атрибутный состав ответа на запросы.
Модель ответа на запросы получения информации о балансе счета (счетов) представлена на рисунке 9.
Рисунок 9
Атрибутный состав ответа, используемый при запросах информации о балансе счета (счетов), представлен в таблице 14.
Таблица 14
Наименование | Путь | Кратность | Тип данных/ | Описание | ||||
balanceResponse | balanceResponse |
| ||||||
| data | balanceResponse/data | [1..1] |
| ||||
| balance | balanceResponse/data/balance | [0..n] |
| ||||
| accountId | balanceResponse/data/balance/accountId | [1..1] | Max35Text | Идентификатор счета | |||
creditDebitIndicator | balanceResponse/data/balance/creditDebitIndicator | [1..1] | Max35Text | Определение баланса дебетовым или кредитовым (согласно описанию справочника CreditDebitIndicatorStaticType. Индикатор дебетовой/кредитовой операции в таблице 71) | ||||
type | balanceResponse/data/balance/type | [1..1] | Max35Text | Тип баланса (согласно справочнику E072, таблица 80) | ||||
dateTime | balanceResponse/data/balance/dateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время актуальности отчета по балансу | ||||
currency | balanceResponse/data/balance/currency | [1..1] | тип данных ActiveCurrencyCode, | Валюта счета (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||||
balanceAmount | balanceResponse/data/balance/balanceAmount | [1..1] | decimal td=18 fd =5 | Итоговая сумма баланса для всех дебетовых и кредитовых записей (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||||
balanceEquivalentAmount | balanceResponse/data/balance/balanceEquivalentAmount | [0..1] | decimal td=18 fd =2 | Итоговая сумма баланса для всех дебетовых и кредитовых записей в эквиваленте в белорусских рублях (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||||
creditLine | balanceResponse/data/balance/creditLine | [0..n] |
| Информация о кредите | ||||
| included | balanceResponse/data/balance/creditLine/included | [1..1] | boolean | Включение кредита в баланс счета | |||
type | balanceResponse/data/balance/creditLine/type | [0..1] | Max35Text | Вид кредита (согласно описанию справочника CreditLineTypeStaticType. Вид кредита в таблице 72) | ||||
currency | balanceResponse/data/balance/creditLine/currency | [1..1] | тип данных ActiveCurrencyCode, формат [A-Z]{3} | Валюта счета (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||||
creditLineAmount | balanceResponse/data/balance/creditLine/amount | [1..1] | decimal td=18 fd =5 | Сумма кредита (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||||
55. Создание выписки по счету и получение выписки по счету по созданному идентификатору выписки.
55.1. Модель данных, атрибутный состав запроса и ответа по созданию выписки по счету.
POST/statements/{accountId} – создание выписки по счету.
Модель данных запроса POST/statements/{accountId} на создание выписки по счету представлена на рисунке 10.
Рисунок 10
Атрибутный состав запроса POST/statements/{accountId} на создание выписки по счету представлен в таблице 15.
Таблица 15
Наименование | Путь | Кратность | Тип данных/ | Описание | |||
statementRequest | statementRequest |
| |||||
| data | statementRequest/data | [1..1] |
| |||
| statement | statementRequest/data/statement | [1..1] |
| |||
| fromBookingDate | statementRequest/data/statement/ | [1..1] | ISODate, формат | Дата начала периода выписки включительно | ||
toBookingDate | statementRequest/data/statement/ | [1..1] | ISODate, формат | Дата окончания периода выписки включительно | |||
Модель данных ответа на запрос на создание выписки по счету представлена на рисунке 11.
Рисунок 11
Атрибутный состав ответа на запрос на создание выписки по счету представлен в таблице 16.
Таблица 16
Наименование | Путь | Кратность | Тип данных/ | Описание | |||
statementResponse | statementResponse |
|
|
| |||
| data | statementResponse/data | [1..1] |
|
| ||
| statement | statementResponse/data/statement | [1..1] |
|
| ||
| statementId | statementInitResponse/data/statement/ | [1..1] | Max35Text | Идентификатор выписки | ||
accountId | statementResponse/data/statement/ | [1..1] | Max35Text | Идентификатор счета | |||
fromBookingDate | statementResponse/data/statement/ | [1..1] | ISODate, формат YYYY-MM-DD | Дата начала периода выписки включительно | |||
toBookingDate | statementResponse/data/statement/ | [1..1] | ISODate, формат YYYY-MM-DD | Дата окончания периода выписки включительно | |||
55.2. Модель данных, атрибутный состав запроса и ответа на получение выписки по счету по созданному идентификатору выписки.
GET/accounts/{accountId}/statements/{statementId} – получение выписки по счету по созданному идентификатору выписки.
Модель данных ответа на запрос на получение выписки по счету по созданному идентификатору выписки представлена на рисунке 12.
Рисунок 12
Атрибутный состав ответа на запрос на получение выписки по счету по созданному идентификатору выписки представлен в таблице 17.
Таблица 17
Наименование | Путь | Кратность | Тип данных/ | Описание | |||||
statementResponse | statementResponse |
| |||||||
| data | statementResponse/data | [1..1] |
| |||||
| statement | statementResponse/data/statement | [1..1] |
| |||||
| accountId | statementResponse/data/statement/accountId | [0..1] | Max35Text | Идентификатор счета | ||||
statementId | statementResponse/data/statement/statementId | [1..1] | Max35Text | Идентификатор выписки | |||||
fromBookingDate | statementResponse/data/statement/fromBookingDate | [1..1] | ISODate, формат YYYY-MM-DD | Дата начала периода выписки | |||||
toBookingDate | statementResponse/data/statement/toBookingDate | [1..1] | ISODate, формат YYYY-MM-DD | Дата окончания периода выписки | |||||
creationDateTime | statementResponse/data/statement/creationDateTime | [1..1] | ISODateTime, формат | Дата и время создания выписки | |||||
openingAvailableBalance | statementResponse/data/statement/ | [1..1] |
| Входящий остаток по балансу | |||||
| creditDebitIndicator | statementResponse/data/statement/ | [1..1] | Max35Text | Определение баланса дебетовым или кредитовым (согласно описанию справочника CreditDebitIndicatorStaticType. Индикатор дебетовой/кредитовой операции в таблице 71) | ||||
currency | statementResponse/data/statement/ | [1..1] | тип данных ActiveCurrencyCode, формат [A-Z]{3} | Валюта счета (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | |||||
amount | statementResponse/data/statement/ | [1..1] | decimal td=18 fd = 5 | Сумма входящего остатка по балансу (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | |||||
equivalentAmount | statementResponse/data/statement/ | [0..1] | decimal td=18 fd =2 | Сумма входящего остатка по балансу в эквиваленте в белорусских рублях (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | |||||
closingAvailableBalance | statementResponse/data/statement/ | [1..1] |
| Исходящий остаток по балансу | |||||
| creditDebitIndicator | statementResponse/data/statement/ | [1..1] | Max35Text | Определение баланса дебетовым или кредитовым (согласно описанию справочника CreditDebitIndicatorStaticType. Индикатор дебетовой/кредитовой операции в таблице 71) | ||||
currency | statementResponse/data/statement/ | [1..1] | тип данных ActiveCurrencyCode, формат [A-Z]{3} | Валюта счета (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | |||||
amount | statementResponse/data/statement/ | [1..1] | decimal td=18 fd =5 | Сумма исходящего остатка по балансу (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | |||||
equivalentAmount | statementResponse/data/statement/ | [0..1] | decimal td=18 fd =2 | Сумма исходящего остатка по балансу в эквиваленте в белорусских рублях (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | |||||
transaction | statementResponse/data/statement/transaction | [0..n] |
|
| |||||
| transactionId | statementResponse/data/statement/ | [0..1] | Max35Text | Уникальный идентификатор транзакции | ||||
creditDebitIndicator | statementResponse/data/statement/transaction/ | [1..1] | Max35Text | Определение баланса дебетовым или кредитовым (согласно описанию справочника CreditDebitIndicatorStaticType. Индикатор дебетовой/кредитовой операции в таблице 71) | |||||
status | statementResponse/data/statement/transaction/status | [1..1] | [A-Z0-9]{3} | Статус транзакции на балансе поставщика API. | |||||
number | statementResponse/data/statement/transaction/number | [0..1] | Max35Text | Номер платежной инструкции | |||||
bookingDateTime | statementResponse/data/statement/transaction/ | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время отражения транзакции по счету на балансе поставщика API | |||||
valueDate | statementResponse/data/statement/transaction/valueDate | [0..1] | ISODate, формат YYYY-MM-DD | Дата валютирования, с которой сумма денежных средств не находится (при списании денежных средств со счета) или находится (при зачислении денежных средств на счет) в распоряжении владельца счета | |||||
transactionDetails | statementResponse/data/statement/transaction/ | [0..1] | Max512Text | Информация о транзакции, назначение перевода денежных средств | |||||
amount | statementResponse/data/statement/transaction/amount | [1..1] | decimal td=18 fd =5 | Сумма транзакции (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | |||||
currency | statementResponse/data/statement/transaction/currency | [1..1] | тип данных ActiveCurrencyCode, формат [A-Z]{3} | Валюта транзакции (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | |||||
equivalentAmount | statementResponse/data/statement/transaction/ | [0..1] | decimal td=18 fd =2 | Сумма транзакции в эквиваленте в белорусских рублях (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | |||||
debtor | statementResponse/data/statement/transaction/debtor | [0..1] |
| Информация о плательщике (в соответствии с описанием, приведенным в таблице 6) | |||||
debtorAccount | statementResponse/data/statement/transaction/ | [0..1] |
| Идентификация счета плательщика | |||||
| schemeName | statementResponse/data/statement/transaction/ | [1..1] | Max140Text | Наименование схемы идентификации. | ||||
identification | statementResponse/data/statement/transaction/ | [1..1] | IBAN2007Identifier (для schemeName= BY.NBRB.IBAN), | Уникальная и однозначная идентификация счета, согласованная между владельцем счета и банком, обслуживающим счет (IBAN или идентификация в иной форме) | |||||
debtorAgent | statementResponse/data/statement/transaction/debtorAgent | [0..1] |
| Информация о банке, обслуживающим счет плательщика | |||||
| identificationClearingSystem | statementResponse/data/statement/transaction/ | [0..1] | Согласно справочнику E005 (таблица 80): [A-Z]{5}, | Идентификация клиринговой системы: в кодированной форме (согласно справочнику E005, таблица 80) или собственная идентификация | ||||
identification | statementResponse/data/statement/transaction/ | [1..1] | BICFIIdentifier (для кода BIC): | Зарегистрированный код BIC (BICFI) или идентификация участника клиринговой системы. | |||||
name | statementResponse/data/statement/transaction/ | [1..1] | Max140Text | Наименование банка, обслуживающего счет плательщика | |||||
creditor | statementResponse/data/statement/transaction/ | [0..1] |
| Информация о бенефициаре (в соответствии с описанием, приведенным в таблице 6) | |||||
creditorAccount | statementResponse/data/statement/transaction/ | [0..1] |
| Идентификация счета бенефициара | |||||
|
|
|
|
| schemeName | statementResponse/data/statement/transaction/ | [1..1] | Max140Text | Наименование схемы идентификации. |
|
|
| identification | statementResponse/data/statement/transaction/ | [1..1] | IBAN2007Identifier (для schemeName= BY.NBRB.IBAN), | Уникальная и однозначная идентификация счета, согласованная между владельцем счета и банком, обслуживающим счет (IBAN или идентификация в иной форме) | ||
creditorAgent | statementResponse/data/statement/transaction/ | [0..1] |
| Информация о банке, обслуживающем счет бенефициара | |||||
| identificationClearingSystem | statementResponse/data/statement/transaction/ | [0..1] | Согласно справочнику E005 (таблица 80): [A-Z]{5}, | Идентификация клиринговой системы: в кодированной форме (согласно справочнику E005, таблица 80) или собственная идентификация | ||||
identification | statementResponse/data/statement/transaction/ | [1..1] | BICFIIdentifier (для кода BIC): | Зарегистрированный код BIC (BICFI) или идентификация участника клиринговой системы. | |||||
name | statementResponse/data/statement/transaction/ | [1..1] | Max140Text | Наименование банка, обслуживающего счет бенефициара | |||||
56. Создание перечня транзакций по счету и получение перечня транзакций по счету по созданному идентификатору списка транзакций.
POST/accounts/{accountId}/transactions – создание перечня транзакций по счету.
GET/accounts/{accountId}/transactions/{transactionListId} – получение перечня транзакций по счету по созданному идентификатору списка транзакций.
56.1. Модель данных, атрибутный состав запроса и ответа по созданию перечня транзакций по счету.
POST/accounts/{accountId}/transactions – создание перечня транзакций по счету.
Модель данных запроса на создание перечня транзакций по счету представлена на рисунке 13.
Рисунок 13
Атрибутный состав запроса на создание перечня транзакций по счету представлен в таблице 18.
Таблица 18
Наименование | Путь | Кратность | Тип данных/Формат | Описание | |||
transactionRequest | transactionRequest |
| |||||
| data | transactionRequest/data | [1..1] |
| |||
| transaction | transactionRequest/data/transaction | [1..1] |
| |||
| fromBookingDateTime | transactionRequest/data/transaction/fromBookingDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время начала фильтрации списка транзакций | ||
toBookingDateTime | transactionRequest/data/transaction/toBookingDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время окончания фильтрации списка транзакций | |||
Модель данных ответа на запрос на создание перечня транзакций по счету представлена на рисунке 14.
Рисунок 14
Атрибутный состав ответа на запрос на создание перечня транзакций по счету представлен в таблице 19.
Таблица 19
Наименование | Путь | Кратность | Тип данных/Формат | Описание | |||
transactionResponse | transactionResponse |
| |||||
| data | transactionResponse/data | [1..1] |
| |||
| transaction | transactionResponse/data/transaction | [1..1] |
| |||
| transactionListId | transactionResponse/data/transaction/transactionListId | [1..1] | Max35Text | Идентификатор списка транзакций | ||
accountId | transactionResponse/data/transaction/accountId | [1..1] | Max35Text | Идентификатор счета | |||
fromBookingDateTime | transactionResponse/data/transaction/fromBookingDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время начала периода фильтрации списка транзакций | |||
toBookingDateTime | transactionResponse/data/transaction/toBookingDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время окончания периода фильтрации транзакций | |||
56.2. Модель данных, атрибутный состав запроса и ответа на получение перечня транзакций по счету по созданному идентификатору списка транзакций.
Модель данных ответа на запрос GET/accounts/{accountId}/transactions/{transactionListId} на получение транзакций по счету по созданному идентификатору списка транзакций (transactionListId) представлена на рисунке 15.
Рисунок 15
Атрибутный состав ответа на запрос GET/accounts/{accountId}/transactions/{transactionListId} на получение транзакций по счету по созданному идентификатору списка транзакций (transactionListId) представлен в таблице 20.
Таблица 20
Наименование | Путь | Кратность | Тип данных/Формат | Описание | |||||
transactionResponse | transactionResponse |
|
|
| |||||
| data | transactionResponse/data | [1..1] |
|
| ||||
| transactionListId | transactionResponse/data/transactionListId | [1..1] | Max35Text | Идентификатор списка транзакций | ||||
accountId | transactionResponse/data/accountId | [1..1] | Max35Text | Идентификатор счета | |||||
fromBookingDateTime | transactionResponse/data/fromBookingDateTime | [1..1] | ISODateTime, | Дата и время начала периода фильтрации списка транзакций | |||||
toBookingDateTime | transactionResponse/data/toBookingDateTime | [1..1] | ISODateTime, | Дата и время окончания периода фильтрации транзакций | |||||
creationDateTime | transactionResponse/data/creationDateTime | [1..1] | ISODateTime, | Дата и время создания списка транзакций | |||||
transaction | transactionResponse/data/transaction | [0..n] |
| Информация о транзакции | |||||
| transactionId | transactionResponse/data/transaction/transactionId | [1..1] | Max35Text | Уникальный идентификатор транзакции | ||||
transactionReference | transactionResponse/data/transaction/transactionReference | [0..1] | Max35Text | Уникальный референс для транзакции | |||||
creditDebitIndicator | transactionResponse/data/transaction/creditDebitIndicator | [1..1] | Max35Text | Определение баланса дебетовым или кредитовым (согласно описанию справочника CreditDebitIndicatorStaticType. Индикатор дебетовой/кредитовой операции в таблице 71) | |||||
status | transactionResponse/data/transaction/status | [1..1] | [A-Z0-9]{3} | Статус транзакции на балансе поставщика API. | |||||
bookingDateTime | transactionResponse/data/transaction/bookingDateTime | [1..1] | ISODateTime, формат | Дата и время отражения транзакции по счету на балансе поставщика API | |||||
valueDate | transactionResponse/data/transaction/valueDate | [0..1] | ISODate, формат YYYY-MM-DD | Дата валютирования, с которой сумма денежных средств не находится (при списании денежных средств со счета) или находится (при зачислении денежных средств на счет) в распоряжении владельца счета | |||||
transactionDetails | transactionResponse/data/transaction/transactionDetails | [0..1] | Max512Text | Информация о транзакции, назначение перевода денежных средств | |||||
addressLine | transactionResponse/data/transaction/addressLine | [0..1] | Max70Text | Информация, которая находит и идентифицирует конкретный адрес для записи транзакции, который представлен в тексте в произвольном формате | |||||
amount | transactionResponse/data/transaction/amount | [1..1] | decimal td=18 fd=5 | Сумма транзакции (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | |||||
currency | transactionResponse/data/transaction/currency | [1..1] | тип данных ActiveCurrencyCode, | Валюта счета (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | |||||
chargeAmount | transactionResponse/data/transaction/chargeAmount | [0..1] |
| Комиссионное вознаграждение за проведение транзакции | |||||
| amount | transactionResponse/data/transaction/chargeAmount/ | [1..1] | decimal td=18 fd=5 | Сумма комиссионного вознаграждения за проведение транзакции (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||||
currency | transactionResponse/data/transaction/chargeAmount/ | [1..1] | тип данных ActiveCurrencyCode, формат [A-Z]{3} | Валюта счета (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | |||||
currencyExchange | transactionResponse/data/transaction/currencyExchange | [0..1] |
| Информация об обмене валют | |||||
| sourceCurrency | transactionResponse/data/transaction/currencyExchange/ | [1..1] | тип данных ActiveCurrencyCode, | Валюта, из которой сумма должна быть конвертирована при конверсии валюты (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||||
targetCurrency | transactionResponse/data/transaction/currencyExchange/ | [0..1] | тип данных ActiveCurrencyCode | Валюта, в которую сумма должна быть конвертирована при конверсии валюты (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | |||||
unitCurrency | transactionResponse/data/transaction/currencyExchange/ | [0..1] | тип данных ActiveCurrencyCode, | Валюта, в которой выражается обменный курс при обмене валюты (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | |||||
exchangeRate | transactionResponse/data/transaction/currencyExchange/ | [1..1] | 0 <= decimal | Обменный курс. Коэффициент, используемый для конвертации суммы из одной валюты в другую. Он отражает цену, по которой одна валюта куплена за другую валюту (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | |||||
contractIdentification | transactionResponse/data/transaction/currencyExchange/ | [0..1] | Max35Text | Уникальный идентификатор валютного договора, согласованного между инициирующей стороной/бенефициаром и агентом плательщика. | |||||
quotationDateTime | transactionResponse/data/transaction/currencyExchange/ | [0..1] | ISODateTime, формат | Дата и время установления котировки обменного курса | |||||
instructedAmount | transactionResponse/data/transaction/currencyExchange/ | [0..1] |
| Сумма денежных средств, подлежащая переводу между плательщиком и получателем средств до вычета расходов, выраженная в валюте, обозначенной инициирующей стороной | |||||
| amount | transactionResponse/data/transaction/currencyExchange/ | [1..1] | decimal td=18 fd=5 | Сумма денежных средств, подлежащая переводу между плательщиком и получателем средств до вычета расходов (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||||
currency | transactionResponse/data/transaction/currencyExchange/ | [1..1] | тип данных ActiveCurrencyCode, | Валюта, обозначенная инициирующей стороной (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | |||||
balance | transactionResponse/data/transaction/balance | [0..1] |
| Подробная информация о балансе | |||||
| creditDebitIndicator | transactionResponse/data/transaction/balance/ | [1..1] | Max35Text | Определение баланса дебетовым или кредитовым (согласно описанию справочника CreditDebitIndicatorStaticType. Индикатор дебетовой/кредитовой операции в таблице 71) | ||||
type | transactionResponse/data/transaction/balance/type | [1..1] | Max35Text | Тип баланса (согласно справочнику E072, таблица 80) | |||||
currency | transactionResponse/data/transaction/balance/currency | [1..1] | тип данных ActiveCurrencyCode, | Валюта суммы баланса (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | |||||
balanceAmount | transactionResponse/data/transaction/balance/amount | [1..1] | decimal td=18 fd=5 | Итоговая сумма по балансу для всех дебетовых и кредитовых записей (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | |||||
merchantDetails | transactionResponse/data/transaction/merchantDetails | [0..1] |
| Информация о продавце, участвующем в сделке | |||||
| merchantName | transactionResponse/data/transaction/merchantDetails/ | [0..1] | Max140Text | Наименование продавца | ||||
merchantCategoryCode | transactionResponse/data/transaction/merchantDetails/ | [0..1] | Max4Text | Код категории, к которому относится тип услуг или товаров, которые продавец предоставляет | |||||
debtor | transactionResponse/data/transaction/debtor | [0..1] |
| Информация о плательщике (согласно описанию, приведенному в таблице 6) | |||||
debtorAccount | transactionResponse/data/transaction/debtorAccount | [0..1] |
| Идентификация счета плательщика | |||||
| schemeName | transactionResponse/data/transaction/debtorAccount/ | [1..1] | Max140Text | Наименование схемы идентификации. | ||||
identification | transactionResponse/data/transaction/debtorAccount/ | [1..1] | IBAN2007Identifier (для schemeName= BY.NBRB.IBAN), | Уникальная и однозначная идентификация счета, согласованная между владельцем счета и банком, обслуживающим счет (IBAN или идентификация в иной форме) | |||||
debtorAgent | transactionResponse/data/transaction/debtorAgent | [0..1] |
| Информация о банке, обслуживающим счет плательщика | |||||
| identificationClearingSystem | transactionResponse/data/transaction/debtorAgent/ | [0..1] | Согласно справочнику E005 (таблица 80): [A-Z]{5}, | Идентификация клиринговой системы: в кодированной форме (согласно справочнику E005, таблица 80) или собственная идентификация | ||||
identification | transactionResponse/data/transaction/ | [1..1] | BICFIIdentifier (для кода BIC): | Зарегистрированный код BIC (BICFI) или идентификация участника клиринговой системы. | |||||
name | transactionResponse/data/transaction/debtorAgent/name | [1..1] | Max140Text | Наименование банка, обслуживающего счет плательщика | |||||
creditor | transactionResponse/data/transaction/creditor | [0..1] |
| Информация о бенефициаре (согласно описанию, приведенному в таблице 6) | |||||
creditorAccount | transactionResponse/data/transaction/creditorAccount | [0..1] |
| Идентификация счета бенефициара | |||||
| schemeName | transactionResponse/data/transaction/creditorAccount/ | [1..1] | Max140Text | Наименование схемы идентификации. | ||||
identification | transactionResponse/data/transaction/creditorAccount/ | [1..1] | IBAN2007Identifier (для schemeName= BY.NBRB.IBAN), | Уникальная и однозначная идентификация счета, согласованная между владельцем счета и банком, обслуживающим счет (IBAN или идентификация в иной форме) | |||||
creditorAgent | transactionResponse/data/transaction/creditorAgent | [0..1] |
| Информация о банке, обслуживающим счет бенефициара | |||||
| identificationClearingSystem | transactionResponse/data/transaction/creditorAgent/ | [0..1] | Согласно справочнику E005 (таблица 80): [A-Z]{5}, | Идентификация клиринговой системы: в кодированной форме (согласно справочнику E005, таблица 80) или собственная идентификация | ||||
identification | transactionResponse/data/transaction/creditorAgent/ | [1..1] | BICFIIdentifier (для кода BIC): | Зарегистрированный код BIC (BICFI) или идентификация участника клиринговой системы. | |||||
name | transactionResponse/data/transaction/creditorAgent/name | [1..1] | Max140Text | Наименование банка, обслуживающего счет бенефициара | |||||
cardInstrument | transactionResponse/data/transaction/cardInstrument | [0..1] |
| Детальное описание платежной карты, использованной в транзакции | |||||
| schemeName | transactionResponse/data/transaction/cardInstrument/ | [1..1] | Max140Text | Наименование схемы (согласно описанию справочника CardSchemeNameStaticType. | ||||
authorisationType | transactionResponse/data/transaction/cardInstrument/ | [0..1] | Max35Text | Тип авторизации карты (согласно описанию справочника CardAuthorisationTypeStaticType. Тип авторизации карты в таблице 74) | |||||
name | transactionResponse/data/transaction/cardInstrument/ | [0..1] | Max140Text | Наименование владельца карты | |||||
identification | transactionResponse/data/transaction/cardInstrument/ | [0..1] | Max35Text | Идентификационный номер карты | |||||
Глава 9
ТРЕБОВАНИЯ К ОСОБЕННОСТЯМ РАБОТЫ С ПОЛЬЗОВАТЕЛЕМ API ПЕРВОГО ТИПА
57. Поставщик API может предоставить возможность создания долгосрочного согласия на получение доступа к API «Получение информации о счетах клиента» для пользователей API первого типа посредством СДБО.
Поставщик API может предоставить возможность просмотра списка долгосрочных согласий на доступ к API «Получение информации о счетах клиента» для пользователя API первого типа и отзыва долгосрочного согласия.
Пользователь API первого типа при выполнении запросов на получение информации о счете может дополнительно использовать следующие заголовки HTTP, которые описаны в таблице 1:
x-api-key – идентификатор Apikey, сгенерированный в СДБО поставщика API и предназначенный для идентификации и авторизации запросов пользователя API первого типа;
x-accountConsentId – идентификатор согласия, в рамках которого отправляется запрос.
58. Схема процесса получения информации о счетах клиента в случае участия пользователя API первого типа представлена на рисунке 16.
Рисунок 16
59. Описание этапов и шагов процесса получения информации о счетах клиента.
59.1. Этап 1. Создание долгосрочного согласия на доступ к API «Получение информации о счетах клиента»:
клиент авторизуется в СДБО у поставщика API, который обслуживает его счет (счета);
клиент создает долгосрочное согласие на получение доступа к API «Получение информации о счетах клиента» и авторизует долгосрочное согласие;
поставщик API генерирует Apikey для долгосрочного согласия;
клиент сохраняет Apikey.
59.2. Этап 2. Создание согласия на получение информации о счетах:
пользователь API первого типа создает согласие на получение информации о счетах на стороне поставщика API с помощью Apikey (запрос POST);
согласие создается со статусом AwaitingAutorization;
поставщик API генерирует и возвращает идентификатор согласия.
59.3. Этап 3. Авторизация согласия:
клиент через СДБО авторизует согласие на получение информации о счетах;
клиент указывает счета, на которые оно распространяется;
поставщик API обновляет статус согласия.
59.4. Этап 4. Запрос данных:
пользователь API первого типа инициирует запрос на получение данных, используя Apikey;
поставщик API отправляет ответ на запрос пользователю API первого типа в рамках авторизованного согласия.
Раздел IV
Требования к API, используемым для инициирования платежа
ГЛАВА 10
ОБЩЕЕ ОПИСАНИЕ
60. Описанные в настоящем разделе методы и модели API дают возможность пользователям API первого типа и пользователям API второго типа (поставщикам платежных услуг инициирования платежа) (далее, если не указано иное, в настоящем разделе – пользователи API) на:
инициирование платежа по инициативе плательщика за товары, работы, услуги;
инициирование платежа по инициативе плательщика в бюджет;
инициирование платежа по инициативе плательщика, содержащего список бенефициаров с указанием счетов бенефициаров;
инициирование платежа по инициативе плательщика, содержащего список бенефициаров при осуществлении перевода без открытия счета;
инициирование платежа по инициативе бенефициара за товары, работы, услуги;
инициирование платежа по инициативе бенефициара (взыскателя) в бюджет;
инициирование рекуррентного платежа;
получение списка согласий и списка платежных указаний.
61. В настоящей главе описываются потоки и данные для инициирования платежа на основании согласия.
API по инициированию платежа, описанные в настоящей главе, включают следующее:
создание согласия на инициирование платежа пользователем API второго типа;
подтверждение согласия на инициирование платежа клиентом;
получение статуса согласия на инициирование платежа клиентом;
создание платежного указания на инициирование платежа клиентом;
получение статуса платежного указания на инициирование платежа клиентом.
62. Поставщик API сам определяет и документирует соответствующие ограничения, которые он поддерживает, основываясь на своих особенностях, индивидуальных методах и локальных правовых актах. Поставщик API отклоняет согласие на инициирование платежа, если не может обработать запрос.
63. Согласие на инициирование только одного платежа является краткосрочным. Клиент не может отозвать согласие после его авторизации.
Согласие на инициирование рекуррентного платежа является долгосрочным. Клиент может отозвать его в любой момент через пользователя API либо непосредственно на стороне поставщика API.
Поставщик API должен предоставить возможность клиенту в СДБО ознакомиться со списком долгосрочных согласий, а также возможность их отозвать. По каждому долгосрочному согласию необходимо дополнительно предоставлять информацию о времени его последнего использования.
Поставщик API должен поддерживать работу с архивом согласий.
63.1. Запрос на создание и получение статуса согласия на инициирование платежа состоит из следующих объектов:
initiation;
authorisation;
risk.
Объект initiation включает в себя все параметры платежной инструкции. Данный объект является обязательным и входит в раздел data.
Объект authorisation включает в себя дату и время, до которого авторизация должна завершиться и тип авторизации согласия клиента (одиночный или множественный). Множественная авторизация используется для авторизации одного и того же согласия несколькими представителями клиента. Данный объект является необязательным и входит в раздел data.
Объект risk используется для указания дополнительных деталей для оценки рисков при инициировании платежей.
63.2. В ответе на запрос создания и получения статуса согласия на инициирование платежа возвращается идентификатор согласия и следующие объекты:
initiation;
authorisation;
risk;
charge.
Объекты initiation, authorisation, risk описаны в подпункте 63.1 настоящего пункта.
Объект charge используется для указания деталей по комиссионным вознаграждениям за обработку платежа. Данный объект является необязательным и входит в раздел data.
64. При ответе на запрос создания и получения статуса согласия на инициирование платежа поставщик API может использовать элемент данных cutOffDateTime, который определяет дату и время, до которого работает платежная система.
Если платежная система работает 24/7, тогда cutOffDateTime не передается. Если платежная система не работает, тогда передается cutOffDateTime со значением, когда она закончила работать.
Поставщик API определяет статус согласия до и после cutOffDateTime для его исполнения.
Существует две стратегии обработки согласий и платежных указаний на инициирование платежа поставщиком API после cutOffDateTime:
1) отклонить согласие на инициирование платежа или платежное указание на инициирование платежа, если оно получено после соответствующего cutOffDateTime;
2) принять согласие на инициирование платежа (и шаги, связанные с созданием данного согласия) и обработать платеж на следующий рабочий интервал, если оно получено после соответствующего cutOffDateTime.
65. Запрос на создание платежного указания на инициирование платежа отправляется после того, как клиент авторизовал согласие на инициирование платежа и должен включать идентификатор согласия.
Данный запрос является инструкцией для поставщика API на инициирование платежа. В случае успешного инициирования платежа возвращается идентификатор платежного указания.
Пользователь API должен обеспечить полное соответствие объектов initiation и risk в запросе на создание согласия на инициирование платежа и в запросе на создание платежного указания на инициирование платежа. Если есть хотя бы одно несовпадение, поставщик API возвращает ошибку с кодом 400 (Bad Request).
Для получения статуса созданного платежного указания на инициирование платежа по идентификатору платежного указания используется соответствующий запрос.
65.1. Запрос на создание платежного указания на инициирование платежа состоит из следующих объектов (описание объектов приведено в подпункте 63.1 пункта 63 настоящего стандарта):
initiation;
risk.
65.2. Ответ на запрос создания платежного указания на инициирование платежа и получение статуса платежного указания на инициирование платежа включает в себя объекты:
initiation;
multiAuthorisation;
charges;
paymentStatus.
Объект initiation описан в подпункте 63.1 пункта 63 настоящего стандарта. Объект charge описан в подпункте 63.2 пункта 63 настоящего стандарта.
Объект multiAuthorisation используется для предоставления информации о текущем состоянии множественной авторизации. Данный объект является необязательным и входит в раздел data.
Объект paymentStatus используется для предоставления информации о текущем статусе платежного указания на инициирование платежа. Данный объект является обязательным и входит в раздел data.
Глава 11
ОПИСАНИЕ ПРОЦЕССА ИНИЦИИРОВАНИЯ ПЛАТЕЖА
66. Схема процесса инициирования платежа представлена на рисунке 17.
Рисунок 17
67. Описание этапов и шагов процесса.
67.1. Этап 1. Запрос на инициирование платежного указания.
Клиент инициирует платежное указание и указывает его параметры.
67.2. Этап 2. Создание согласия.
Пользователь API подготавливает и регистрирует согласие на стороне поставщика API:
1) установление защищенного канала связи между пользователем API и сервером авторизации поставщика API;
2) пользователь API с помощью потока Client Credentials Grant получает токен доступа от сервера авторизации поставщика API;
3) пользователь API создает согласие на инициирование платежа с помощью запроса POST. Согласие создается со статусом AwaitingAutorization и пока не привязано к клиенту;
4) поставщик API генерирует и возвращает идентификатор согласия.
67.3. Этап 3. Авторизация согласия.
Пользователь API отправляет запрос клиенту на авторизацию согласия по следующему сценарию:
1) пользователь API перенаправляет клиента на страницу к поставщику API с указанием идентификатора согласия, созданного на предыдущем этапе;
2) клиент аутентифицируется на стороне поставщика API;
3) поставщик API идентифицирует согласие на инициирование платежа;
4) поставщик API показывает согласие клиенту;
5) клиент выбирает счет получателя средств на этом этапе (если счет получателя средств не был выбран ранее на этапе, указанном в подпункте 67.1 настоящего пункта) и авторизует согласие. Поставщик API на основе риск ориентированного подхода выбирает соответствующий способ авторизации;
6) поставщик API обновляет статус согласия на инициирование платежа, фиксирует, что согласие было авторизовано один раз;
7) после авторизации согласия клиент перенаправляется на сторону пользователя API с кодом авторизации;
8) на сервере авторизации поставщика API происходит обмен кода авторизации на токен доступа.
67.4. Этап 4. Создание платежного указания на инициирование платежа:
1) установление защищенного канала связи между пользователем API и сервером ресурсов поставщика API;
2) пользователь API инициирует платежное указание и указывает идентификатор авторизованного согласия;
3) поставщик API возвращает идентификатор платежного указания и отправляет платежное указание в обработку. Для множественной авторизации платежное указание отправляется в обработку после авторизации согласия необходимым количеством представителей клиента, для одиночной авторизации – одним представителем клиента. Под множественной авторизацией понимается авторизация одного и того же согласия несколькими представителями клиента, под одиночной – одним представителем клиента.
67.5. Этап 5. Получение статуса согласия и статуса платежного указания:
1) установление защищенного канала связи между пользователем API и сервером ресурсов поставщика API;
2) пользователь API проверяет статус согласия на инициирование платежа или статус платежного указания на инициирование платежа.
Глава 12
Модели данных общих объектов, используемых при инициировании платежа
68. Объект charge.
Объект charge используется для указания деталей по комиссионным вознаграждениям за обработку платежа. Модель данных объекта charge представлена на рисунке 18.
Рисунок 18
Атрибутный состав объекта charge приведен в таблице 21.
Таблица 21
Наименование | Путь | Кратность | Тип данных/ | Описание | |
charge | charge |
|
|
| |
| chargeBearer | charge/chargeBearer | [1..1] | [A-Z]{4} | Сторона, которая будет уплачивать комиссии за обработку платежной транзакции (согласно справочнику N100, таблица 80) |
type | charge/type | [1..1] | Max16Text | Тип комиссии за проведение платежа: | |
currency | charge/currency | [1..1] | тип данных | Код валюты, валюта суммы комиссии (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | |
chargeAmount | charge/chargeAmount | [1..1] | decimal td=18 fd =5 | Сумма комиссии за проведение платежа (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | |
69. Объект authorisation.
Объект authorisation включает в себя дату и время, до которого авторизация должна завершиться и тип авторизации согласия клиента (одиночный или множественный). Одиночная авторизация используется для авторизации согласия одним представителем клиента. Множественная авторизация используется для авторизации одного и того же согласия несколькими представителями клиента. Модель данных объекта authorisation представлена на рисунке 19.
Рисунок 19
Атрибутный состав объекта authorisation приведен в таблице 22.
Таблица 22
Наименование | Путь | Кратность | Тип данных/Формат | Описание | |
authorisation | authorisation |
|
|
| |
| authorisationType | authorisation/authorisationType | [1..1] | Max16Text | Тип запроса авторизации согласия от пользователя API (согласно описанию справочника AuthorisationTypeStaticType. Тип запроса авторизации в таблице 75) |
completionDateTime | authorisation/completionDateTime | [0..1] | ISODateTime, | Дата и время, до которого авторизация должна завершиться | |
70. Объект multiAuthorisation.
Объект multiAuthorisation используется для предоставления информации о текущем состоянии множественной авторизации. Модель данных объекта multiAuthorisation представлена на рисунке 20.
Рисунок 20
Атрибутный состав объекта multiAuthorisation приведен в таблице 23.
Таблица 23
Наименование | Путь | Кратность | Тип данных/Формат | Описание | |
multiAuthorisation | multiAuthorisation |
|
|
| |
| status | multiAuthorisation/status | [1..1] | Max35Text | Статус авторизации (согласно описанию справочника StatusAuthorisationTypeStaticType. Статус авторизации в таблице 76) |
numberRequired | multiAuthorisation/numberRequired | [0..1] | Number | Количество авторизаций, необходимых для инициирования платежа | |
numberReceived | multiAuthorisation/numberReceived | [0..1] | Number | Количество полученных авторизаций | |
lastUpdateDateTime | multiAuthorisation/lastUpdateDateTime | [0..1] | ISODateTime, | Дата и время последнего обновления авторизационного потока | |
expirationDateTime | multiAuthorisation/expirationDateTime | [0..1] | ISODateTime, | Дата и время, до которого авторизация должна быть завершена | |
71. Объект paymentStatus.
Объект paymentStatus используется в ответах на запрос создания и получения статуса платежного указания на инициирование платежа. Модель данных объекта paymentStatus представлена на рисунке 21.
Рисунок 21
Атрибутный состав объекта paymentStatus приведен в таблице 24.
Таблица 24
Наименование | Путь | Кратность | Тип данных/Формат | Описание | ||
paymentStatus | paymentStatus |
|
| Детализированная информация о статусе платежного указания на инициирование платежа | ||
| paymentStatus | paymentStatus/paymentStatus | [1..1] | Max4Text | Код статуса платежного указания (согласно справочнику E065, таблица 80) | |
statusUpdateDateTime | paymentStatus/statusUpdateDateTime | [1..1] | ISODateTime, | Дата и время обновления статуса платежного указания | ||
statusReasonInformation | paymentStatus/statusReasonInformation | [0..1] |
| Детальная информация о причине статуса (отмены) | ||
| statusReasonCode | paymentStatus/statusReasonInformation/statusReasonCode | [1..1] | Max4Text | Код причины отмены платежного указания (согласно справочнику E066, таблица 80) | |
additionalInformation | paymentStatus/statusReasonInformation/additionalInformation | [0..1] | Max140Text | Наименование кода причины отмены. Дополнительная информация причины отмены, содержит текстовую расшифровку кодов или собственное значение | ||
72. Объект taxRemittance.
Объект taxRemittance используется в запросах и ответах на инициирование платежа плательщиком в бюджет, входит в состав объекта initiation. Модель данных объекта taxRemittance представлена на рисунке 22.
Рисунок 22
Атрибутный состав объекта taxRemittance представлен в таблице 25.
Таблица 25
Наименование | Путь | Кратность | Тип данных/Формат | Описание | ||
taxRemittance | taxRemittance | [0..1] |
| Информация о платежах в бюджет (о налогах и сборах) | ||
| referenceNumber | taxRemittance/referenceNumber | [0..1] | Max35Text | Информация о референсе платежа в бюджет, специфичная для государственного (налогового) органа | |
date | taxRemittance/date | [0..1] | ISODate, | Дата, на которую платеж в бюджет должен быть уплачен | ||
category | taxRemittance/category | [1..1] | [0-9]{5} | Определяет код платежа в бюджет, опубликованный государственным (налоговым) органом. В первой позиции элемента данных указывается код вида платежа (согласно справочнику N085, таблица 80), во второй–пятой позициях – коды платежей в бюджет (согласно справочнику N011, таблица 80) | ||
year | taxRemittance/year | [0..1] | ISODate, | Год уплаты платежа в бюджет (налога) | ||
type | taxRemittance/type | [0..1] | [A-Z0-9]{4} | Идентификация периода, связанного с (налоговым) платежом в бюджет (согласно справочнику N102, таблица 80) | ||
fromDate | taxRemittance/fromDate | [0..1] | ISODate, | Начальная дата временного интервала, за который предоставляется (налоговый) отчет платежа в бюджет | ||
toDate | taxRemittance/toDate | [0..1] | ISODate, | Конечная дата временного интервала, за который предоставляется (налоговый) отчет платежа в бюджет | ||
totalAmount | taxRemittance/totalAmount | [0..1] | decimal td=18 fd =5 | Итоговая сумма денежных средств, полученная в результате исчисления платежа в бюджет (налога) для отражения в учете (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||
rate | taxRemittance/rate | [0..1] | 0<=decimal<=100 td=11 fd=10 | Ставка, используемая для исчисления платежа в бюджет (налога) (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||
taxableBaseAmount | taxRemittance/taxableBaseAmount | [0..1] | decimal td=18 fd =5 | Сумма денежных средств, исходя из которой рассчитывается сумма платежа в бюджет (налога) (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||
additionalInformation | taxRemittance/additionalInformation | [0..1] | Max140Text | Дополнительные сведения о платеже в бюджет (налоге) | ||
debtor | taxRemittance/debtor | [1..1] |
| Сторона на дебетовой стороне транзакции, к которой применяется платеж в бюджет (налог) | ||
| taxIdentification | taxRemittance/debtor/taxIdentification | [1..1] | Max35Text | Идентификационный налоговый номер плательщика (в соответствии с описанием, приведенным в подпункте 16.7 пункта 16 настоящего стандарта) | |
creditor | taxRemittance/creditor | [1..1] |
| Сторона – получатель платежа в бюджет (налога) | ||
| taxIdentification | taxRemittance/creditor/taxIdentification | [1..1] | Max35Text | Идентификационный налоговый номер плательщика (в соответствии с описанием, приведенным в подпункте 16.7 пункта 16 настоящего стандарта) | |
ultimateDebtor | taxRemittance/ultimateDebtor | [0..1] |
| Фактическая сторона, которая должна денежную сумму бенефициару, в данном случае – государственному (налоговому) органу | ||
| taxIdentification | taxRemittance/ultimateDebtor/taxIdentification | [1..1] | Max35Text | Идентификационный налоговый номер фактического плательщика (в соответствии с описанием, приведенным в подпункте 16.7 пункта 16 настоящего стандарта) | |
name | taxRemittance/ultimateDebtor/name | [0..1] | Max140Text | Наименование фактического плательщика или уполномоченного представителя фактического плательщика | ||
73. Объект remittanceInformation.
Объект remittanceInformation используется во всех запросах и ответах на инициирование всех видов платежей, входит в состав объекта initiation.
Модель данных объекта remittanceInformation представлена на рисунке 23.
Рисунок 23
Атрибутный состав объекта remittanceInformation представлен в таблице 26.
Таблица 26
Наименование | Путь | Кратность | Тип данных/Формат | Описание | ||
remittanceInformation | remittanceInformation | [0..1] |
| Информация о переводе денежных средств. Предоставляется для сопоставления записи с позициями, расчеты по которым должны быть осуществлены с помощью перевода. Например, коммерческие счета-фактуры в системе учета дебиторской задолженности | ||
| categoryPurposeCode | remittanceInformation/categoryPurposeCode | [1..1] | [A-Z0-9]{4} | Код категории назначения платежа (согласно справочнику E004, таблица 80) | |
proprietaryPurpose | remittanceInformation/proprietaryPurpose | [1..1] | [0-1]{1}[A-Z0-9]{5}.[0-9]{2} | Код назначения платежа и очередность, где: | ||
unstructured | remittanceInformation/unstructured | [0..1] | Max420Text | Информация, позволяющая сопоставлять/сверять записи с позициями, для которых предназначен платеж, такими, как коммерческие счета в системе дебиторской задолженности, в неструктурированной форме | ||
referredDocument | remittanceInformation/referredDocument | [0..5] |
| Информация, представляемая для сопоставления/сверки записи с позициями, расчеты по которым должны быть осуществлены с помощью перевода, например, коммерческие счета-фактуры в системе учета дебиторской задолженности, в структурированной форме. Информация о ссылочных документах | ||
| type | remittanceInformation/referredDocument/type | [1..1] | [A-Z]{4} | Идентификация типа ссылочного документа (согласно справочнику N080, таблица 80 – для указания информации о законодательном акте), (согласно справочнику N101, таблица 80 – для иных ссылочных документов) | |
number | remittanceInformation/referredDocument/number | [1..1] | Max35Text | Номер ссылочного документа | ||
relatedDate | remittanceInformation/referredDocument/relatedDate | [1..1] | ISODate, формат YYYY-MM-DD | Дата ссылочного документа | ||
remittedAmount | remittanceInformation/referredDocument/remittedAmount | [0..1] | decimal td=18 fd =5 | Сумма денежных средств за указанный документ (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||
invoicer | remittanceInformation/referredDocument/invoicer | [0..1] | Max140Text | Уполномоченный орган (взыскатель), идентификация организации, выставившей счет (согласно справочникам N077, N087 и N088, таблица 80) | ||
74. Объект regulatoryReporting.
Объект regulatoryReporting используется в запросах и ответах при инициировании платежа плательщиком в бюджет и инициировании платежа бенефициаром (взыскателем) в бюджет, входит в состав объекта initiation.
Модель данных объекта regulatoryReporting представлена на рисунке 24.
Рисунок 24
Атрибутный состав объекта regulatoryReporting представлен в таблице 27.
Таблица 27
Наименование | Путь | Кратность | Тип данных/ | Описание | |
regulatoryReporting | regulatoryReporting | [0..10] |
| Информация, необходимая в соответствии с требованиями нормативных правовых актов | |
| nameAuthority | regulatoryReporting/nameAuthority | [0..1] | Max140Text | Субъект, требующий предоставления информации отчетности регулятору. |
type | regulatoryReporting/type | [0..1] | Max35Text | Определяет тип информации, представляемой в деталях отчетности регулятору. | |
date | regulatoryReporting/date | [0..1] | ISODate, формат YYYY-MM-DD | Дата, связанная с установленным типом информации отчетности регулятору | |
code | regulatoryReporting/code | [0..1] | Max10Text | Определяет характер, назначение и причину транзакции, которые должны быть отражены в соответствии с требованиями нормативных правовых актов, в кодированной форме | |
amount | regulatoryReporting/amount | [0..1] | decimal td=18 fd =5 | Сумма денежных средств, которая должна быть переведена от плательщика бенефициару до вычета комиссий, выраженная в валюте, определенной инициирующей стороной (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | |
75. Объект initiation.
Объект initiation включает в себя все возможные параметры платежной инструкции. Модель данных объекта initiation представлена на рисунке 25.
Рисунок 25
Атрибутный состав объекта initiation представлен в таблице 28.
Таблица 28
Наименование | Путь | Кратность | Тип данных/Формат | Описание | ||
initiation | initiation |
|
| Параметры, которые отправляются инициирующей стороной поставщику API. Используется для запроса об инициировании платежа плательщиком на счет получателя средств | ||
| instructionIdentification | initiation/instructionIdentification | [1..1] | Max35Text | Уникальный идентификатор платежной инструкции, присвоенный инструктирующей стороной для однозначной идентификации инструкции инструктируемой стороной. Присваивается первым банком в цепочке и передается без изменений | |
endToEndIdentification | initiation/endToEndIdentification | [1..1] | [0-9]{2}.[0-9]{8}.[Max16Text]{1,16}(.[0-9]{1,6})? | Сквозной идентификатор, присвоенный инициирующей стороной для однозначной идентификации транзакции. Эта идентификация передается без изменения по всей сквозной цепочке. | ||
localInstrument | initiation/localInstrument | [0..1] | Max35Text | Элемент используется для указания сервиса или уровня обслуживания, варианта клиринга. Возможные значения: | ||
requestedExecutionDate | initiation/requestedExecutionDate | [0..1] | ISODate, формат YYYY-MM-DD | Дата, в которую денежные средства должны быть списаны со счета плательщика | ||
amount | initiation/amount | [1..1] | decimal td=18 fd =5 | Сумма денежных средств, которая должна быть переведена от плательщика бенефициару до вычета комиссионных вознаграждений, выраженная в валюте, определенной инициирующей стороной (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||
currency | initiation/currency | [1..1] | тип данных ActiveCurrencyCode, формат [A-Z]{3} | Валюта суммы платежа (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||
debtor | initiation/debtor | [0..1] |
| Информация о плательщике (в соответствии с описанием, приведенным в таблице 6). | ||
debtorAccount | initiation/debtorAccount | [0..1] |
| Идентификация счета плательщика | ||
| schemeName | initiation/debtorAccount/schemeName | [1..1] | Max140Text | Наименование схемы идентификации. | |
identification | initiation/debtorAccount/identification | [1..1] | IBAN2007Identifier (для schemeName= BY.NBRB.IBAN), | Уникальная и однозначная идентификация счета, согласованная между владельцем счета и банком, обслуживающим счет (IBAN или идентификация в иной форме) | ||
debtorAgent | initiation/debtorAgent | [0..1] |
| Информация о банке, обслуживающем счет плательщика | ||
| identificationClearingSystem | initiation /debtorAgent/ | [0..1] | Согласно справочнику E005 (таблица 80): [A-Z]{5}, | Идентификация клиринговой системы: в кодированной форме (согласно справочнику E005, таблица 80) или собственная идентификация | |
identification | initiation/debtorAgent/identification | [1..1] | BICFIIdentifier (для кода BIC): | Зарегистрированный код BIC (BICFI) или идентификация участника клиринговой системы. | ||
name | initiation/debtorAgent/name | [1..1] | Max140Text | Наименование банка, обслуживающего счет плательщика | ||
creditor | initiation/creditor | [1..1] |
| Информация о бенефициаре (в соответствии с описанием, приведенным в таблице 6). | ||
creditorAccount | creditor/creditorAccount | [1..1] |
| Идентификация счета бенефициара. | ||
| schemeName | initiation/creditorAccount/schemeName | [1..1] | Max140Text | Наименование схемы идентификации. Схема для осуществления платежа по номеру счета: | |
identification | initiation/creditorAccount/identification | [1..1] | IBAN2007Identifier (для schemeName= BY.NBRB.IBAN), | Уникальная и однозначная идентификация счета, согласованная между владельцем счета и банком, обслуживающим счет (IBAN или идентификация в иной форме) | ||
creditorAgent | initiation/creditorAgent | [0..1] |
| Информация о банке, обслуживающем счет бенефициара | ||
| identificationClearingSystem | initiation/creditorAgent/ | [0..1] | Согласно справочнику E005 (таблица 80): [A-Z]{5}, | Идентификация клиринговой системы: в кодированной форме (согласно справочнику E005, таблица 80) или собственная идентификация | |
identification | initiation/creditorAgent/identification | [1..1] | BICFIIdentifier (для кода BIC): | Зарегистрированный код BIC (BICFI) или идентификация участника клиринговой системы. | ||
name | initiation/creditorAgent/name | [1..1] | Max140Text | Наименование банка, обслуживающего счет бенефициара | ||
ultimateDebtor | initiation/ultimateDebtor | [0..1] |
| Информация о фактическом плательщике (в соответствии с описанием, приведенным в таблице 6) | ||
ultimateCreditor | initiation/ultimateCreditor | [0..1] |
| Информация о фактическом бенефициаре (в соответствии с описанием, приведенным в таблице 6) | ||
taxRemittance | initiation/taxRemittance | [0..1] |
| Информация о платежах в бюджет (налогах и сборах) (в соответствии с описанием, приведенным в таблице 25). | ||
remittanceInformation | initiation/remittanceInformation | [0..1] |
| Информация о переводе денежных средств. Предоставляется для сопоставления записи с позициями, расчеты по которым должны быть осуществлены с помощью перевода. Например, коммерческие счета-фактуры в системе учета дебиторской задолженности (в соответствии с описанием, приведенным в таблице 26) | ||
regulatoryReporting | initiation/regulatoryReporting | [0..10] |
| Информация, необходимая в соответствии с требованиями нормативных правовых актов. Используется только при инициировании платежей в бюджет | ||
listAccounts | initiation/listAccounts | [0..n] |
| Список бенефициаров (физических лиц) с указанием счетов бенефициаров. Используется только при инициировании платежа плательщиком, содержащего список бенефициаров с указанием счетов бенефициаров | ||
| name | initiation/listAccounts/name | [1..1] | Max140Text | Полное фамилия, собственное имя, отчество (если таковое имеется) (далее – Ф.И.О.) физического лица | |
IBAN | initiation/listAccounts/IBAN | [1..1] | IBAN2007Identifier | Международный номер банковского счета физического лица | ||
amount | initiation/listAccounts/amount | [1..1] | decimal td=18 fd =5 | Сумма денежных средств, которая должна быть переведена от плательщика конечному получателю, выраженная в валюте, определенной инициирующей стороной (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||
listPassportData | initiation/listPassportData | [0..n] |
| Список бенефициаров (физических лиц) при осуществлении перевода без открытия счета. | ||
| name | initiation/listPassportData/name | [1..1] | Max140Text | Полное Ф.И.О. физического лица | |
|
| identification | initiation/listPassportData/identification | [1..1] | Max35Text | Уникальная и однозначная идентификация физического лица, где: |
|
| issuer | initiation/listPassportData/issuer | [1..1] | Max35Text | Наименование или код органа, выдавшего документ |
amount | initiation/listPassportData/amount | [1..1] | decimal td=18 fd =5 | Сумма денежных средств, которая должна быть переведена от плательщика конечному получателю, выраженная в валюте, определенной инициирующей стороной (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||
enclosedFile | initiation/enclosedFile | [0..5] |
| Информация о приложенном файле. Документ или образец (шаблон), прилагаемые к уведомлению. | ||
| name | initiation/enclosedFile/name | [0..1] | Max140Text | Наименование документа или операции | |
identification | initiation/enclosedFile/identification | [1..1] | Max4Text | Идентификация приложенного файла (согласно справочнику N101, таблица 80) | ||
format | initiation/enclosedFile/format | [1..1] | Max35Text | Формат приложенного документа или файла, код или в собственной форме. Пример: PDF, XML, XSLT и т.д. | ||
fileName | initiation/enclosedFile/fileName | [1..1] | Max140Text | Техническое наименование файла | ||
issueDate | initiation/enclosedFile/issueDate | [1..1] | ISODate, формат YYYY-MM-DD | Дата оформления приложенного документа (файла) | ||
digitalSignature | initiation/enclosedFile/digitalSignature | [0..1] |
| Цифровая подпись приложенного бинарного файла | ||
enclosure | initiation/enclosedFile/enclosure | [0..1] |
| Бинарный файл, представляющий собой приложенный документ или образец. | ||
supplementaryData | initiation/supplementaryData | [0..1] | – | Дополнительная информация, которая не может быть отражена в структурированных элементах и/или других специальных блоках (в соответствии с описанием, приведенным подпункте 21.4 пункта 21 настоящего стандарта) | ||
76. Объект risk.
Объект risk используется для указания дополнительных деталей для оценки рисков при инициировании платежей. Модель данных объекта risk представлена на рисунке 26.
Рисунок 26
Атрибутный состав объекта risk представлен в таблице 29.
Таблица 29
Наименование | Путь | Кратность | Тип данных/Формат | Описание | ||
risk | risk |
|
|
| ||
| paymentContextCode | risk/paymentContextCode | [0..1] | Max35Text | Код платежа (согласно справочнику N099, таблица 80) | |
merchantCategoryCode | risk/merchantCategoryCode | [0..1] | Max4Text | Код категории, связанный с типом услуг или товаров, которые продавец предоставляет для транзакции (согласно ISO 18245) | ||
merchantCustomerIdentification | risk/merchantCustomerIdentification | [0..1] | Max35Text | Уникальный идентификатор покупателя, который продавец присвоил клиенту | ||
postalAddress | risk/postalAddress | [0..1] |
| Информация, которая позволяет найти и идентифицирует конкретный адрес в формате, устанавливаемом почтовыми службами | ||
| country | risk/postalAddress/country | [1..1] | CountryCode | Страна (согласно ОКРБ 017 и справочнику N013, таблица 80) | |
countrySubDivision | risk/postalAddress/countrySubDivision | [0..1] | Max35Text | Регион/область страны | ||
districtName | risk/postalAddress/districtName | [0..1] | Max35Text | Название административно-территориальной единицы, например: район, сельсовет | ||
townName | risk/postalAddress/townName | [0..1] | Max35Text | Название населенного пункта, может заполняться согласно единому реестру административно-территориальных и территориальных единиц Республики Беларусь с указанием типа населенного пункта (согласно справочнику N091, таблица 80) перед его названием через пробел | ||
townLocationName | risk/postalAddress/townLocationName | [0..1] | Max35Text | Конкретное наименование места в населенном пункте. Используется при необходимости для указания кода СОАТО в соответствии с ОКРБ 003 и согласно справочнику N058, таблица 80 | ||
postCode | risk/postalAddress/postCode | [0..1] | Max16Text | Почтовый код (индекс) | ||
streetName | risk/postalAddress/streetName | [0..1] | Max70Text | Наименование улицы, может заполняться согласно реестру улиц и дорог с указанием типа элемента улично-дорожной сети (согласно справочнику N098, таблица 80) перед его названием через пробел | ||
buildingNumber | risk/postalAddress/buildingNumber | [0..1] | Max16Text | Номер дома | ||
room | risk/postalAddress/room | [0..1] | Max16Text | Номер квартиры, помещения или комнаты | ||
addressLine | risk/deliveryAddress/addressLine | [0..3] | Max70Text | Информация, которая позволяет найти и идентифицирует конкретный адрес в соответствии с данными почтовых служб, в произвольном текстовом формате | ||
Глава 13
Согласие на инициирование платежа
77. Пользователь API создает согласие на инициирование платежа с помощью метода POST.
Первоначально согласие не авторизовано, так как поставщик API еще не верифицировал разрешения непосредственно с самим клиентом. Поставщик API отправляет в ответ идентификатор согласия. Далее этот идентификатор используется при инициировании потока авторизации, который нужен для подтверждения клиентом разрешений.
При авторизации:
1. поставщик API аутентифицирует клиента;
2. поставщик API направляет согласие, полученное от пользователя API, обратно клиенту для непосредственной авторизации;
3. клиент подтверждает согласие, которое было дано пользователю API, но уже на стороне поставщика API;
4. клиент может принять или отклонить согласие только целиком (не частично, так как нет выбора параметров);
Если в согласии не был указан счет плательщика, то поставщик API предоставляет клиенту список счетов на выбор.
После этого согласие считается авторизованным клиентом.
Клиент не может отозвать согласие на инициирование платежа после его авторизации.
Клиент не может изменить выбранный счет для согласия на проведение платежа после того, как это согласие было авторизовано.
Конечная точка POST/paymentConsents/domestic позволяет создавать на стороне поставщика API согласие на проведение платежа без предварительной идентификации клиента.
После создания согласия на инициирование платежа ему присваивается статус «AwaitingAuthorisation».
Конечная точка GET/paymentConsents/domestic/{domesticConsentId} позволяет пользователю API получать детали и статус созданного им согласия по его идентификатору.
78. Статусы согласия.
После авторизации клиентом согласия поставщик API изменяет его статус на «Authorised». При отклонении согласия клиентом поставщик API изменяет статус на «Rejected». При возникновении иных причин, препятствующих проведению платежа, поставщик API изменяет статус согласия на «Rejected». После того, как согласие было задействовано при выполнении платежа, поставщик API изменяет статус на «Consumed». Статус согласия может принимать значения, представленные в таблице 30.
Таблица 30
Наименование статуса | Описание статуса |
AwaitingAuthorisation | Согласие ожидает авторизации |
Authorised | Согласие успешно авторизовано |
Rejected | Согласие отклонено |
Consumed | Согласие было задействовано и больше не может использоваться при инициировании платежа |
Модель состояний согласия на инициирование платежа соответствует схеме, приведенной на рисунке 27.
Рисунок 27
Глава 14
Требования к методам и моделям API для инициирования платежа
79. Основные параметры API для инициирования платежа представлены в таблице 31.
Таблица 31
Вид платежа | API | Параметр | Конечные точки (endpoints) | Описание |
Платеж по инициативе плательщика за товары, работы, услуги | Согласие на инициирование платежа плательщиком за товары, работы, услуги | domesticConsents | POST/paymentConsents/domestic | Создание согласия на инициирование платежа плательщиком за товары, работы, услуги |
GET/paymentConsents/domestic/{domesticConsentId} | Получение статуса согласия на инициирование платежа плательщиком за товары, работы, услуги | |||
Платежное указание на инициирование платежа плательщиком за товары, работы, услуги | domesticPayments | POST/payments/domestic | Создание платежного указания на инициирование платежа плательщиком за товары, работы, услуги | |
GET/payments/domestic/{domesticId} | Получение статуса платежного указания на инициирование платежа плательщиком за товары, работы, услуги | |||
DELETE/payments/domestic/{domesticId} | Отзыв платежного указания на инициирование платежа плательщиком за товары, работы, услуги | |||
Платеж по инициативе плательщика в бюджет | Согласие на инициирование платежа плательщиком в бюджет | domesticTaxConsents | POST/paymentConsents/domesticTax | Создание согласия на инициирование платежа плательщиком в бюджет |
GET/paymentConsents/domesticTax/{domesticTaxConsentId} | Получение статуса согласия на инициирование платежа плательщиком в бюджет | |||
Платежное указание на инициирование платежа плательщиком в бюджет | domesticTaxes | POST/payments/domesticTax | Создание платежного указания на инициирование платежа плательщиком в бюджет | |
GET/payments/domesticTax/{domesticTaxId} | Получение статуса платежного указания на инициирование платежа плательщиком в бюджет | |||
DELETE/payments/domesticTax/{domesticTaxId} | Отзыв платежного указания на инициирование платежа плательщиком в бюджет | |||
Платеж по инициативе плательщика, содержащий список бенефициаров с указанием счетов бенефициаров | Согласие на инициирование платежа плательщиком, содержащее список бенефициаров с указанием счетов бенефициаров | listAccountsConsents | POST/paymentConsents/listAccounts | Создание согласия на инициирование платежа плательщиком, содержащего список бенефициаров с указанием счетов бенефициаров |
GET/paymentConsents/listAccounts/{listAccountsConsentId} | Получение статуса согласия на инициирование платежа плательщиком, содержащего список бенефициаров с указанием счетов бенефициаров | |||
Платежное указание на осуществление платежа по инициативе плательщика, содержащее список бенефициаров с указанием счетов бенефициаров | listAccounts | POST/payments/listAccounts | Создание платежного указания на инициирование платежа плательщиком, содержащего список бенефициаров с указанием счетов бенефициаров | |
GET/payments/listAccounts/{listAccountsId} | Получение статуса платежного указания на инициирование платежа плательщиком, содержащего список бенефициаров с указанием счетов бенефициаров | |||
DELETE/payments/listAccounts/{listAccountsId} | Отзыв платежного указания на инициирование платежа плательщиком, содержащего список бенефициаров с указанием счетов бенефициаров | |||
Платеж по инициативе плательщика, содержащий список бенефициаров при осуществлении перевода без открытия счета | Согласие на инициирование платежа плательщиком, содержащее список бенефициаров при осуществлении перевода без открытия счета | listPassportsConsents | POST/paymentConsents/listPassports | Создание согласия на инициирование платежа плательщиком, содержащего список бенефициаров при осуществлении перевода без открытия счета |
GET/paymentConsents/listPassports/{listPassportsConsentId} | Получение статуса согласия на инициирование платежа плательщиком, содержащего список бенефициаров при осуществлении перевода без открытия счета | |||
Платежное указание на инициирование платежа плательщиком, содержащее список бенефициаров при осуществлении перевода без открытия счета | listPassports | POST/payments/listPassports | Создание платежного указания на инициирование платежа плательщиком, содержащего список бенефициаров при осуществлении перевода без открытия счета | |
GET/payments/listPassports/{listPassportsId} | Получение статуса платежного указания на инициирование платежа плательщиком, содержащего список бенефициаров при осуществлении перевода без открытия счета | |||
DELETE/payments/listPassports/{listPassportsId} | Отзыв платежного указания на инициирование платежа плательщиком, содержащего список бенефициаров при осуществлении перевода без открытия счета | |||
Платеж по инициативе бенефициара за товары, работы, услуги | Согласие на инициирование платежа бенефициаром за товары, работы, услуги | requirementConsents | POST/paymentConsents/requirement | Создание согласия на инициирование платежа бенефициаром за товары, работы, услуги |
GET/paymentConsents/requirement/{requirementConsentId} | Получение статуса согласия на инициирование платежа бенефициаром за товары, работы, услуги | |||
Платежное указание на инициирование платежа по инициативе бенефициара за товары, работы, услуги | requirements | POST/payments/requirement | Создание платежного указания на инициирование платежа бенефициаром за товары, работы, услуги | |
GET/payments/requirement/{requirementId} | Получение статуса платежного указания на инициирование бенефициаром за товары, работы, услуги | |||
DELETE/payments/requirement/{requirementId} | Отзыв платежного указания на инициирование платежа бенефициаром за товары, работы, услуги | |||
Платеж по инициативе бенефициара (взыскателя) в бюджет | Согласие на инициирование платежа бенефициаром (взыскателем) в бюджет | taxRequirementConsents | POST/paymentConsents/taxRequirement | Создание согласия на инициирование платежа бенефициаром (взыскателем) в бюджет |
GET/paymentConsents/taxRequirement/{taxRequirementConsentId} | Получение статуса согласия на инициирование платежа бенефициаром (взыскателем) в бюджет | |||
Платежное указание на инициирование платежа бенефициаром (взыскателем) в бюджет | taxRequirements | POST/payments/taxRequirements | Создание платежного указания на инициирование платежа бенефициаром (взыскателем) в бюджет | |
GET/payments/taxRequirements/{taxRequirementId} | Получение статуса платежного указания на инициирование платежа бенефициаром (взыскателем) в бюджет | |||
DELETE/payments/taxRequirements/{taxRequirementId} | Отзыв платежного указания на инициирование платежа бенефициаром (взыскателем) в бюджет | |||
Рекуррентный платеж | Согласие на инициирование рекуррентного платежа | VRPConsents | POST/paymentConsents/VRP | Создание долгосрочного согласия на инициирование рекуррентного платежа |
GET/paymentConsents/VRP/{VRPConsentId} | Получение статуса долгосрочного согласия на инициирование рекуррентного платежа | |||
DELETE/paymentConsents/VRP/{VRPConsentId} | Отзыв (удаление) долгосрочного согласия на инициирование рекуррентного платежа | |||
Платежное указание на инициирование платежа | VRP | POST/payments/VRP | Создание платежного указания на инициирование платежа | |
GET/payments/VRP/{VRPId} | Получение статуса платежного указания на инициирование платежа | |||
DELETE/payments/VRP/{VRPId} | Отзыв платежного указания на инициирование платежа |
80. Методы и модели платежа по инициативе плательщика за товары, работы, услуги (далее для целей настоящего пункта – платеж).
Рассматриваются следующие методы и модели:
создания и получения статуса согласия на инициирование платежа;
создания и получения статуса платежного указания на инициирование платежа.
80.1. Методы и модели данных, атрибутный состав запроса и ответа на создание и получение статуса согласия на инициирование платежа.
Модель данных запроса на создание согласия POST/paymentConsents/domestic на инициирование платежа представлена на рисунке 28.
Рисунок 28
Атрибутный состав запроса на создание согласия POST/paymentConsents/domestic на инициирование платежа представлен в таблице 32.
Таблица 32
Наименование | Путь | Кратность | Описание | Комментарии | ||
domesticConsentRequest |
|
|
|
| ||
| data | domesticConsentRequest/data | [1..1] |
|
| |
| initiation | domesticConsentRequest/data/initiation | [1..1] | Инициирующая сторона отправляет параметры данных поставщику API. Данный объект используется для запроса перевода средств со счета плательщика на счет получателя средств для одиночного платежа | Согласно описанию объекта initiation в таблице 28 | |
authorisation | domesticConsentRequest/data/authorisation | [0..1] | Запрос типа авторизации от пользователя API | Согласно описанию объекта authorisation в таблице 22 | ||
risk | domesticConsentRequest/risk | [1..1] | Данный объект отправляется инициатором поставщику API и используется для указания дополнительных деталей для оценки рисков при проведении платежей | Согласно описанию объекта risk в таблице 29 | ||
Модель ответа на запросы на создание согласия POST/paymentConsents/domestic и получение статуса согласия GET/paymentConsents/domestic/{domesticConsentId} на инициирование платежа представлена на рисунке 29.
Рисунок 29
Атрибутный состав ответа на запросы на создание согласия POST/paymentConsents/domestic и получение статуса согласия GET/paymentConsents/domestic/{domesticConsentId} на инициирование платежа представлен в таблице 33.
Таблица 33
Наименование | Путь | Кратность | Тип данных/Формат | Описание | Комментарии | ||
domesticConsentResponse |
|
|
|
|
| ||
| data | domesticConsentResponse/data | [1..1] |
|
| – | |
| domesticConsentId | domesticConsentResponse/data/domesticConsentId | [1..1] | Max35Text | Идентификатор согласия | – | |
link | domesticConsentResponse/data/link | [1..1] | Max140Text | Ссылка на согласие | – | ||
creationDateTime | domesticConsentResponse/data/creationDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время создания согласия | – | ||
status | domesticConsentResponse/data/status | [1..1] | Max35Text | Текущий статус согласия (согласно описанию в таблице 30) | – | ||
statusUpdateDateTime | domesticConsentResponse/data/statusUpdateDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время обновления статуса согласия | – | ||
cutOffDateTime | domesticConsentResponse/data/cutOffDateTime | [0..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время, до которого работает платежная система | – | ||
expectedExecutionDate | domesticConsentResponse/data/expectedExecutionDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата исполнения платежа, списания средств со счета плательщика | – | ||
expectedSettlementDate | domesticConsentResponse/data/expectedSettlementDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата расчета платежа, зачисления средств на счет получателя | – | ||
initiation | domesticConsentResponse/data/initiation | [1..1] |
| Исходные параметры блока initiation | Согласно описанию объекта initiation в таблице 28 | ||
charge | domesticConsentResponse/data/charge | 0..n |
| Комиссионное вознаграждение поставщика API | Согласно описанию объекта charge в таблице 21 | ||
authorisation | domesticConsentResponse/data/authorisation | [0..1] |
| Тип авторизации от поставщика API | Согласно описанию объекта authorisation в таблице 22 | ||
risk | domesticConsentResponse/risk | [1..1] |
| Исходные параметры блока risk | Согласно описанию объекта risk в таблице 29 | ||
80.2. Методы и модели данных, атрибутный состав запроса и ответа на создание и получение статуса платежного указания на инициирование платежа.
Модель данных запроса на создание платежного указания на инициирование платежа POST/payments/domestic представлен на рисунке 30.
Рисунок 30
Атрибутный состав запроса на создание платежного указания на инициирование платежа POST/payments/domestic представлен в таблице 34.
Таблица 34
Наименование | Путь | Кратность | Тип данных/ | Описание | Комментарии | ||
domesticRequest |
|
|
|
|
| ||
| data | domesticRequest/data | [1..1] |
|
|
| |
| domesticConsentId | domesticRequest/data/domesticConsentId | [1..1] | Max35Text | Идентификатор согласия, присвоенный на стороне поставщика API |
| |
initiation | domesticRequest/data/initiation | [1..1] |
| Исходные параметры блока initiation | Согласно описанию объекта initiation в таблице 28 | ||
| risk | domesticRequest/risk | [1..1] |
| Исходные параметры блока risk | Согласно описанию объекта risk в таблице 29 | |
Модель данных для ответа на создание платежного указания на инициирование платежа POST/payments/domestic и получение статуса платежного указания на инициирование платежа GET/payments/domestic/{domesticId} представлена на рисунке 31.
Рисунок 31
Атрибутный состав ответа на запрос создания платежного указания на инициирование платежа POST/payments/domestic и получения статуса платежного указания на инициирование платежа GET/payments/domestic/{domesticId} представлен в таблице 35.
Таблица 35
Наименование | Путь | Кратность | Тип данных/ | Описание | Комментарии | ||
domesticResponse |
|
|
|
|
| ||
| data | domesticResponse/data | [1..1] |
|
|
| |
| domesticId | domesticResponse/data/domesticId | [1..1] | Max35Text | Идентификатор платежного указания |
| |
domesticConsentId | domesticResponse/data/domesticConsentId | [1..1] | Max35Text | Идентификатор согласия, присвоенный на стороне поставщика API |
| ||
creationDateTime | domesticResponse /data/creationDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh | Дата и время создания платежного указания |
| ||
expectedExecutionDate | domesticResponse/data/expectedExecutionDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата исполнения платежа, списания средств со счета плательщика |
| ||
expectedSettlementDate | domesticResponse/data/expectedSettlementDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата расчета платежа, зачисления средств на счет получателя |
| ||
initiation | domesticResponse/data/initiation | [1..1] |
| Исходные параметры блока initiation | Согласно описанию объекта initiation в таблице 28 | ||
charge | domesticResponse/data/charges | [0..n] |
| Комиссионное вознаграждение поставщика API | Согласно описанию объекта charge в таблице 21 | ||
multiAuthorisation | domesticResponse/data/multiAuthorisation | [0..1] |
| Параметры ответа потока множественной авторизации от поставщика API | Согласно описанию объекта multiAuthorisation в таблице 23 | ||
paymentStatus | domesticResponse/data/paymentStatus | [1..1] |
| Параметры статуса платежного указания на инициирование платежа | Согласно описанию объекта paymentStatus в таблице 24 | ||
80.3. Метод для отзыва платежного указания на инициирование платежа.
Клиент имеет возможность отозвать платежное указание на инициирование платежа, отправив запрос DELETE/payments/domestic/{domesticId}.
При невозможности отзыва платежного указания на инициирование платежа поставщик API возвращает ошибку с кодом 400 Bad Request с указанием errorCode=BY.NBRB.Resource.NotCancel.
81. Методы и модели платежа по инициативе плательщика в бюджет (далее для целей настоящего пункта – платеж в бюджет).
Рассматриваются следующие методы и модели:
создание и получение статуса согласия на инициирование платежа в бюджет;
создание и получение статуса платежного указания на инициирование платежа в бюджет.
81.1. Методы и модели данных, атрибутный состав запроса и ответа на создание и получение статуса согласия на инициирование платежа в бюджет.
Модель данных запроса на создание согласия POST/paymentConsents/domesticTax на инициирование платежа в бюджет представлена на рисунке 32.
Рисунок 32
Атрибутный состав запроса на создание согласия POST/paymentConsents/domesticTax на инициирование платежа в бюджет представлен в таблице 36.
Таблица 36
Наименование | Путь | Кратность | Описание | Комментарии | ||
domesticTaxConsentRequest |
|
|
|
| ||
| data | domesticTaxConsentRequest/data | [1..1] |
|
| |
| initiation | domesticTaxConsentRequest/data/initiation | [1..1] | Инициирующая сторона отправляет параметры данных поставщику API. Данный объект используется для запроса перевода средств со счета плательщика на счет получателя средств для платежа в бюджет | Согласно описанию объекта initiation в таблице 28 | |
authorisation | domesticTaxConsentRequest/data/authorisation | [0..1] | Запрос типа авторизации от пользователя API | Согласно описанию объекта authorisation в таблице 22 | ||
Модель ответа на запрос на создание согласия POST/paymentConsents/domesticTax и получение статуса согласия GET/paymentConsents/domesticTax/{domesticTaxConsentId} на инициирование платежа в бюджет представлена на рисунке 33.
Рисунок 33
Атрибутный состав ответа на запрос на создание согласия POST/paymentConsents/domesticTax и получение статуса согласия GET/paymentConsents/domesticTax/{domesticTaxConsentId} на инициирование платежа в бюджет представлен в таблице 37.
Таблица 37
Наименование | Путь | Кратность | Тип данных/Формат | Описание | Комментарии | ||
domesticTaxConsentResponse |
|
|
|
|
| ||
| data | domesticTaxConsentResponse/data | [1..1] |
|
|
| |
| domesticTaxConsentId | domesticTaxConsentResponse/data/domesticTaxConsentId | [1..1] | Max35Text | Идентификатор согласия | – | |
link | domesticTaxConsentResponse/data/link | [1..1] | Max140Text | Ссылка на согласие | – | ||
creationDateTime | domesticTaxConsentResponse/data/creationDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время создания согласия | – | ||
status | domesticTaxConsentResponse/data/status | [1..1] | Max35Text | Текущий статус согласия (согласно описанию в таблице 30) | – | ||
statusUpdateDateTime | domesticTaxConsentResponse/data/statusUpdateDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время обновления статуса согласия | – | ||
cutOffDateTime | domesticTaxConsentResponse/data/cutOffDateTime | [0..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время, до которого работает платежная система | – | ||
expectedExecutionDate | domesticTaxConsentResponse/data/expectedExecutionDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата исполнения платежа, списания средств со счета плательщика | – | ||
|
| expectedSettlementDate | domesticTaxConsentResponse/data/expectedSettlementDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата расчета платежа, зачисления средств на счет получателя | – |
|
| initiation | domesticTaxConsentResponse/data/initiation | [1..1] |
| Исходные параметры блока initiation | Согласно описанию объекта initiation в таблице 28 |
|
| authorisation | DomesticTaxConsentResponse/data/authorisation | [0..1] |
| Тип авторизации от поставщика API | Согласно описанию объекта authorisation в таблице 22 |
81.2. Методы и модели данных, атрибутный состав запроса и ответа на создание и получение статуса платежного указания на инициирование платежа в бюджет.
Модель данных запроса на создание платежного указания на инициирование платежа в бюджет POST/payments/domesticTax представлена на рисунке 34.
Рисунок 34
Атрибутный состав запроса на создание платежного указания на инициирование платежа в бюджет POST/payments/domesticTax представлен в таблице 38.
Таблица 38
Наименование | Путь | Кратность | Тип данных/Формат | Описание | Комментарии | ||
domesticTaxRequest |
|
|
|
|
| ||
| data | domesticTaxRequest/data | [1..1] |
|
|
| |
| domesticTaxConsentId | domesticTaxRequest/data/domesticTaxConsentId | [1..1] | Max35Text | Идентификатор согласия, присвоенный на стороне поставщика API | – | |
initiation | domesticTaxRequest/data/initiation | [1..1] |
| Исходные параметры блока initiation | Согласно описанию объекта initiation в таблице 28 | ||
Модель данных ответа на запросы на создание платежного указания на инициирование платежа в бюджет POST/payments/domesticTax и получение статуса платежного указания на инициирование платежа в бюджет GET/payments/domesticTax/{domesticTaxId} представлена на рисунке 35.
Рисунок 35
Атрибутный состав ответа на запросы на создание платежного указания на инициирование платежа в бюджет POST/payments/domesticTax и получение статуса платежного указания на инициирование платежа в бюджет GET/payments/domesticTax/{domesticTaxId} представлен в таблице 39.
Таблица 39
Наименование | Путь | Кратность | Тип данных/Формат | Описание | Комментарии | ||
domesticTaxResponse |
|
|
|
|
| ||
| data | domesticTaxResponse/data | [1..1] |
|
|
| |
| domesticTaxId | domesticTaxResponse/data/domesticTaxId | [1..1] | Max35Text | Идентификатор платежного указания | – | |
domesticTaxConsentId | domesticTaxResponse/data/domesticTaxConsentId | [1..1] | Max35Text | Идентификатор согласия, присвоенный на стороне поставщика API | – | ||
creationDateTime | domesticTaxResponse/data/creationDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss ±hh | Дата и время создания платежного указания | – | ||
expectedExecutionDate | domesticTaxResponse/data/expectedExecutionDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата исполнения платежа, списания средств со счета плательщика | – | ||
expectedSettlementDate | domesticTaxResponse/data/expectedSettlementDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата расчета платежа в бюджет, зачисления средств на счет получателя | – | ||
initiation | domesticTaxResponset/data/initiation | [1..1] |
| Исходные параметры блока initiation | Согласно описанию объекта initiation в таблице 28 | ||
multiAuthorisation | domesticTaxResponse/data/multiAuthorisation | [0..1] |
| Параметры ответа потока множественной авторизации от поставщика API | Согласно описанию объекта multiAuthorisation в таблице 23 | ||
paymentStatus | domesticTaxResponse/data/paymentStatus | [1..1] |
| Параметры статуса платежного указания на инициирование платежа в бюджет | Согласно описанию объекта paymentStatus в таблице 24 | ||
81.3. Метод для отзыва платежного указания на инициирование платежа в бюджет.
Клиент имеет возможность отозвать платежное указание на инициирование платежа в бюджет, отправив запрос DELETE/payments/domesticTax/{domesticTaxId}.
При невозможности отзыва платежного указания на инициирование платежа в бюджет поставщик API возвращает ошибку с кодом 400 Bad Request с указанием errorCode=BY.NBRB.Resource.NotCancel.
82. Методы и модели платежа по инициативе плательщика, содержащего список бенефициаров с указанием счетов бенефициаров (далее для целей настоящего пункта – платеж, содержащий список счетов бенефициаров).
Рассматриваются следующие методы и модели:
создание и получение статуса согласия на инициирование платежа, содержащего список счетов бенефициаров;
создание и получение статуса платежного указания на инициирование платежа, содержащего список счетов бенефициаров.
82.1. Методы и модели данных, атрибутный состав запроса и ответа на создание и получение статуса согласия на инициирование платежа, содержащего список счетов бенефициаров.
Модель данных запроса на создание согласия POST/paymentConsents/listAccounts на инициирование платежа, содержащего список счетов бенефициаров представлена на рисунке 36.
Рисунок 36
Атрибутный состав запроса на создание согласия POST/paymentConsents/listAccounts на инициирование платежа, содержащего список счетов бенефициаров представлен в таблице 40.
Таблица 40
Наименование | Путь | Кратность | Описание | Комментарии | ||
listAccountsConsentRequest |
|
|
|
| ||
| data | listAccountsConsentRequest/data | [1..1] |
|
| |
| initiation | listAccountsConsentRequest/data/initiation | [1..1] | Инициирующая сторона отправляет параметры данных поставщику API. Данный объект используется для запроса перевода средств со счета плательщика на счет получателей средств | Согласно описанию объекта initiation в таблице 28 | |
authorisation | listAccountsConsentRequest/data/authorisation | [0..1] | Запрос типа авторизации от пользователя API | Согласно описанию объекта authorisation в таблице 22 | ||
Модель ответа на запросы на создание согласия POST/paymentConsents/listAccounts и получение статуса согласия GET/paymentConsents/listAccounts/{listAccountsConsentId} на инициирование платежа, содержащего список счетов бенефициаров, представлена в диаграмме на рисунке 37.
Рисунок 37
Атрибутный состав ответа на запросы на создание согласия POST/paymentConsents/listAccounts и получение статуса согласия GET/paymentConsents/listAccounts/{listAccountsConsentid} на инициирование платежа, содержащего список счетов бенефициаров представлен в таблице 41.
Таблица 41
Наименование | Путь | Кратность | Тип данных/Формат | Описание | Комментарии | ||
listAccountsConsentResponse |
|
|
|
|
| ||
| data | listAccountsConsentResponse/data | [1..1] |
|
|
| |
| listAccountsConsentId | listAccountsConsentResponse/data/listAccountsConsentId | [1..1] | Max35Text | Идентификатор согласия | – | |
link | listAccountsConsentResponse/data/link | [1..1] | Max140Text | Ссылка на согласие |
| ||
creationDateTime | listAccountsConsentResponse/data/creationDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время создания согласия | – | ||
status | listAccountsConsentResponse/data/status | [1..1] | Max35Text | Текущий статус согласия (согласно описанию в таблице 30) | – | ||
statusUpdateDateTime | listAccountsConsentResponse/data/statusUpdateDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время обновления статуса согласия | – | ||
cutOffDateTime | listAccountsConsentResponse/data/cutOffDateTime | [0..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время, до которого работает платежная система | – | ||
expectedExecutionDate | listAccountsConsentResponse/data/expectedExecutionDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата исполнения платежа, содержащего список счетов бенефициаров, списания средств со счета плательщика | – | ||
expectedSettlementDate | listAccountsConsentResponse/data/expectedSettlementDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата расчета платежа, содержащего список счетов бенефициаров, зачисления средств на счет получателя | – | ||
initiation | listAccountsConsentResponse/data/initiation | [1..1] |
| Исходные параметры блока initiation | Согласно описанию объекта initiation в таблице 28 | ||
charge | listAccountsConsentResponse/data/charges | [0..n] |
| Комиссионное вознаграждение поставщика API | Согласно описанию объекта charge в таблице 21 | ||
authorisation | listAccountsConsentResponse/data/authorisation | [0..1] |
| Тип авторизации от поставщика API | Согласно описанию объекта authorisation в таблице 22 | ||
82.2. Методы и модели данных, атрибутный состав запроса и ответа на создание и получение статуса платежного указания на инициирование платежа, содержащего список счетов бенефициаров.
Модель данных запроса на создание платежного указания на инициирование платежа, содержащего список счетов бенефициаров POST/payments/listAccounts представлена на рисунке 38.
Рисунок 38
Атрибутный состав запроса на создание платежного указания на инициирование платежа, содержащего список счетов бенефициаров POST/payments/listAccounts представлен в таблице 42.
Таблица 42
Наименование | Путь | Кратность | Тип данных/ | Описание | Комментарии | ||
listAccountsRequest |
|
|
|
|
| ||
| data | listAccountsRequest/data | [1..1] |
|
|
| |
| listAccountsConsentId | listAccountsRequest/data/listAccountsConsentId | [1..1] | Max35Text | Идентификатор согласия, присвоенный на стороне поставщика API | – | |
initiation | listAccountsRequest/data/initiation | [1..1] |
| Исходные параметры блока initiation | Согласно описанию объекта initiation в таблице 28 | ||
Модель данных ответа на запросы на создание платежного указания на инициирование платежа, содержащего список счетов бенефициаров POST/payments/listAccounts и получение статуса платежного указания на инициирование платежа, содержащего список счетов бенефициаров GET/payments/listAccounts/{listAccountsId} представлена на рисунке 39.
Рисунок 39
Атрибутный состав ответа на запросы на создание платежного указания на инициирование платежа, содержащего список счетов бенефициаров POST/payments/listAccounts и получение статуса платежного указания на инициирование платежа, содержащего список счетов бенефициаров GET/payments/listAccounts/{listAccountsId} представлен в таблице 43.
Таблица 43
Наименование | Путь | Кратность | Тип данных/ | Описание | Комментарии | ||
listAccountsResponse |
|
|
|
|
| ||
| data | listAccountsResponse/data | [1..1] |
|
|
| |
| listAccountsId | listAccountsResponse/data/listAccountsId | [1..1] | Max35Text | Идентификатор платежного указания | – | |
listAccountsConsentId | listAccountsResponse/data/listAccountsConsentId | [1..1] | Max35Text | Идентификатор согласия, присвоенный на стороне поставщика API | – | ||
creationDateTime | listAccountsResponse/data/creationDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss ±hh | Дата и время создания платежного указания | – | ||
expectedExecutionDate | listAccountsResponse/data/expectedExecutionDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата исполнения платежа, списания средств со счета плательщика | – | ||
expectedSettlementDate | listAccountsResponse/data/expectedSettlementDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата расчета платежа, зачисления средств на счет получателя | – | ||
initiation | listAccountsResponse/data/Initiation | [1..1] |
| Исходные параметры блока initiation | Согласно описанию объекта initiation в таблице 28 | ||
charge | listAccountsResponse/data/charges | [0..n] |
| Комиссионное вознаграждение поставщика API | Согласно описанию объекта charge в таблице 21 | ||
multiAuthorisation | listAccountsResponse/data/multiAuthorisation | [0..1] |
| Параметры ответа потока множественной авторизации от поставщика API | Согласно описанию объекта multiAuthorisation в таблице 23 | ||
paymentStatus | listAccountsResponse/data/paymentStatus | [1..1] |
| Параметры статуса платежного указания на инициирование платежа, содержащего список счетов бенефициаров | Согласно описанию объекта paymentStatus в таблице 24 | ||
82.3. Метод для отзыва платежного указания на инициирование платежа, содержащего список счетов бенефициаров.
Клиент имеет возможность отозвать платежное указание на инициирование платежа, содержащее список счетов бенефициаров, отправив запрос DELETE/payments/listAccounts/{listAccountsId}.
При невозможности отзыва платежного указания на инициирование платежа, содержащего список счетов бенефициаров, поставщик API возвращает ошибку с кодом 400 Bad Request с указанием errorCode=BY.NBRB.Resource.NotCancel.
83. Методы и модели данных платежа по инициативе плательщика, содержащего список бенефициаров при инициировании перевода без открытия счета (далее для целей настоящего пункта – платеж, содержащий список бенефициаров без открытия счета).
Рассматриваются следующие методы и модели:
создание и получение статуса согласия на инициирование платежа, содержащего список бенефициаров без открытия счета;
создание и получение статуса платежного указания на инициирование платежа, содержащего список бенефициаров без открытия счетов.
83.1. Методы и модели данных, атрибутный состав запроса и ответа на создание согласия и получение статуса согласия на инициирование платежа, содержащего список бенефициаров без открытия счета.
Модель данных запроса на создание согласия POST/paymentConsents/listPassports на инициирование платежа, содержащего список бенефициаров без открытия счета представлена на рисунке 40.
Рисунок 40
Атрибутный состав запроса на создание согласия POST/paymentConsents/listPassports на инициирование платежа, содержащего список бенефициаров без открытия счета представлен в таблице 44.
Таблица 44
Наименование | Путь | Кратность | Описание | Комментарии | ||
listPassportsConsentRequest |
|
|
|
| ||
| data | listPassportsConsentRequest/data | [1..1] |
|
| |
| initiation | listPassportsConsentRequest/data/initiation | [1..1] | Инициирующая сторона отправляет параметры данных поставщику API. Данный объект используется для запроса перевода средств со счета плательщика на счет получателей средств | Согласно описанию объекта initiation в таблице 28 | |
authorisation | listPassportsConsentRequest/data/authorisation | [0..1] | Запрос типа авторизации от пользователя API | Согласно описанию объекта authorisation в таблице 22 | ||
Модель данных ответа на запросы на создание согласия POST/paymentConsents/listPassports и получение статуса согласия GET/paymentConsents/listPassports/{listPassportsConsentId} на инициирование платежа, содержащего список бенефициаров без открытия счета представлена на рисунке 41.
Рисунок 41
Атрибутный состав ответа на запросы на создание согласия POST/paymentConsents/listPassports и получение статуса согласия GET/paymentConsents/listPassports/{listPassportsConsentId} на инициирование платежа, содержащего список бенефициаров без открытия счета представлен в таблице 45.
Таблица 45
Наименование | Путь | Кратность | Тип данных/Формат | Описание | Комментарии | ||
listPassportsConsentResponse |
|
|
|
|
| ||
| data | listPassportsConsentResponse/data | [1..1] |
|
|
| |
| listPassportsConsentId | listPassportsConsentResponse/data/listPassportsConsentId | [1..1] | Max35Text | Идентификатор согласия | – | |
link | listPassportsConsentResponse/data/link | [1..1] | Max140Text | Ссылка на согласие | – | ||
creationDateTime | listPassportsConsentResponse/data/creationDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время создания согласия | – | ||
status | listPassportsConsentResponse/data/status | [1..1] | Max35Text | Текущий статус согласия (согласно описанию в таблице 30) | – | ||
statusUpdateDateTime | listPassportsConsentResponse/data/statusUpdateDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время обновления статуса согласия | – | ||
cutOffDateTime | listPassportsConsentResponse/data/cutOffDateTime | [0..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время, до которого работает платежная система | – | ||
expectedExecutionDate | listPassportsConsentResponse/data/expectedExecutionDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата исполнения платежа, списания средств со счета плательщика | – | ||
expectedSettlementDate | listPassportsConsentResponse/data/expectedSettlementDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата расчета платежа, зачисления средств на счет получателя | – | ||
initiation | listPassportsConsentResponse/data/initiation | [1..1] |
| Исходные параметры блока initiation | Согласно описанию объекта initiation в таблице 28 | ||
charge | listPassportsConsentResponse/data/charges | [0..n] |
| Комиссионное вознаграждение поставщика API | Согласно описанию объекта charge в таблице 21 | ||
authorisation | listPassportsConsentResponse/data/authorisation | [0..1] |
| Тип авторизации от поставщика API | Согласно описанию объекта authorisation в таблице 22 | ||
83.2. Методы и модели данных, атрибутный состав запроса и ответа на создание и получение статуса платежного указания на инициирование платежа, содержащего список бенефициаров без открытия счета.
Модель данных запроса на создание платежного указания на инициирование платежа, содержащего список бенефициаров без открытия счета POST/paymentConsents/listPassports представлена на рисунке 42.
Рисунок 42
Атрибутный состав запроса на создание платежного указания на инициирование платежа, содержащего список бенефициаров без открытия счета POST/paymentConsents/listPassports представлен в таблице 46.
Таблица 46
Наименование | Путь | Кратность | Тип данных/ | Описание | Комментарии | ||
listPassportsRequest |
|
|
|
|
| ||
| data | listPassportsRequest/data | [1..1] |
|
|
| |
| listPassportsConsentId | listPassportsRequest/data/listPassportsConsentId | [1..1] | Max35Text | Идентификатор согласия, присвоенный на стороне поставщика API | – | |
initiation | listPassportsRequest/data/initiation | [1..1] |
| Исходные параметры блока initiation | Согласно описанию объекта initiation в таблице 28 | ||
Модель данных ответа на запросы создания платежного указания POST/paymentConsents/listPassports и получения статуса платежного указания GET/paymentConsents/listPassports/{listPassportsConsentId} на инициирование платежа, содержащего список бенефициаров без открытия счета представлена на рисунке 43.
Рисунок 43
Атрибутный состав ответа на запросы создания платежного указания POST/paymentConsents/listPassports и получения статуса платежного указания GET/paymentConsents/listPassports/{listPassportsConsentId} на инициирование платежа, содержащего список бенефициаров без открытия счета представлен в таблице 47.
Таблица 47
Наименование | Путь | Кратность | Тип данных/Формат | Описание | Комментарии | ||
listPassportsResponse |
|
|
|
|
| ||
| data | listPassportsResponse/data | [1..1] |
|
|
| |
| listPassportsId | listPassportsResponse/data/listPassportsId | [1..1] | Max35Text | Идентификатор платежного указания | – | |
listPassportsConsentId | listPassportsResponse/data/listPassportsConsentId | [1..1] | Max35Text | Идентификатор согласия, присвоенный на стороне поставщика API | – | ||
creationDateTime | listPassportsResponse/data/creationDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss ±hh | Дата и время создания платежного указания | – | ||
expectedExecutionDate | listPassportsResponse/data/expectedExecutionDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата исполнения платежа, списания средств со счета плательщика | – | ||
expectedSettlementDate | listPassportsResponse/data/expectedSettlementDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата расчета платежа, зачисления средств на счет получателя | – | ||
initiation | listPassportsResponse/data/initiation | [1..1] |
| Исходные параметры блока initiation | Согласно описанию объекта initiation в таблице 28 | ||
charge | listPassportsResponse/data/charges | [0..n] |
| Комиссионное вознаграждение поставщика API | Согласно описанию объекта charge в таблице 21 | ||
multiAuthorisation | listPassportsResponse/data/multiAuthorisation | [0..1] |
| Параметры ответа потока множественной авторизации от поставщика API | Согласно описанию объекта multiAuthorisation в таблице 23 | ||
paymentStatus | listPassportsResponse/data/paymentStatus | [1..1] |
| Параметры статуса платежного указания на инициирование платежа, содержащего список бенефициаров без открытия счета | Согласно описанию объекта paymentStatus в таблице 24 | ||
83.3. Метод для отзыва платежного указания на инициирование платежа, содержащего список бенефициаров без открытия счета.
Клиент имеет возможность отозвать платежное указание на инициирование платежа, содержащего список бенефициаров без открытия счета, отправив запрос DELETE/payments/listPassports/{listPassportsId}.
При невозможности отзыва поставщик API возвращает ошибку с кодом 400 Bad Request с указанием errorCode=BY.NBRB.Resource.NotCancel.
84. Методы и модели платежа по инициативе бенефициара (взыскателя) в бюджет.
Рассматриваются следующие методы и модели данных:
создание и получение статуса согласия на инициирование платежа бенефициаром (взыскателем) в бюджет;
создание и получение статуса платежного указания на инициирование платежа бенефициаром (взыскателем) в бюджет.
84.1. Методы и модели создания и получения статуса согласия на инициирование платежа бенефициаром (взыскателем) в бюджет.
Модель запроса на создание согласия POST/paymentConsents/taxRequirement на инициирование платежа бенефициаром (взыскателем) в бюджет представлена на рисунке 44.
Рисунок 44
Атрибутный состав запроса на создание согласия POST/paymentConsents/taxRequirement на инициирование платежа бенефициаром (взыскателем) в бюджет представлен в таблице 48.
Таблица 48
Наименование | Путь | Кратность | Описание | Комментарии | ||
taxRequirementConsentRequest |
|
|
|
| ||
| data | taxRequirementConsentRequest/data | [1..1] |
|
| |
| initiation | taxRequirementConsentRequest/data/initiation | [1..1] | Инициирующая сторона отправляет параметры данных поставщику API. Данный объект используется для запроса перевода средств со счета плательщика на счет бенефициара при инициировании платежа бенефициаром (взыскателем) в бюджет | Согласно описанию объекта initiation в таблице 28 | |
authorisation | taxRequirementConsentRequest/data/authorisation | [0..1] | Запрос типа авторизации от пользователя API | Согласно описанию объекта authorisation в таблице 22 | ||
Модель ответа на запросы на создание согласия POST/paymentConsents/taxRequirement и получение статуса согласия GET/paymentConsents/taxRequirement/{taxRequirementConsentId} на инициирование платежа бенефициаром (взыскателем) в бюджет представлена на рисунке 45.
Рисунок 45
Атрибутный состав ответа на запросы на создание согласия POST/paymentConsents/taxRequirement и получение статуса согласия GET/paymentConsents/taxRequirement/{taxRequirementConsentId} на инициирование платежа бенефициаром (взыскателем) в бюджет приведен в таблице 49.
Таблица 49
Наименование | Путь | Кратность | Тип данных/Формат | Описание | Комментарии | ||
taxRequirementConsentResponse |
|
|
|
|
| ||
| data | taxRequirementConsentResponse/data | [1..1] |
|
|
| |
| taxRequirementConsentId | taxRequirementConsentResponse/data/taxRequirementConsentId | [1..1] | Max35Text | Идентификатор согласия | – | |
link | taxRequirementConsentResponse/data/link | [1..1] | Max140Text | Ссылка на согласие | – | ||
creationDateTime | taxRequirementConsentResponse/data/creationDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время создания согласия | – | ||
status | taxRequirementConsentResponse/data/status | [1..1] | Max35Text | Текущий статус согласия (согласно описанию в таблице 30) | – | ||
statusUpdateDateTime | taxRequirementConsentResponse/data/statusUpdateDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время обновления статуса согласия | – | ||
cutOffDateTime | taxRequirementConsentResponse/data/cutOffDateTime | [0..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время актуальности согласия (после этого согласие является недействительным) | – | ||
expectedExecutionDate | taxRequirementConsentResponse/data/expectedExecutionDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата исполнения платежа, списания средств со счета плательщика | – | ||
expectedSettlementDate | taxRequirementConsentResponse/data/expectedSettlementDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата расчета платежа, зачисления средств на счет получателя | – | ||
initiation | taxRequirementConsentResponse/data/initiation | [1..1] |
| Исходные параметры блока initiation | Согласно описанию объекта initiation в таблице 28 | ||
|
| authorisation | taxRequirementConsentResponse/data/authorisation | [0..1] |
| Тип авторизации от поставщика API | Согласно описанию объекта authorisation в таблице 22 |
84.2. Методы и модели создания и получения статуса платежного указания на инициирование платежа бенефициаром (взыскателем) в бюджет.
Модель данных запроса на создание платежного указания на инициирование платежа в бюджет POST/payments/taxRequirement представлена на рисунке 46.
Рисунок 46
Атрибутный состав запроса на создание платежного указания на инициирование платежа в бюджет POST/payments/taxRequirement представлен в таблице 50.
Таблица 50
Наименование | Путь | Кратность | Тип данных/Формат | Описание | Комментарии | ||
taxRequirementRequest |
|
|
|
|
| ||
| data | taxRequirementRequest/data | [1..1] |
|
|
| |
| taxRequirementConsentId | taxRequirementRequest/data/taxRequirementConsentId | [1..1] | Max35Text | Идентификатор согласия, присвоенный на стороне поставщика API | – | |
initiation | taxRequirementRequest/data/initiation | [1..1] |
| Исходные параметры блока initiation | Согласно описанию объекта initiation в таблице 28 | ||
Модель данных ответа на запросы создания платежного указания POST/payments/taxRequirement и получения статуса платежного указания GET/payments/taxRequirement/{taxRequirementId} на инициирование платежа бенефициаром (взыскателем) в бюджет представлена на рисунке 47.
Рисунок 47
Атрибутный состав ответа на запросы создания платежного указания POST/payments/taxRequirement и получения статуса платежного указания GET/payments/taxRequirement/{taxRequirementId} на инициирование платежа бенефициаром (взыскателем) в бюджет представлен в таблице 51.
Таблица 51
Наименование | Путь | Кратность | Тип данных/Формат | Описание | Комментарии | ||
taxRequirementResponse |
|
|
|
|
| ||
| data | taxRequirementResponse/data | [1..1] |
|
|
| |
| taxRequirementId | taxRequirementResponse/data/taxrRequirementId | [1..1] | Max35Text | Идентификатор платежного указания | – | |
taxRequirementConsentId | taxRequirementResponse/data/taxRequirementConsentId | [1..1] | Max35Text | Идентификатор согласия, присвоенный на стороне поставщика API | – | ||
creationDateTime | taxRequirementResponse/data/creationDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss ±hh | Дата и время создания платежного указания | – | ||
expectedExecutionDate | taxRequirementResponse/data/expectedExecutionDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата исполнения платежа, списания средств со счета плательщика | – | ||
expectedSettlementDate | taxRequirementResponse/data/expectedSettlementDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата расчета платежа, зачисления средств на счет получателя | – | ||
initiation | taxRequirementResponse/data/initiation | [1..1] |
| Исходные параметры блока initiation | Согласно описанию объекта initiation в таблице 28 | ||
multiAuthorisation | taxRequirementResponse/data/multiAuthorisation | [0..1] |
| Параметры ответа потока множественной авторизации от поставщика API | Согласно описанию объекта multiAuthorisation в таблице 23 | ||
paymentStatus | taxRequirementResponse/data/paymentStatus | [1..1] |
| Параметры статуса платежного указания на инициирование платежа бенефициаром (взыскателем) в бюджет | Согласно описанию объекта paymentStatus в таблице 24 | ||
84.3. Метод для отзыва платежного указания на инициирование платежа бенефициаром (взыскателем) в бюджет.
Клиент имеет возможность отозвать платежное указание на инициирование платежа бенефициаром (взыскателем) в бюджет, отправив запрос DELETE/payments/taxRequirements/{taxRequirementId}.
При невозможности отзыва платежного указания на инициирование платежа бенефициаром (взыскателем) в бюджет поставщик API возвращает ошибку с кодом 400 Bad Request с указанием errorCode=BY.NBRB.Resource.NotCancel.
85. Методы и модели платежа по инициативе бенефициара за товары, работы, услуги (далее для целей настоящего пункта – инициирование платежа бенефициаром).
Рассматриваются следующие методы и модели:
создание и получение статуса согласия на инициирование платежа бенефициаром;
создание и получение статуса платежного указания на инициирование платежа бенефициаром.
85.1. Методы и модели запроса и ответа на создание и получение статуса согласия на инициирование платежа бенефициаром.
Модель запроса на создание согласия POST/paymentConsents/requirement на инициирование платежа бенефициаром представлена на рисунке 48.
Рисунок 48
Атрибутный состав запроса на создание согласия POST/paymentConsents/requirement на инициирование платежа бенефициаром представлен в таблице 52.
Таблица 52
Наименование | Путь | Кратность | Описание | Комментарии | ||
requirementConsentRequest |
|
|
|
| ||
| data | requirementConsentRequest/data | [1..1] |
|
| |
| initiation | requirementConsentRequest/data/initiation | [1..1] | Инициирующая сторона отправляет параметры данных поставщику API. Данный объект используется для запроса перевода средств со счета плательщика на счет получателя средств | Согласно описанию объекта initiation в таблице 28 | |
authorisation | requirementConsentRequest/data/authorisation | [0..1] | Запрос типа авторизации от пользователя API | Согласно описанию объекта authorisation в таблице 22 | ||
risk | requirementConsentRequest/risk | [1..1] | Данный объект отправляется инициатором поставщику API и используется для указания дополнительных деталей для оценки рисков платежа | Согласно описанию объекта risk в таблице 29 | ||
Модель ответа на запросы на создание согласия POST/paymentConsents/requirement и получение статуса согласия GET/paymentConsents/requirement/{requirementConsentId} на инициирование платежа бенефициаром представлена на рисунке 49.
Рисунок 49
Атрибутный состав ответа на запросы на создание согласия POST/paymentConsents/requirement и получение статуса согласия GET/paymentConsents/requirement/{requirementConsentId} на инициирование платежа бенефициаром представлен в таблице 53.
Таблица 53
Наименование | Путь | Кратность | Тип данных/Формат | Описание | Комментарии | ||
requirementConsentResponse |
|
|
|
|
| ||
| data | requirementConsentResponse/data | [1..1] |
|
|
| |
| requirementConsentId | requirementConsentResponse/data/requirementConsentId | [1..1] | Max35Text | Идентификатор согласия | – | |
link | requirementConsentResponse/data/link | [1..1] | Max140Text | Ссылка на согласие | – | ||
creationDateTime | requirementConsentResponse/data/creationDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время создания согласия | – | ||
status | requirementConsentResponse/data/status | [1..1] | Max35Text | Текущий статус согласия (согласно описанию в таблице 30) | – | ||
statusUpdateDateTime | requirementConsentResponse/data/statusUpdateDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время обновления статуса согласия | – | ||
cutOffDateTime | requirementConsentResponse/data/cutOffDateTime | [0..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время актуальности согласия (после этой даты и времени, согласие является недействительным) | – | ||
expectedExecutionDate | requirementConsentResponse/data/expectedExecutionDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата исполнения платежа, списания средств со счета плательщика | – | ||
expectedSettlementDate | requirementConsentResponse/data/expectedSettlementDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата расчета платежа, зачисления средств на счет получателя | – | ||
initiation | requirementConsentResponse/data/initiation | [1..1] |
| Исходные параметры блока initiation | Согласно описанию объекта initiation в таблице 28 | ||
charge | paymentRequirementConsentResponse/data/charge | [0..n] |
| Комиссионное вознаграждение поставщика API | Согласно описанию объекта charge в таблице 21 | ||
authorisation | requirementConsentResponse/data/authorisation | [0..1] |
| Тип авторизации от поставщика API | Согласно описанию объекта authorisation в таблице 22 | ||
risk | requirementConsentResponse/risk | [1..1] |
| Исходные параметры блока risk | Согласно описанию объекта risk в таблице 29 | ||
85.2. Методы и модели создания и получения статуса платежного указания на инициирование платежа бенефициаром.
Модель данных запроса на создание платежного указания POST/payments/requirements на инициирование платежа бенефициаром представлена на рисунке 50.
Рисунок 50
Атрибутный состав запроса на создание платежного указания POST/payments/requirements на инициирование платежа бенефициаром представлен в таблице 54.
Таблица 54
Наименование | Путь | Кратность | Тип данных/Формат | Описание | Комментарии | ||
requirementRequest |
|
|
|
|
| ||
| data | requirementRequest/data | [1..1] |
|
|
| |
| requirementConsentId | requirementRequest/data/requirementConsentId | [1..1] | Max35Text | Идентификатор согласия, присвоенный на стороне поставщика API | – | |
initiation | requirementRequest/data/initiation | [1..1] |
| Исходные параметры блока initiation | Согласно описанию объекта initiation в таблице 28 | ||
risk | requirementRequest/risk | [1..1] |
| Исходные параметры блока risk | Согласно описанию объекта risk в таблице 29 | ||
Модель данных ответа на запросы создания платежного указания POST/payments/requirements и получения статуса платежного указания GET/payments/requirements/{requirementId} на инициирование платежа бенефициаром представлена на рисунке 51.
Рисунок 51
Атрибутный состав ответа на запросы создания платежного указания POST/payments/requirements и получения статуса платежного указания GET/payments/requirements/{requirementId} на инициирование платежа бенефициаром представлен в таблице 55.
Таблица 55
Наименование | Путь | Кратность | Тип данных/Формат | Описание | Комментарии | ||
requirementResponse |
|
|
|
|
| ||
| data | requirementResponse/data | [1..1] |
|
|
| |
| requirementId | requirementResponse/data/requirementId | [1..1] | Max35Text | Идентификатор платежного указания | – | |
requirementConsentId | requirementResponse/data/requirementConsentId | [1..1] | Max35Text | Идентификатор согласия, присвоенный на стороне поставщика API | – | ||
creationDateTime | requirementResponse/data/creationDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss ±hh | Дата и время создания платежного указания | – | ||
expectedExecutionDate | requirementResponse/data/expectedExecutionDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата исполнения платежа, списания средств со счета плательщика | – | ||
expectedSettlementDate | requirementResponse/data/expectedSettlementDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата расчета платежа, зачисления средств на счет получателя | – | ||
initiation | requirementResponse/data/initiation | [1..1] |
| Исходные параметры блока initiation | Согласно описанию объекта initiation в таблице 28 | ||
charge | requirementResponse/data/charge | [0..n] |
| Комиссионное вознаграждение поставщика API | Согласно описанию объекта charge в таблице 21 | ||
multiAuthorisation | requirementResponse/data/multiAuthorisation | [0..1] |
| Параметры ответа потока множественной авторизации от поставщика API | Согласно описанию объекта multiAuthorisation в таблице 23 | ||
paymentStatus | requirementResponse/data/paymentStatus | [1..1] |
| Параметры статуса платежного указания на инициирование платежа бенефициаром | Согласно описанию объекта paymentStatus в таблице 24 | ||
85.3. Метод для отзыва платежного указания на инициирование платежа бенефициаром.
Клиент имеет возможность отозвать платежное указание на инициирование платежа бенефициаром, отправив запрос DELETE/payments/requirement/{requirementId}.
При невозможности отзыва платежного указания на инициирование платежа бенефициаром поставщик API возвращает ошибку с кодом 400 Bad Request с указанием errorCode=BY.NBRB.Resource.NotCancel.
86. Методы и модели рекуррентного платежа.
Рассматриваются следующие методы и модели:
создание и получение статуса долгосрочного согласия на рекуррентный платеж;
создание и получение статуса платежного указания на инициирование платежа.
При инициировании рекуррентного платежа создается долгосрочное согласие, в рамках которого может инициироваться несколько платежей.
86.1. Общее описание рекуррентного платежа.
Запрос на создание долгосрочного согласия VRPConsentRequest состоит из следующих объектов:
initiation;
controlParameters;
risk.
Объект initiation содержит общие параметры для всех платежей, которые инициируются в рамках долгосрочного согласия.
Объект controlParameters содержит параметры управления лимитами платежей.
Объект risk используется для указания дополнительных деталей для оценки рисков.
Ответ на запрос на создание и получение долгосрочного согласия VRPConsentResponse состоит из следующих объектов:
initiation;
controlParameters;
risk.
Запросы на создание и получение статуса платежного указания на инициирование платежа VRPRequest состоит из следующих объектов:
initiation;
instruction;
risk.
Объект instruction содержит конкретные параметры платежной инструкции для каждого конкретного платежного указания на инициирование платежа в рамках долгосрочного согласия.
Ответ на запрос на создание и получение статуса платежного указания на инициирование платежа VRPResponse состоит из следующих объектов:
initiation;
instruction;
charge;
risk.
Объект charge используется для указания деталей по комиссионным вознаграждениям за обработку конкретного платежа.
Значения параметров в объекте instruction не должны отличаться от заданных значений параметров в объекте initiation. Если есть хотя бы одно несовпадение, поставщик API возвращает ошибку с кодом 400 (Bad Request).
Пользователь API должен обеспечить полное соответствие объектов initiation и risk в запросе на создание долгосрочного согласия на инициирование рекуррентного платежа и в запросе на создание платежного указания на инициирование платежа. Если есть хотя бы одно несовпадение, поставщик API возвращает ошибку с кодом 400 (Bad Request).
86.2. Долгосрочное согласие на инициирование рекуррентного платежа.
Клиент может отозвать долгосрочное согласие в любой момент.
Долгосрочное согласие содержит параметры, которые указывают срок действия долгосрочного согласия и устанавливают лимиты на:
сумму каждого платежа;
общую сумму платежей за заданный промежуток времени.
Статусы параметра VRPConsent при авторизации долгосрочного согласия, после авторизации долгосрочного согласия, после отзыва долгосрочного согласия представлены в таблице 56.
Таблица 56
Наименование статуса | Описание статуса |
Authorised | Согласие на инициирование рекуррентного платежа успешно авторизовано клиентом |
AwaitingAuthorisation | Согласие на инициирование рекуррентного платежа ожидает авторизации клиента |
Expired | Согласие на инициирование рекуррентного платежа недействительно, истек срок действия |
Rejected | Согласие на инициирование рекуррентного платежа было отклонено клиентом |
Revoked | Согласие на инициирование рекуррентного платежа было отозвано клиентом |
Смена состояний статусов при определенных действиях долгосрочного согласия на инициирование рекуррентного платежа представлена на рисунке 52.
Рисунок 52
86.3. Модели данных общих объектов в рекуррентном платеже.
При всех запросах и ответах по инициированию рекуррентного платежа обязательный объект initiation включает следующие компоненты:
debtor;
debtorAccount;
debtorAgent;
creditor;
creditorAccount;
creditorAgent;
remittanceInformation.
Модель данных объекта initiation для рекуррентного платежа представлена на рисунке 53.
Рисунок 53
Атрибутный состав объекта initiation для рекуррентного платежа приведен в таблице 57.
Таблица 57
Наименование | Путь | Кратность | Тип данных/Формат | Описание | ||
initiation | initiation |
|
| Параметры, которые отправляются инициирующей стороной поставщику API. Используется для запроса о переводе средств со счета плательщика на счет получателя средств в рамках рекуррентного платежа | ||
| localInstrument | initiation/localInstrument | [0..1] | Max35Text | Элемент используется для указания варианта клиринга и (или) для дополнительного описания сервиса или уровня обслуживания. Возможные значения: | |
amount | initiation/amount | [0..1] | decimal td=18 fd =5 | Сумма платежа (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||
currency | initiation/currency | [0..1] | тип данных ActiveCurrencyCode, формат [A-Z]{3} | Валюта суммы платежа (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||
debtor | initiation/debtor | [0..1] |
| Информация о плательщике (в соответствии с описанием, приведенным в таблице 6) | ||
debtorAccount | initiation/debtorAccount | [0..1] |
| Идентификация счета плательщика | ||
| schemeName | initiation/debtorAccount/schemeName | [1..1] | Max140Text | Наименование схемы идентификации. | |
identification | initiation/debtorAccount/identification | [1..1] | IBAN2007Identifier (для schemeName= BY.NBRB.IBAN), | Уникальная и однозначная идентификация счета, согласованная между владельцем счета и банком, обслуживающим счет (IBAN или идентификация в иной форме) | ||
debtorAgent | initiation/debtorAgent | [0..1] |
| Информация о банке, обслуживающим счет плательщика | ||
| identificationClearingSystem | initiation/debtorAgent/identificationClearingSystem | [0..1] | Согласно справочнику E005 (таблица 80): [A-Z]{5}, | Идентификация клиринговой системы: в кодированной форме (согласно справочнику E005, таблица 80) или собственная идентификация | |
identification | initiation/debtorAgent/identification | [1..1] | BICFIIdentifier (для кода BIC): | Зарегистрированный код BIC (BICFI) или идентификация участника клиринговой системы. | ||
name | initiation/debtorAgent/name | [1..1] | Max140Text | Наименование банка, обслуживающего счет плательщика | ||
creditor | initiation/creditor | [1..1] |
| Информация о бенефициаре (в соответствии с описанием, приведенным в таблице 6) | ||
creditorAccount | initiation/creditorAccount | [1..1] |
| Идентификация счета бенефициара | ||
| schemeName | initiation/creditorAccount/schemeName | [1..1] | Max140Text | Наименование схемы идентификации. | |
identification | initiation/creditorAccount/identification | [1..1] | IBAN2007Identifier (для schemeName= BY.NBRB.IBAN), | Уникальная и однозначная идентификация счета, согласованная между владельцем счета и банком, обслуживающим счет (IBAN или идентификация в иной форме) | ||
creditorAgent | initiation/creditorAgent | [0..1] |
| Информация о банке, обслуживающим счет бенефициара | ||
| identificationClearingSystem | initiation/creditorAgent/identificationClearingSystem | [0..1] | Согласно справочнику E005 (таблица 80): [A-Z]{5}, | Идентификация клиринговой системы: в кодированной форме (согласно справочнику E005, таблица 80) или собственная идентификация | |
identification | initiation/creditorAgent/identification | [1..1] | BICFIIdentifier (для кода BIC): | Зарегистрированный код BIC (BICFI) или идентификация участника клиринговой системы. | ||
name | initiation/creditorAgent/name | [1..1] | Max140Text | Наименование банка, обслуживающего счет бенефициара | ||
remittanceInformation | initiation/remittanceInformation | [0..1] |
| Информация о переводе денежных средств. Предоставляется для сопоставления записи с позициями, расчеты по которым должны быть осуществлены с помощью перевода, например, коммерческие счета-фактуры в системе учета дебиторской задолженности (в соответствии с описанием, приведенным в таблице 26) | ||
Объект controlParameters используется для указания долгосрочных параметров управления при инициировании рекуррентного платежа.
В запросе и ответе по созданию и получению статуса согласия на инициирование рекуррентного платежа обязательный объект controlParameters включает:
maximumIndividualAmount;
periodicLimits;
supplementaryData.
Модель данных объекта controlParameters для рекуррентного платежа представлена на рисунке 54.
Рисунок 54
Атрибутный состав объекта controlParameters для рекуррентного платежа представлен в таблице 58.
Таблица 58
Наименование | Путь | Кратность | Тип данных/Формат | Описание | ||
controlParameters | controlParameters |
|
|
| ||
| fromPaymentDate | controlParameters/fromPaymentDate | [0..1] | ISODate, формат YYYY-MM-DD | Дата начала действия долгосрочного согласия включительно | |
toPaymentDate | controlParameters/tolPaymentDate | [0..1] | ISODate, формат YYYY-MM-D | Дата окончания действия долгосрочного согласия включительно | ||
maximumIndividualAmount | controlParameters/maximumIndividualAmount | [0..1] | decimal td=18 fd =5 | Максимальная единовременная сумма, которая может быть указана в платежной инструкции (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||
currency | controlParameters/currency | [1..1] | тип данных ActiveCurrencyCode, формат [A-Z]{3} | Валюта максимальной суммы платежа (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||
periodicLimits | controlParameters/periodicLimits | [0..n] |
| Данные по лимиту суммы за определенный период | ||
| amount | controlParameters/periodicLimits/amount | [1..1] | decimal td=18 fd =5 | Лимит суммы рекуррентного платежа за определенный период (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | |
currency | controlParameters/periodicLimits/currency | [1..1] | тип данных ActiveCurrencyCode, формат [A-Z]{3} | Валюта суммы платежа (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||
periodType | controlParameters/periodicLimits/periodType | [1..1] | Max10Text | Тип периода (согласно описанию справочника TypePaymentPeriodStaticType. Тип периода в таблице 77) | ||
| supplementaryData | controlParameters/supplementaryData | [0..1] | – | Дополнительная информация, которая не может быть отражена в структурированных элементах и/или других специальных блоках | |
В запросе и ответе на создание и получение статуса платежного указания на инициирование платежа обязательный объект instruction включает:
creditor;
creditorAccount;
creditorAgent;
remittanceInformation;
supplementaryData.
Модель данных объекта instruction для рекуррентного платежа представлена на рисунке 55.
Рисунок 55
Атрибутный состав объекта instruction для рекуррентного платежа представлен в таблице 59.
Таблица 59
Наименование | Путь | Кратность | Тип данных/Формат | Описание | ||
instruction | instruction |
|
| Параметры платежного указания для инициирования платежа в рамках долгосрочного согласия | ||
| instructionIdentification | instruction/instructionIdentification | [1..1] | Max35Text | Уникальный идентификатор платежной инструкции, присвоенный инструктирующей стороной для однозначной идентификации инструкции инструктируемой стороной. | |
endToEndIdentification | instruction/endToEndIdentification | [1..1] | [0-9]{2}.[0-9]{8}.[Max16Text]{1,16}(.[0-9]{1,6})? | Сквозной идентификатор, присвоенный инициирующей стороной для однозначной идентификации транзакции. Эта идентификация передается без изменения по всей сквозной цепочке. | ||
localInstrument | instruction/localInstrument | [0..1] | Max35Text | Элемент используется для указания варианта клиринга и (или) для дополнительного описания сервиса или уровня обслуживания. Возможные значения: | ||
amount | instruction/amount | [1..1] | decimal td=18 fd =5 | Сумма денежных средств, которая должна быть переведена от плательщика бенефициару до вычета комиссий, выраженная в валюте, определенной инициирующей стороной (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||
currency | instruction/currency | [1..1] | тип данных ActiveCurrencyCode, формат [A-Z]{3} | Валюта суммы платежа (в соответствии с описанием, приведенным в подпункте 16.4 пункта 16 настоящего стандарта) | ||
creditor | instruction/creditor | [1..1] |
| Информация о бенефициаре (согласно описанию в таблице 6) | ||
creditorAccount | instruction/creditor/creditorAccount | [1..1] |
| Идентификация счета бенефициара | ||
| schemeName | instruction/creditorAccount/schemeName | [1..1] | Max140Text | Наименование схемы идентификации. | |
identification | instruction/creditorAccount/identification | [1..1] | IBAN2007Identifier (для schemeName= BY.NBRB.IBAN), | Уникальная и однозначная идентификация счета, согласованная между владельцем счета и банком, обслуживающим счет (IBAN или идентификация в иной форме) | ||
creditorAgent | instruction/creditor/creditorAgent | [0..1] |
| Информация о банке, обслуживающим счет бенефициара | ||
| identificationClearingSystem | instruction/creditorAgent/identificationClearingSystem | [0..1] | Согласно справочнику E005 (таблица 80): [A-Z]{5}, | Идентификация клиринговой системы: в кодированной форме (согласно справочнику E005, таблица 80) или собственная идентификация | |
identification | instruction/creditorAgent/identification | [1..1] | BICFIIdentifier (для кода BIC): | Зарегистрированный код BIC (BICFI) или идентификация участника клиринга. | ||
name | instruction/creditorAgent/name | [1..1] | Max140Text | Наименование банка, обслуживающего счет бенефициара | ||
remittanceInformation | instruction/remittanceInformation | [0..1] |
| Информация о переводе денежных средств. Предоставляется для сопоставления записи с позициями, расчеты по которым должны быть осуществлены с помощью перевода, например, коммерческие счета-фактуры в системе учета дебиторской задолженности (согласно описанию в таблице 26) | ||
supplementaryData | instruction/supplementaryData | [0..1] | – | Дополнительная информация, которая не может быть отражена в структурированных элементах и/или других специальных блоках | ||
86.4. Методы и модели данных, атрибутный состав запроса и ответа создания долгосрочного согласия на инициирование рекуррентного платежа.
Модель данных запроса на создание долгосрочного согласия POST/paymentConsents/VRP на инициирование рекуррентного платежа представлена на рисунке 56.
Рисунок 56
Атрибутный состав запроса на создание долгосрочного согласия POST/paymentConsents/VRP на инициирование рекуррентного платежа представлен в таблице 60.
Таблица 60
Наименование | Путь | Кратность | Описание | Комментарии | ||
VRPConsentRequest |
|
|
|
| ||
| data | VRPConsentRequest/data | [1..1] |
|
| |
| ControlParameters | VRPConsentRequest/data/ControlParameters | [1..1] | Параметры управления, при которых должна происходить инициация рекуррентного платежа | Согласно описанию объекта controlParameters в таблице 58 | |
initiation | VRPConsentRequest/data/initiation | [1..1] | Инициирующая сторона отправляет параметры данных поставщику API. Данный объект используется для запроса перевода средств со счета плательщика на счет получателя средств для рекуррентного платежа | Согласно описанию объекта initiation в таблице 57 | ||
risk | VRPConsentRequest/risk | [1..1] | Данный объект отправляется инициатором поставщику API и используется для указания дополнительных деталей для оценки рисков при проведении рекуррентных платежей | Согласно описанию объекта risk в таблице 29 | ||
Модель ответа на запросы на создание долгосрочного согласия POST/paymentConsents/VRP и получение статуса долгосрочного согласия GET/paymentConsents/VRP/{VRPConsentId} на инициирование рекуррентного платежа представлена на рисунке 57.
Рисунок 57
Атрибутный состав ответа на запросы на создание долгосрочного согласия POST/paymentConsents/VRP и получение статуса долгосрочного согласия GET/paymentConsents/VRP/{VRPConsentId} на инициирование рекуррентного платежа представлен в таблице 61.
Таблица 61
Наименование | Путь | Кратность | Тип данных/Формат | Описание | Комментарии | ||
VRPConsentResponse |
|
|
|
|
| ||
| data | VRPConsentResponse/data | [1..1] |
|
|
| |
| VRPConsentId | VRPConsentResponse/data/VRPConsentId | [1..1] | Max35Text | Идентификатор долгосрочного согласия | – | |
link | VRPConsentResponse/data/link | [1..1] | Max140Text | Ссылка на долгосрочное согласие | – | ||
creationDateTime | VRPConsentResponse/data/creationDateTime | [1..1] | ISODateTime, формат | Дата и время создания долгосрочного согласия | – | ||
status | VRPConsentResponse/data/status | [1..1] | Max35Text | Текущий статус долгосрочного согласия (согласно описанию в таблице 56) | – | ||
statusUpdateDateTime | VRPConsentResponse/data/statusUpdateDateTime | [1..1] | ISODateTime, формат | Дата и время обновления статуса долгосрочного согласия | – | ||
controlParameters | VRPConsentResponse/data/controlParameters | [1..1] |
| Исходные параметры управления, при которых должна происходить инициация рекуррентного платежа | Согласно описанию объекта controlParameters в таблице 58 | ||
initiation | VRPConsentResponse/data/initiation | [1..1] |
| Исходные параметры блока initiation | Согласно описанию объекта initiation в таблице 57 | ||
risk | VRPConsentResponse/risk | [1..1] |
| Исходные параметры блока risk | Согласно описанию объекта risk в таблице 29 | ||
86.5. Методы и модели данных, атрибутный состав запроса и ответа на создание и получение статуса платежного указания на инициирование платежа.
Модель данных запроса на создание платежного указания на инициирование платежа POST/payments/VRPS представлена на рисунке 58.
Рисунок 58
Атрибутный состав запроса на создание платежного указания на инициирование платежа POST/payments/VRPS представлен в таблице 62.
Таблица 62
Наименование | Путь | Крат- | Тип данных/ | Описание | Комментарии | ||
VRPRequest |
|
|
|
|
| ||
| data | VRPRequest/data | [1..1] |
|
|
| |
| VRPConsentId | VRPRequest/data/VRPConsentId | [1..1] | Max35Text | Идентификатор долгосрочного согласия, присвоенный на стороне поставщика API | – | |
initiation | VRPRequest/data/initiation | [1..1] |
| Исходные параметры блока initiation | Согласно описанию объекта initiation в таблице 57 | ||
instruction | instruction | [1..1] |
| Конкретные параметры платежной инструкции для конкретного рекуррентного платежа в рамках долгосрочного согласия | Согласно описанию объекта instruction в таблице 59 | ||
risk | VRPRequest/risk | [1..1] |
| Исходные параметры блока risk | Согласно описанию объекта risk в таблице 30 | ||
Модель данных ответа на запросы на создание платежного указания POST/payments/VRPS и получение статуса платежного указания GET/payments/VRPS/VRPId} на инициирование платежа представлена на рисунке 59.
Рисунок 59
Атрибутный состав ответа на запросы на создание платежного указания POST/payments/VRPS и получение статуса платежного указания GET/payments/VRPS/VRPId} на инициирование платежа представлен в таблице 63.
Таблица 63
Наименование | Путь | Кратность | Тип данных/Формат | Описание | Комментарии | ||
VRPResponse |
|
|
|
|
| ||
| data | VRPResponse/data | [1..1] |
|
|
| |
| VRPId | VRPResponse/data/VRPId | [1..1] | Max35Text | Идентификатор платежного указания | – | |
VRPConsentId | VRPResponse/data/VRPConsentId | [1..1] | Max35Text | Идентификатор долгосрочного согласия, присвоенный на стороне поставщика API | – | ||
creationDateTime | VRPResponse/data/creationDateTime | [1..1] | ISODateTime, формат | Дата и время создания платежного указания | – | ||
expectedExecutionDate | VRPResponse/data/expectedExecutionDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата исполнения платежа, списания средств со счета плательщика | – | ||
expectedSettlementDate | VRPResponse/data/expectedSettlementDate | [0..1] | ISODate, формат YYYY-MM-DD | Ожидаемая дата расчета, зачисления средств на счет получателя | – | ||
initiation | VRPResponse/data/Initiation | [1..1] |
| Исходные параметры блока initiation | Согласно описанию объекта initiation в таблице 57 | ||
instruction | VRPResponse/data/instruction | [1..1] |
| Исходные конкретные параметры платежной инструкции для конкретного рекуррентного платежа в рамках долгосрочного платежного указания | Согласно описанию объекта instruction в таблице 59 | ||
charge | VRPResponse/data/charge | [0..n] |
| Комиссионное вознаграждение поставщика API | Согласно описанию объекта charge в таблице 21 | ||
risk | VRPResponse/risk | [1..1] |
| Исходные параметры блока risk | Согласно описанию объекта risk в таблице 29 | ||
86.6. Метод для отзыва платежного указания на инициирование платежа из состава рекуррентных платежей.
Клиент имеет возможность отозвать платежное указание на инициирование платежа из состава рекуррентных платежей, отправив запрос DELETE/payments/VRP/{VRPId}.
При невозможности отзыва платежного указания на инициирование платежа из состава рекуррентных платежей поставщик API возвращает ошибку с кодом 400 Bad Request с указанием errorCode=BY.NBRB.Resource.NotCancel.
Глава 15
Требования к особенностям работы с Пользователями API первого типа
87. Поставщик API может предоставить возможность создания долгосрочного согласия на получение доступа к API инициирования рекуррентных платежей для пользователей API первого типа посредством СДБО.
Поставщик API может предоставить возможность просмотра списка долгосрочных согласий на доступ к API для пользователя API первого типа и отзыва долгосрочного согласия.
Пользователь API первого типа при выполнении запросов на инициирование платежа может дополнительно использовать следующий заголовок HTTP, который описан в таблице 1:
x-api-key – идентификатор Apikey, сгенерированный в СДБО поставщика API и предназначенный для идентификации и авторизации запросов пользователя API первого типа.
88. Схема процесса при инициировании платежа пользователем API первого типа представлена на рисунке 60.
Рисунок 60
89. Описание этапов и шагов процесса при инициировании платежа для пользователя API первого типа.
89.1. Этап 1. Создание долгосрочного согласия на доступ к API для инициирования платежей и генерация Apikey:
1) клиент авторизуется в СДБО у поставщика API, который обслуживает его счет (счета);
2) клиент создает долгосрочное согласие на получение доступа к API инициирования платежей и авторизует долгосрочное согласие;
3) поставщик API генерирует Apikey для долгосрочного согласия;
4) клиент сохраняет Apikey.
89.2. Этап 2. Создание согласия на инициирование платежа:
1) пользователь API первого типа создает долгосрочное согласие на инициирование платежа с помощью Apikey (запрос POST). Долгосрочное согласие создается со статусом AwaitingAutorization;
2) поставщик API генерирует и возвращает идентификатор согласия.
89.3. Этап 3. Авторизация согласия:
1) клиент через СДБО авторизует долгосрочное согласие на инициирование платежа;
2) поставщик API обновляет статус долгосрочного согласия на инициирование платежа.
89.4. Этап 4. Создание платежного указания на инициирование платежа:
1) пользователь API первого типа создает платежное указание на инициирование платежа и указывает идентификатор авторизованного долгосрочного согласия на инициирование платежа;
2) поставщик API возвращает идентификатор платежного указания на инициирование платежа и отправляет платежное указание в обработку. Для множественной авторизации платежное указание отправляется в обработку после авторизации долгосрочного согласия на инициирование платежа необходимым количеством представителей клиента.
89.5. Этап 5. Получение статуса долгосрочного согласия и статуса платежного указания.
Пользователь API первого типа проверяет статус долгосрочного согласия или статус платежного указания на инициирование платежа.
Глава 16
Требования к методам и моделям получения информации по всем Согласиям и платежным указаниям Клиента
90. Для получения информации по всем согласиям и всем платежным указаниям на инициирование платежей клиента используются методы API, указанные в таблице 64.
Таблица 64
API | Параметр | Конечные точки (endpoints) | Описание |
Список согласий | paymentConsents | GET/paymentConsents?fromCreationDate=&toCreationDate=&type=&status= | Получение информации по всем согласиям клиента. Параметры fromCreationDate и toCreationDate обязательные в данном запросе. Параметры type и status необязательные в данном запросе |
Список платежных указаний | payments | GET/payments?fromCreationDate=&toCreationDate=&type=&status= | Получение информации по всем платежным указаниям клиента. Параметры fromCreationDate и toCreationDate обязательные в данном запросе. Параметры type и status необязательные в данном запросе |
91. Метод и модель данных, атрибутный состав запроса и ответа получения информации по всем согласиям клиента.
Ответ на запрос получения информации по всем согласиям клиента paymentConsentsResponse включает в себя объект paymentConsent.
Модель данных ответа на запрос GET/paymentConsents?fromCreationDate=&toCreationDate=&type=&status= показана на рисунке 61.
Рисунок 61
Атрибутный состав ответа на запрос GET/paymentConsents?fromCreationDate=&toCreationDate=&type=&status= представлен в таблице 65.
Таблица 65
Наименование | Путь | Кратность | Тип данных/Формат | Описание | |||
paymentConsentsResponse |
|
|
|
| |||
| data | paymentConsentsResponse/data | [1..1] |
|
| ||
| paymentConsent | paymentConsentsResponse/data/paymentConsent | [0..n] |
|
| ||
| paymentConsentId | paymentConsentsResponse/data/paymentConsent/paymentConsentId | [1..1] | Max35Text | Идентификатор согласия, присвоенный на стороне поставщика API | ||
creationDateTime | paymentConsentsResponse/data/paymentConsent/creationDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время создания согласия | |||
status | paymentConsentsResponse/data/paymentConsent/status | [1..1] | Max35Text | Текущий статус согласия (согласно описанию в таблицах 30 и 56) | |||
type | paymentConsentsResponse/data/paymentConsent/type | [1..1] | Max35Text | Тип согласия (согласно описанию справочника PaymentConsentStaticType. Тип согласия в таблице 78) | |||
92. Метод и модель данных, атрибутный состав запроса и ответа на получение информации по всем платежным указаниям клиента.
Ответ на запрос получения информации по всем платежным указаниям клиента paymentsResponse включает в себя объект payment.
Объект payment включает блок paymentStatus.
Модель данных ответа на запрос GET/payments?fromCreationDate=&toCreationDate=&type=&status= представлена на рисунке 62.
Рисунок 62
Атрибутный состав ответа на запрос GET/payments?fromCreationDate=&toCreationDate=&type=&status= представлен в таблице 66.
Таблица 66
Наименование | Путь | Кратность | Тип данных/Формат | Описание | Комментарии | |||
paymentsResponse |
|
|
|
|
| |||
| data | paymentsResponse/data | [1..1] |
|
|
| ||
| payment | paymentsResponse/data/payment | [0..n] |
|
|
| ||
| paymentId | paymentsResponse/data/payment/paymentId | [1..1] | Max35Text | Идентификатор платежного указания, присвоенный на стороне поставщика API |
| ||
creationDateTime | paymentsResponse/data/payment/creationDateTime | [1..1] | ISODateTime, формат YYYY-MM-DDThh:mm:ss±hh:mm | Дата и время создания платежного указания |
| |||
type | paymentsResponse/data/payment/type | [1..1] | Max35Text | Тип платежного указания (согласно описанию справочника PaymentStaticType. Тип платежного указания в таблице 79) |
| |||
paymentStatus | paymentsResponse/data/payment/paymentStatus | [1..1] |
| Детализированная информация о статусе платежного указания | Согласно описанию объекта paymentStatus в таблице 24 | |||
Раздел V
Справочники
Глава 17
Общее описание справочников
93. Справочники предназначены для отражения типизированных элементов данных для компонентов.
94. Описание справочников, разработанных для стандарта, приведено в таблицах 67–79.
В таблице 67 приведен Справочник AccountTypeStaticType. Тип счета.
Таблица 67
Значение | Описание |
Business | Тип счета для юридических лиц |
Individual | Тип счета для физических лиц |
В таблице 68 приведен Справочник AccountSubTypeStaticType. Вид счета/банковских продуктов/условий.
Таблица 68
Значение | Описание |
CreditCard | Кредитные карты |
CurrentAccount | Текущие (расчетные) счета |
Loan | Потребительские кредиты |
Mortgage | Ипотека |
Installment | Рассрочка |
Savings | Вклады (депозиты) |
В таблице 69 приведен Справочник AccountStatusStaticType. Статус счета.
Таблица 69
Значение | Описание |
Enabled | Счет доступен и может использоваться |
Disabled | Счет не доступен и не может использоваться временно или навсегда |
Deleted | Счет был закрыт и не может использоваться |
Pending | Изменения счета ожидают подтверждения |
В таблице 70 приведен Справочник AccountSubstatusStaticType. Детализированный статус счета.
Таблица 70
Значение | Описание |
Arrested | Арестован |
Blocked | Заблокирован |
Fixed | Неподвижный |
Suspended | Приостановлен |
Stopped | Остановлен |
В таблице 71 приведен Справочник CreditDebitIndicatorStaticType. Индикатор дебетовой/кредитовой операции.
Таблица 71
Значение | Описание |
Credit | Кредитовая операция |
Debit | Дебетовая операция |
В таблице 72 приведен Справочник CreditLineTypeStaticType. Вид кредита.
Таблица 72
Значение | Описание |
Revolving | Возобновляемая кредитная линия |
Non-revolving | Невозобновляемая кредитная линия |
В таблице 73 приведен Справочник CardSchemeNameStaticType. Наименование схемы карты.
Таблица 73
Значение | Описание |
Visa | Visa |
MasterCard | MasterCard |
Belkart | Белкарт, белорусская национальная платежная система |
AmericanExpress | AmericanExpress |
UnionPay | UnionPay |
JCB | JCB |
Mir | Мир, российская национальная платежная система |
Diners | Diners |
Discover | Discover |
ArCa | ArCa, армянская национальная платежная система |
ELCART | ELCART, киргизская национальная платежная система |
В таблице 74 приведен Справочник CardAuthorisationTypeStaticType. Тип авторизации карты.
Таблица 74
Значение | Описание |
ConsumerDevice | Устройство пользователя |
Contactless | Бесконтактный |
None | Отсутствует |
PIN | PIN-код |
В таблице 75 приведен Справочник AuthorisationTypeStaticType. Тип запроса авторизации.
Таблица 75
Значение | Описание |
Any | Любой тип авторизации (авторизация на момент запроса неизвестна) |
Single | Одиночный тип авторизации |
Multiple | Множественный тип авторизации |
В таблице 76 приведен Справочник StatusAuthorisationTypeStaticType. Статус авторизации.
Таблица 76
Значение | Описание |
Authorised | Клиент подтвердил авторизацию |
AwaitingFurtherAuthorisation | Ожидает авторизации клиента |
Rejected | Клиент отклонил авторизацию |
В таблице 77 приведен Справочник TypePaymentPeriodStaticType. Тип периода.
Таблица 77
Значение | Описание |
Day | День |
Week | Неделя |
Month | Месяц |
Quarter | Квартал |
SemiAnnual | Полугодие |
Annual | Год |
В таблице 78 приведен Справочник PaymentConsentStaticType. Тип согласия.
Таблица 78
Обозначение | Описание |
domesticConsent | Согласие на инициирование платежа плательщиком за товары, работы, услуги |
domesticTaxConsent | Согласие на инициирование платежа плательщиком в бюджет |
listAccountsConsent | Согласие на инициирование платежа плательщиком, содержащего список бенефициаров с указанием счетов бенефициаров |
listPassportsConsent | Согласие на инициирование платежа плательщиком, содержащего список бенефициаров при осуществлении перевода без открытия счета |
requirementConsent | Согласие на инициирование платежа бенефициаром за товары, работы, услуги |
taxRequirementConsent | Согласие на инициирование платежа бенефициаром (взыскателем) в бюджет |
VRPConsent | Согласие на инициирование рекуррентного платежа |
В таблице 79 приведен Справочник PaymentStaticType. Тип платежного указания.
Таблица 79
Значение | Описание |
domestic | Платеж по инициативе плательщика за товары, работы, услуги |
domesticTax | Платеж по инициативе плательщика в бюджет |
listAccounts | Платеж по инициативе плательщика, содержащий список бенефициаров с указанием счетов бенефициаров |
listPassports | Платеж по инициативе плательщика, содержащий список бенефициаров при осуществлении перевода без открытия счета |
requirement | Платеж по инициативе бенефициара за товары, работы, услуги |
taxRequirement | Платеж по инициативе бенефициара (взыскателя) в бюджет |
VRP | Рекуррентный платеж |
95. Для некоторых значений элементов данных используются национальные и внешние справочники, представленные в таблице 80.
Таблица 80
Номер справочника | Наименование справочника |
N003 | Справочник кодов и наименований валют |
N010 | Справочник кодов ошибок |
N011 | Справочник кодов платежей в бюджет |
N013 | Кодификатор стран |
N016 | Справочник условных цифровых обозначений видов платежных и иных документов |
N023 | Справочник видов документов, удостоверяющих личность |
N029 | Справочник банковских идентификационных кодов |
N034 | Справочник кодов очередностей платежа |
N058 | Справочник населенных пунктов на основании ОК СОАТО |
N061 | Справочник статусов субъектов |
N063 | Справочник кодов операций |
N080 | Справочник законодательных актов, в соответствии с которыми открываются специальные счета |
N085 | Справочник кодов видов платежей |
N091 | Справочник типов населенных пунктов |
N098 | Справочник типов элементов улично-дорожной сети |
N099 | Кодификатор назначения платежа в Республике Беларусь |
N100 | Справочник видов расходов по переводу (репозиторий ISO 20022) |
N101 | Справочник типов ссылочных документов (репозиторий ISO 20022) |
N102 | Справочник периодов уплаты налогов (репозиторий ISO 20022) |
E004 | Справочник кодов категории назначения перевода (репозиторий ISO20022) |
E005 | Справочник кодов клиринговых систем (репозиторий ISO 20022) |
E009 | Справочников кодов идентификации организации (репозиторий ISO 20022) |
E065 | Справочник кодов статусов перевода (репозиторий ISO 20022) |
E066 | Справочник кодов причин отзыва сообщения (репозиторий ISO 20022) |
E072 | Справочник типов балансов (остатков) по счету (репозиторий ISO 20022) |
| УТВЕРЖДЕНО Постановление Правления |
СТАНДАРТ ПРОВЕДЕНИЯ РАСЧЕТОВ
СПР 6.02-2-2022 «Банковская деятельность. Информационные технологии. Открытые банковские API. Платежные API. Информационная безопасность»
Раздел I
Общие положения
1. Настоящий стандарт проведения расчетов (далее – стандарт) устанавливает требования по информационной безопасности к открытым платежным банковским интерфейсам программирования приложений (интерфейсам прикладного программирования, API) (далее – API) и используется при создании программных средств, предназначенных для безопасного обмена информацией, предоставляемой посредством API, связанной:
с получением информации о банковском счете (далее – счет);
с инициированием платежей в белорусских рублях.
Настоящий стандарт применяется при обеспечении безопасного доступа к финансовым данным в финансовых сервисах реального времени с использованием модели обмена данными REST/JSON, защищенной технологией OAuth, включая профилирующий ее протокол OpenID Connect.
Настоящий стандарт предназначен для:
участников получения информации о счете (банки и (или) небанковские кредитно-финансовые организации (далее – банк), их клиенты, а также сторонние поставщики, которые получают доступ к информации с согласия владельца счета);
участников перевода денежных средств (банки и их клиенты, а также сторонние поставщики, которые получают доступ к счету с согласия владельца счета);
разработчиков информационного и программного обеспечения, информационных систем.
2. Настоящий стандарт следует применять совместно со следующими техническими нормативными правовыми актами в области технического нормирования и стандартизации:
СТБ ISO/IEC 27000-2012 «Информационные технологии. Методы обеспечения безопасности. Системы менеджмента информационной безопасности. Основные положения и словарь», утвержденный постановлением Государственного комитета по стандартизации Республики Беларусь от 30 июня 2012 г. № 36 (далее – СТБ ISO/IEC 27000);
СТБ 34.101.45-2013 «Информационные технологии и безопасность. Алгоритмы электронной цифровой подписи и транспорта ключа на основе эллиптических кривых», утвержденный постановлением Государственного комитета по стандартизации Республики Беларусь от 30 августа 2013 г. № 45 (далее – СТБ 34.101.45);
СТБ 34.101.41-2013 «Информационные технологии и безопасность. Обеспечение информационной безопасности банков Республики Беларусь. Общие положения», утвержденный постановлением Государственного комитета по стандартизации Республики Беларусь от 31 октября 2013 г. № 56 (далее – СТБ 34.101.41);
СТБ 34.101.65-2014 «Информационные технологии и безопасность. Протокол защиты транспортного уровня (TLS)», утвержденный постановлением Государственного комитета по стандартизации Республики Беларусь от 22 мая 2014 г. № 23 (далее – СТБ 34.101.65);
СТБ 34.101.69-2014 «Информационные технологии и безопасность. Криптология. Термины и определения», утвержденный постановлением Государственного комитета по стандартизации Республики Беларусь от 14 августа 2014 г. № 35 (далее – СТБ 34.101.69);
СТБ 34.101.31-2020 «Информационные технологии и безопасность. Алгоритмы шифрования и контроля целостности», утвержденный постановлением Государственного комитета по стандартизации Республики Беларусь от 1 октября 2020 г. № 56 (далее – СТБ 34.101.31).
3. В настоящем стандарте применяются термины в значениях, установленных СТБ ISO/IEC 27000, СТБ 34.101.41, СТБ 34.101.45, СТБ 34.101.69, СТБ 34.101.31, а также следующие термины:
авторизация – проверка, подтверждение и предоставление прав логического доступа при осуществлении субъектами доступа логического доступа;
агент пользователя – клиентское приложение, использующее определенный сетевой протокол для доступа к серверу. Термин обычно используется для приложений, таких как браузеры, поисковые роботы, почтовые клиенты;
аутентификация – действия по проверке подлинности субъекта доступа и/или объекта доступа, а также по проверке принадлежности субъекту доступа и/или объекту доступа предъявленного идентификатора доступа и аутентификационной информации. Аутентификация рассматривается применительно к конкретному субъекту доступа и/или конкретному объекту доступа;
аутентифицированное шифрование с присоединенными данными – режим работы блочного шифра, который обеспечивает шифрование и имитозащиту открытого текста. При этом часть открытого текста (дополнительные аутентифицированные данные, AAD) не шифруется;
взаимная аутентификация – обоюдная аутентификация, обеспечивающая для каждого из участников процесса аутентификации – и субъекту доступа, и объекту доступа – уверенность в том, что другой участник процесса аутентификации является тем, за кого себя выдает;
владелец ресурса – субъект, способный предоставить доступ к защищенному ресурсу;
доступ – получение одной стороной информационного взаимодействия возможности использования ресурсов другой стороны. В качестве ресурсов стороны информационного взаимодействия, которые может использовать другая сторона информационного взаимодействия, рассматриваются информационные ресурсы, вычислительные ресурсы средств вычислительной техники и ресурсы автоматизированных (информационных) систем, а также средства вычислительной техники и автоматизированные (информационные) системы в целом;
защищенный ресурс – ресурс с ограниченным доступом;
клиент – приложение, выполняющее запросы защищенных ресурсов от имени владельца ресурса и с его авторизацией (не подразумевает каких-либо конкретных характеристик реализации (выполняется ли приложение на сервере, персональном компьютере или других устройствах);
код аутентификации сообщения – специальный набор символов, который добавляется к сообщению и предназначен для обеспечения его целостности и аутентификации источника данных;
код аутентификации сообщения на основе хэш-функции – специальный набор символов, сформированный на основе симметричного ключа с использованием хэш-функции, который добавляется к сообщению и предназначен для обеспечения его целостности и аутентификации источника данных;
конечная точка – адрес ресурса, точка входа интерфейса;
конечная точка авторизации – конечная точка, используемая клиентом для получения авторизации от владельца ресурса посредством перенаправления агента пользователя;
конечная точка клиента – конечная точка, на которую сервер авторизации возвращает ответы клиенту посредством агента пользователя;
конечная точка токена – конечная точка, используемая клиентом для обмена разрешения на доступ на токен доступа, обычно с аутентификацией клиента;
конечная точка UserInfo – защищенный ресурс, который при предоставлении клиентом токена доступа возвращает авторизованную информацию о конечном пользователе;
конечный пользователь – владелец ресурса в случае, если он является человеком;
конфиденциальный клиент – клиент, который может обеспечить конфиденциальность своих учетных данных или может выполнить безопасную аутентификацию клиента с использованием других средств;
криптографический ключ – изменяемый элемент (параметр), каждому значению которого соответствует одно из преобразований, реализуемых криптографическим алгоритмом;
нативное приложение – приложение, которое пользователь устанавливает на свое устройство, в отличие от веб-приложения, которое работает только в контексте браузера;
объект запроса – токен JWT, который содержит набор параметров запроса в качестве своих заявленных свойств;
односторонняя аутентификация – аутентификация, обеспечивающая только лишь для одного из участников процесса аутентификации (объекта доступа) уверенность в том, что другой участник процесса аутентификации (субъект доступа) является тем, за кого себя выдает, предъявленным идентификатором доступа;
параметр, заявленное свойство – часть информации, заявленной о субъекте. Заявленное свойство представлено в виде пары имя/значение, состоящей из имени заявленного свойства (параметра) и значения заявленного свойства (параметра);
протокол аутентификации – протокол, позволяющий участникам процесса аутентификации осуществить аутентификацию (протокол реализует алгоритм (правила), в рамках которого субъект доступа и объект доступа последовательно выполняют определенные действия и обмениваются сообщениями);
публичный клиент – клиент, который не может обеспечить конфиденциальность своих учетных данных (нативное приложение или приложение на основе веб-браузера) и не может выполнить безопасную аутентификацию клиента с помощью других средств;
разрешение на доступ – свидетельство, представляющее авторизацию владельца ресурса (для доступа к его защищенным ресурсам), которое далее используется клиентом для получения токена доступа;
сервер авторизации – сервер, выдающий клиенту токены доступа после успешной аутентификации владельца ресурса и получения авторизации;
сервер ресурсов – сервер, на котором размещены защищенные ресурсы, способный принимать и отвечать на запросы защищенных ресурсов с использованием токенов доступа;
токен доступа – свидетельство, представляющее авторизацию, выданную клиенту сервером авторизации с одобрения владельца ресурса;
токен на предъявителя – токен доступа с тем свойством, что любая сторона, владеющая токеном (предъявитель), может использовать токен по назначению, не доказывая владение соответствующим криптографическим ключом;
токен обновления – свидетельство, используемое для получения токенов доступа;
base64 кодирование – стандарт кодирования двоичных данных при помощи только 64 символов ASCII. Алфавит кодирования содержит алфавитно-цифровые латинские символы A-Z, a-z и 0–9 (62 знака) и 2 дополнительных символа, зависящих от системы реализации;
base64url кодирование – base64 кодирование строки октетов с использованием набора символов, допускающих использование результата кодирования в качестве имени файла или URL;
ID токен – токен идентификации, JSON веб-токен, который содержит параметры события аутентификации (может содержать также другие параметры);
JSON веб-токен – строка, представляющая набор параметров в формате объекта JSON, который закодирован в виде структуры JWS или JWE, сопровождая параметры электронной цифровой подписью (далее – цифровая подпись), кодом аутентификации и/или шифрованием.
MTLS (Mutual TLS) – процесс, в соответствии с которым при согласовании сеанса TLS выполняется взаимная аутентификация сервера TLS и клиента, а также подтверждение владения соответствующими ключами;
Nested JWT – JWT, в котором используются вложенные подпись и/или шифрование. В Nested JWT вложенная структура JWT используется в качестве полезной нагрузки или значения открытого текста вмещающей ее структуры JWS или JWE соответственно.
Термины «личный ключ», «открытый ключ», «электронная цифровая подпись» используются в значениях, определенных соответственно абзацами четвертым, шестым и пятнадцатым статьи 1 Закона Республики Беларусь от 28 декабря 2009 г. № 113-З «Об электронном документе и электронной цифровой подписи».
4. В настоящем стандарте применяются следующие обозначения:
СКЗИ – средство криптографической защиты информации;
API (Application Programming Interface) – интерфейс программирования приложений (интерфейс прикладного программирования);
ASCII (American Standard Code for Information Interchange) – стандарт 8-битного кодирования некоторого набора печатных и непечатных символов;
ASCII (STRING) – октеты ASCII представления последовательности ASCII символов STRING;
BASE64URL (OCTETS) – base64url кодирование строки октетов OCTETS;
CSRF (Cross Site Request Forgery) – межсайтовая подделка запроса;
DER (Distinguished Encoding Rules) – отличительные правила кодирования структур ASN.1;
FAPI (Financial-grade API) – API обеспечения безопасности финансовых сервисов;
HTTP (Hypertext Transfer Protocol) – протокол передачи гипертекстовых сообщений;
HTTPS (Hypertext Transfer Protocol Secure) – протокол защищенной передачи гипертекстовых сообщений;
HMAC (Hash-based Message Authentication Code) – код аутентификации сообщения на основе хэш-функции;
IANA (Internet Assigned Numbers Authority) – агентство по выделению имен и уникальных параметров протоколов Internet (администрация адресного пространства Интернет);
ID (identifier) – идентификатор, идентификационный номер;
IESG (Internet Engineering Steering Group) – группа технического управления Internet (исполнительный комитет IETF);
JARM (JWT Secured Authorization Response Mode for OAuth 2.0) – защищенный с использованием токена JWT режим ответа на запрос авторизации в OAuth 2.0;
JOSE (JavaScript Object Signing and Encryption) – технология подписи и шифрования объектов JavaScript;
JSON (JavaScript Object Notation) – текстовый формат обмена данными, основанный на JavaScript (нотация объектов JavaScript);
JWA (JSON Web Algorithmes) – набор криптографических алгоритмов и идентификаторов для использования со спецификациями JWS и JWE;
JWE (JSON Web Encryption) – структура данных в формате JSON, представляющая зашифрованное и защищенное от модификации сообщение;
JWK (JSON Web Key) – структура данных в формате JSON, представляющая криптографический ключ;
JWS (JSON Web Signature) – структура данных в формате JSON, представляющая сообщение с цифровой подписью или кодом аутентификации сообщений;
JWT (JSON Web Token) – токен доступа, основанный на формате JSON;
MAC (Message Authentication Code) – код аутентификации сообщения;
OAuth – открытый протокол (схема) авторизации;
OIDC (OpenID Connect Core) – семейство протоколов, являющихся расширением протоколов OAuth 2.0;
OIDF (OpenID Foundation) – некоммерческая организация, созданная для управления авторскими правами, товарными знаками, маркетинговыми компаниями и другой деятельностью, связанной с сообществом OpenID;
OpenID – открытый стандарт децентрализованной системы аутентификации;
PKI (Public Key Infrastructure) – инфраструктура открытых ключей;
REST (Representational State Transfer) – архитектурный стиль взаимодействия компонентов распределенного приложения в сети. REST представляет собой согласованный набор ограничений, учитываемых при проектировании распределенной гипермедиасистемы. Для веб-служб, построенных с учетом REST, применяют термин «RESTful»;
RFC (Request for Comments) – предложения для обсуждения; серия нормативных документов, стандартизирующих протоколы Internet;
TLS (Transport Layer Security) – протокол защиты транспортного уровня;
URI (Uniform Resource Identifier) – унифицированный идентификатор ресурса;
URL (Uniform Resource Locator) – унифицированный адрес ресурса (единый указатель ресурса);
URN (Uniform Resource Name) – унифицированное имя ресурса;
UTF-8 – стандарт кодирования символов, позволяющий компактно хранить и передавать символы Unicode, используя переменное количество байтов (от 1 до 4), и обеспечивающий полную обратную совместимость с кодировкой ASCII;
UTF8 (STRING) – октеты UTF-8 представления последовательности Unicode символов STRING;
A || B – операция конкатенации символьных строк A и B;
<name> – параметр (claim) некоторого субъекта с именем name.
5. При применении настоящего стандарта необходимо соблюдать требования, определенные банковским законодательством, законодательством об информации, информатизации и защите информации, в том числе о персональных данных, в частности:
Законом Республики Беларусь от 10 ноября 2008 г. № 455-З «Об информации, информатизации и защите информации»;
Законом Республики Беларусь «Об электронном документе и электронной цифровой подписи»;
Законом Республики Беларусь от 7 мая 2021 г. № 99-З «О защите персональных данных»;
Положением о технической и криптографической защите информации, утвержденным Указом Президента Республики Беларусь от 16 апреля 2013 г. № 196;
приказом Оперативно-аналитического центра при Президенте Республики Беларусь от 8 февраля 2019 г. № 45 «О дополнительных мерах по реализации Закона Республики Беларусь от 28 декабря 2009 г. № 113-З «Об электронном документе и электронной цифровой подписи»;
приказом Оперативно-аналитического центра при Президенте Республики Беларусь от 20 февраля 2020 г. № 66 «О мерах по реализации Указа Президента Республики Беларусь от 9 декабря 2019 г. № 449».
Раздел II
Технические требования
Глава 1
ОБЩИЕ ТЕХНИЧЕСКИЕ ТРЕБОВАНИЯ
6. API, реализующие требования настоящего стандарта, должны отвечать требованиям технических нормативных правовых актов и локальных правовых актов организаций, регламентирующих порядок анализа уязвимостей в API как на этапе его разработки, так и при его использовании в составе конечных целевых систем.
7. Разработка программного обеспечения, реализующего требования настоящего стандарта, должна осуществляться в соответствии с техническими нормативными правовыми актами в области разработки безопасного программного обеспечения. Кроме того, должен проводиться регулярный поиск информации, связанной с уязвимостями программ, в общедоступных источниках.
Глава 2
Технология авторизации OAuth 2.0
8. OAuth 2.0 – семейство протоколов авторизации, позволяющих одному приложению – клиенту – получить доступ к данным другого приложения – сервера ресурсов. При этом клиент получает разрешение на доступ от имени пользователя – владельца ресурса, который владеет необходимыми учетными данными, позволяющими его аутентифицировать. Непосредственно разрешение на доступ выдает клиенту сервер авторизации, на котором зарегистрирован владелец ресурса. Сервер ресурсов и сервер авторизации могут совпадать.
9. Схематично сценарий протокола OAuth 2.0 представлен на рисунке 1.
Рисунок 1 – Сценарий протокола OAuth 2.0
Сценарий протокола OAuth 2.0 описывает взаимодействие между сторонами и включает следующие шаги:
1) клиент запрашивает авторизацию у владельца ресурса. Запрос авторизации может быть направлен владельцу ресурса напрямую, как представлено на рисунке 1, или косвенно через сервер авторизации. Предпочтительным является второй вариант;
2) клиент получает разрешение на доступ, структуру данных, представляющую авторизацию владельца ресурса, выраженную с использованием одного из четырех типов разрешений: код авторизации, неявное разрешение, пароль владельца ресурса и учетные данные клиента. Тип разрешения на доступ зависит от метода, используемого клиентом для запроса авторизации и типов разрешений, поддерживаемых сервером авторизации. Типы разрешений, поддерживаемые сервером авторизации, определяются при его разработке, исходя из его прикладных целей и задач. Настоящий стандарт регламентирует использование в качестве типа разрешения код авторизации;
3) клиент запрашивает токен доступа посредством аутентификации на сервере авторизации и предоставление разрешения на доступ;
4) сервер авторизации аутентифицирует клиента, проверяет разрешение на доступ и, если разрешение действительно, выдает токен доступа;
5) клиент запрашивает защищенный ресурс на сервере ресурсов и аутентифицируется, предоставляя токен доступа;
6) сервер ресурсов проверяет токен доступа и, если токен доступа действителен, обслуживает запрос.
10. Для связи сервер авторизации и клиент используют конечные точки – адреса ресурсов или точки входа соответствующих сервисов. В процессе авторизации OAuth 2.0 используются две конечные точки сервера авторизации – конечная точка авторизации и конечная точка токена, а также одна конечная точка клиента.
11. Сервер авторизации должен поддерживать использование метода HTTP GET на конечной точке авторизации и может также поддерживать использование метода POST. При осуществлении запросов токена доступа клиент должен использовать метод HTTP POST.
12. Передача сообщений между клиентом и сервером авторизации должна производиться с использованием протокола TLS.
Глава 3
OpenID Connect. Протокол OpenID Connect
13. OIDC позволяет расширить функционал протоколов OAuth 2.0 путем более точного описания процесса аутентификации владельца ресурса и предоставления клиенту возможности получить информацию о нем. Это этапы 1–4 протокола OAuth 2.0, изображенного на рисунке 1.
14. Схематично сценарий протокола OpenID Connect представлен на рисунке 2.
Рисунок 2 – Сценарий протокола OpenID Connect
Сценарий протокола OpenID Connect описывает взаимодействие между сторонами и включает следующие шаги:
1) клиент отправляет серверу авторизации запрос аутентификации;
2) сервер авторизации аутентифицирует конечного пользователя и получает согласие пользователя на доступ клиента к запрошенному ресурсу;
3) сервер авторизации отвечает клиенту ID токеном и токеном доступа;
4) клиент может отправить серверу авторизации запрос информации о пользователе по токену доступа;
5) сервер авторизации возвращает клиенту информацию о конечном пользователе.
15. Сервер авторизации OpenID Connect поддерживает три сценария аутентификации, реализующие этот сценарий:
с генерацией кода авторизации (Authorization Code Flow);
неявный сценарий (Implicit Flow);
гибридный сценарий (Hybrid Flow).
Настоящий стандарт не предполагает использование неявного сценария.
16. Передача сообщений между клиентом и сервером авторизации (на конечных точках авторизации, токена и UserInfo) должна производиться с использованием протокола TLS.
Глава 4
OpenID Connect.
Аутентификация с генерацией кода авторизации
17. Сценарий протокола аутентификации OpenID Connect с генерацией кода авторизации использует код авторизации в качестве типа разрешения на доступ (grant). При этом выполняются следующие действия:
1) клиент генерирует запрос аутентификации;
2) клиент, используя агента пользователя (User Agent), отправляет запрос аутентификации на конечную точку авторизации сервера авторизации;
3) сервер авторизации аутентифицирует конечного пользователя;
4) сервер авторизации получает разрешение конечного пользователя на доступ клиента к защищенным ресурсам;
5) сервер авторизации генерирует код авторизации и перенаправляет агента пользователя на конечную точку клиента, включая значение сгенерированного кода авторизации в состав параметров запроса на переадресацию;
6) клиент запрашивает ID токен и токен доступа, используя код авторизации на конечной точке токена;
7) клиент получает ответ, содержащий ID токен и токен доступа;
8) клиент проверяет ID токен согласно требованиям, указанным в пункте 33 настоящего стандарта и получает идентификатор конечного пользователя.
18. В состав запроса аутентификации клиент может включать следующие параметры:
<scope> – (обязательный) область действия определяет свойства защищаемых данных конечного пользователя к которым запрошен доступ, в случае использования протокола OpenID Connect параметр <scope> должен содержать строку «openid»;
<response_type> – (обязательный) тип ответа и сценарий протокола авторизации, в данном сценарии используется следующее значение:
«code» – возвращает код авторизации, используется в сценарии аутентификации с генерацией кода авторизации;
<client_id> – (обязательный) идентификатор клиента OAuth 2.0, полученный при регистрации на сервере авторизации согласно описанию в пункте 46 настоящего стандарта;
<redirect_uri> – (обязательный) URI переадресации, на который будет отправлен ответ, должен быть предварительно зарегистрирован на сервере авторизации согласно описанию в пункте 46 настоящего стандарта;
<state> – (рекомендуемый) значение, используемое для синхронизации состояния между запросом и обратным вызовом, используется для защиты от атак межсайтовых запросов (CSRF);
<nonce> – (опциональный) случайное строковое значение, используемое для привязки сеанса клиента к ID токену и для защиты от атак повторного воспроизведения;
<prompt> – (опциональный) список строк, которые указывают, должен ли сервер авторизации запрашивать у конечного пользователя повторную аутентификацию и согласие на доступ клиента к ресурсу. Определены значения:
«none» – не требуется интерфейс пользователя;
«login» – серверу авторизации рекомендуется запросить повторную аутентификацию;
«consent» – серверу авторизации рекомендуется запросить у пользователя согласие на доступ к ресурсу;
«select_account» – серверу авторизации рекомендуется запросить у пользователя выбор учетной записи;
<max_age> – (опциональный) максимальный срок аутентификации. Определяет допустимое время в секундах, прошедшее с момента последней активной аутентификации конечного пользователя сервером авторизации. Если истекшее время больше этого значения, сервер авторизации должен пытаться активно повторно аутентифицировать конечного пользователя. Если в запросе аутентификации присутствует параметр <max_age>, возвращаемый ID токен должен включать значение параметра <auth_time>.
19. Серверы авторизации должны поддерживать на конечной точке авторизации методы HTTP GET и POST. Клиенты могут использовать методы HTTP GET или POST для отправки запроса аутентификации на сервер авторизации. При использовании метода HTTP GET параметры запроса сериализуются с использованием URI Query String Serialization. При использовании метода HTTP POST параметры запроса сериализуются с использованием сериализации форм (Form Serialization).
20. Также параметры запроса аутентификации могут быть переданы в качестве параметров (claims) JSON объекта запроса – JWT токена. JWT токен должен быть подписан и может быть зашифрован. JWT токен передается в кодировании base64url по значению через параметр <request> или по ссылке через параметр <request_URI>.
21. Сервер авторизации должен проверить полученный запрос следующим образом:
1) проверить наличие обязательных параметров запроса и их соответствие спецификациям OAuth 2.0 и OIDC;
2) убедиться, что параметр <scope> содержит значение области действия «openid»;
3) проверить, что все обязательные параметры присутствуют и их использование соответствует требованиям настоящего стандарта.
Серверу авторизации рекомендуется игнорировать неопознанные параметры запроса. В случае если хотя бы одна из вышеперечисленных проверок не пройдена, сервер авторизации должен вернуть ошибку в соответствии с требованиями, указанными в пункте 25 настоящего стандарта.
22. Если запрос аутентификации действителен, сервер авторизации пытается аутентифицировать конечного пользователя или определяет, аутентифицирован ли конечный пользователь. Методы, используемые сервером авторизации для аутентификации конечного пользователя (имя пользователя и пароль, файлы cookie сеанса и т.д.), не регламентируются настоящим стандартом.
Сервер авторизации должен запрашивать аутентификацию конечного пользователя в следующих случаях:
конечный пользователь еще не аутентифицирован;
запрос аутентификации содержит параметр <prompt> со значением «login». В этом случае сервер авторизации должен повторно аутентифицировать конечного пользователя, даже если конечный пользователь уже аутентифицирован.
Сервер авторизации не должен взаимодействовать с конечным пользователем в следующем случае: запрос аутентификации содержит параметр <prompt> со значением «none». В этом случае сервер авторизации должен возвратить ошибку, если конечный пользователь еще не прошел аутентификацию или не может быть аутентифицирован в режиме без вывода сообщений.
При взаимодействии с конечным пользователем сервер авторизации должен использовать соответствующие меры против подделки межсайтовых запросов (CSRF) и перехвата кликов (Clickjacking).
23. После аутентификации конечного пользователя сервер авторизации должен получить его разрешение об авторизации доступа к запрошенному ресурсу, прежде чем предоставлять информацию клиента. В случае если это определено параметрами запроса, разрешение может быть получено одним из следующих способов:
через интерактивный диалог с конечным пользователем, в ходе которого сервер авторизации отображает запрашиваемую клиентом область действия и запрашивает у конечного пользователя согласие на доступ;
путем установления согласия с помощью условий обработки запроса;
другими способами (с помощью предыдущего административного согласования).
24. После успешной аутентификации конечного пользователя и получения его разрешения на доступ клиента к защищенному ресурсу сервер авторизации генерирует код авторизации и передает его на конечную точку клиента, воспользовавшись адресом, который был ранее указан в параметре <redirect_uri> запроса аутентификации, с использованием формата «application/x-www-form-urlencoded». Параметры успешного ответа на запрос аутентификации:
<code> – (обязательный) значение кода авторизации (размер строки кода авторизации должен определяться при проектировании сервера авторизации);
<state> – (обязательный, если параметр <state> присутствует в запросе аутентификации) значение параметра <state> запроса аутентификации, полученного от клиента.
25. В случае ошибки при проверке запроса аутентификации, либо в процессе аутентификации конечного пользователя, сервер авторизации отвечает клиенту с указанием информации об ошибке.
Параметры сообщения об ошибке:
<error> – (обязательный) код ошибки;
<error_description> – (опциональный) текстовое описание ошибки;
<error_uri> – (опциональный) URI веб-страницы с дополнительной информацией об ошибке;
<state> – (обязательный, если параметр <state> присутствует в запросе аутентификации) значение параметра <state> запроса аутентификации, полученного от клиента.
Возможные значения кода ошибки:
«invalid_request» – в запросе отсутствует обязательный параметр, или он содержит недопустимое значение параметра, или содержит параметр более одного раза, или имеет иные неправильные значения параметров;
«unauthorized_client» – клиент не авторизован для запроса кода авторизации с использованием данного метода;
«access_denied» – владелец ресурса или сервер авторизации отклонил запрос;
«unsupported_response_type» – сервер авторизации не поддерживает выдачу кода авторизации с использованием данного метода;
«invalid_scope» – запрошенная область действия недействительна, неизвестна или имеет неправильный формат;
«server_error» – сервер авторизации обнаружил непредвиденное состояние, которое не позволило ему выполнить запрос;
«temporarily_unavailable» – сервер авторизации в настоящее время не может обработать запрос из-за временной перегрузки или обслуживания сервера;
«interaction_required» – для авторизации на сервере авторизации требуется взаимодействие с конечным пользователем (значение параметра <prompt> запроса аутентификации равно «none», но запрос аутентификации не может быть выполнен без отображения пользовательского интерфейса для взаимодействия с конечным пользователем);
«login_required» – сервер авторизации требует аутентификации конечного пользователя (значение параметра <prompt> запроса аутентификации равно «none», но запрос аутентификации не может быть выполнен без отображения пользовательского интерфейса для аутентификации конечного пользователя);
«account_selection_required» – конечный пользователь должен выбрать сеанс на сервере авторизации (значение параметра <prompt> запроса аутентификации равно «none», но запрос аутентификации не может быть выполнен без отображения пользовательского интерфейса, запрашивающего сеанс);
«consent_required» – серверу авторизации требуется согласие конечного пользователя (значение параметра <prompt> запроса аутентификации равно «none», но запрос аутентификации не может быть выполнен без отображения пользовательского интерфейса для получения согласия конечного пользователя);
«invalid_request_URI» – попытка доступа по адресу <request_URI> в запросе авторизации возвращает ошибку или содержит неверные данные;
«invalid_request_object» – параметр <request> содержит недопустимый объект запроса;
«request_not_supported» – сервер авторизации не поддерживает использование параметра <request>;
«request_URI_not_supported» – сервер авторизации не поддерживает использование параметра <request_URI>;
«registration_not_supported» – сервер авторизации не поддерживает использование параметра <registration>.
26. Получив успешный ответ на запрос аутентификации, клиент проверяет его. Клиент должен игнорировать нераспознанные параметры ответа. Клиент должен проверить соответствие длин параметров установленным при разработке сервера авторизации ограничениям. Клиент должен проверить, совпадает ли значение параметра <state>, полученное в составе ответа, со значением параметра <state> в запросе аутентификации, переданным клиентом.
27. В случае успешной проверки ответа сервера авторизации клиент формирует и отправляет на адрес конечной точки токена запрос токена. Параметры запроса токена:
<grant_type> – (обязательный) тип разрешения; в данном случае значением должна быть строка «authorization_code»;
<code> – (обязательный) значение кода авторизации, полученное от сервера авторизации;
<redirect_uri> – (обязательный) URI переадресации, на который будет отправлен ответ; должен быть предварительно зарегистрирован на сервере авторизации; значение этого параметра должно совпадать со значением параметра <redirect_uri> запроса авторизации;
<client_id> – (обязательный) идентификатор клиента, зарегистрированный сервером авторизации.
28. Сервер авторизации должен проверить запрос токена следующим образом:
аутентифицировать клиента в соответствии с требованиями, описанными в главе 7 настоящего стандарта;
убедиться, что код авторизации был выдан аутентифицированному клиенту;
убедиться, что код авторизации действителен;
убедиться, что код авторизации ранее не использовался;
убедиться, что значение параметра <redirect_uri> совпадает со значением параметра <redirect_uri>, которое было включено в начальный запрос авторизации. Если значение параметра <redirect_uri> отсутствует при наличии только одного зарегистрированного значения <redirect_uri>, сервер авторизации может вернуть ошибку (так как клиент должен был включить параметр) или может работать без ошибки (так как OAuth 2.0 разрешает опускать этот параметр в таком случае);
убедиться, что использованный код авторизации был выдан в ответ на запрос аутентификации OpenID Connect.
29. Коды авторизации должны быть кратковременными и одноразовыми. Если сервер авторизации регистрирует несколько попыток обмена одного и того же кода авторизации на токен доступа, серверу авторизации следует отозвать все токены доступа, уже предоставленные на основе скомпрометированного кода авторизации.
Сервер авторизации должен аутентифицировать клиента согласно требованиям, описанным в главе 7 настоящего стандарта, и гарантировать, что код авторизации был выдан клиенту, запросившему его.
30. Получив и успешно проверив запрос токена, сервер авторизации генерирует ID токен согласно описанию в пункте 32 настоящего стандарта, токен доступа согласно описанию в пункте 34 настоящего стандарта, а также, если необходимо, токен обновления согласно описанию в пункте 35 настоящего стандарта и возвращает их клиенту по адресу <redirect_uri> в теле HTTP ответа с кодом состояния 200 (ОК). В ответе используется тип формата «application/json». Ответ должен включать следующие поля и значения заголовка HTTP ответа:
Cache-Control: no-store;
Pragma: no-cache.
Параметры JSON структуры ответа на запрос токена:
<access_token> – (обязательный) токен доступа;
<token_type> – (обязательный) тип токена, должен иметь значение «Bearer»;
<expires_in> – (рекомендуемый) время жизни токена в секундах;
<refresh_token> – (опциональный) токен обновления;
<scope> – (опциональный) область действия токена доступа;
<id_token> – (обязательный) ID токен, связанный с текущей сессией доступа.
В случае ошибки проверки запроса токена сервер авторизации должен ответить сообщением об ошибке. Параметры и формат сообщения об ошибке приведены в пункте 25 настоящего стандарта. В теле HTTP ответа используется тип «application/json» с кодом HTTP ответа 400.
31. Клиент должен проверять правильность ответа на запрос токена следующим образом:
клиент должен игнорировать нераспознанные параметры ответа;
клиент должен прекратить проверку, если отсутствует значение хотя бы одного из обязательных параметров;
клиент должен сверить длины параметров с установленными в системе;
клиент должен проверить правильность ID токена согласно описанию в пункте 21 настоящего стандарта.
32. ID токен – это токен безопасности, который содержит параметры аутентификации конечного пользователя сервером авторизации. ID токен представляется в виде структуры JWT.
ID токен включает следующие параметры:
<iss> – (обязательный) идентификатор эмитента (сервера авторизации), источника ответа, регистрозависимый URL-адрес, использующий схему https; содержит схему, хост и опционально компоненты номера порта и пути, но не компоненты запроса или фрагмента;
<sub> – (обязательный) уникальный идентификатор субъекта, выданный сервером авторизации конечному пользователю, регистрозависимая строка длиной не более 255 символов ASCII;
<aud> – (обязательный) аудитория, для которой предназначен данный ID токен; должна содержать идентификатор <client_id>, в общем случае значение <aud> представляет собой массив чувствительных к регистру строк; если есть только один элемент, значением <aud> может быть единственная строка;
<exp> – (обязательный) время завершения срока действия, при наступлении и после наступления которого ID токен не должен приниматься к обработке, значением является число в формате JSON, представляющее количество секунд от 1970-01-01T0:0:0Z UTC до соответствующей даты/времени;
<iat> – (обязательный) время, когда был выпущен токен; значением является число в формате JSON, представляющее количество секунд от 1970-01-01T0:0:0Z UTC до соответствующей даты/времени;
<auth_time> – (обязательный, если в запросе аутентификации присутствует значение параметра <max_age>) время, когда выполнена аутентификация конечного пользователя; значением является число в формате JSON, представляющее количество секунд от 1970-01-01T0:0:0Z UTC до соответствующей даты/времени;
<nonce> – строковое значение, равно значению параметра <nonce> в запросе аутентификации, серверу авторизации следует включать этот параметр, если значение параметра <nonce> присутствует в соответствующем запросе аутентификации;
<azp> – (опциональный) идентификатор клиента стороны, для которого был выпущен ID токен.
ID токен должен быть подписан с использованием JWS, как описано в главе 9 настоящего стандарта. Он может быть подписан с использованием JWS и затем зашифрован с использованием JWE, как описано в главе 10 настоящего стандарта, как структура Nested JWT. При этом в ID токене не должна использоваться строка «none» в качестве значения параметра <alg>.
33. Проверка ID токена клиентом должна выполняться следующим образом:
1) если ID токен зашифрован, следует расшифровать его, используя ключи и алгоритмы, которые сервер авторизации должен был использовать для шифрования ID токена как JWE;
2) идентификатор эмитента (сервера авторизации), полученный при регистрации клиента, должен точно соответствовать значению параметра <iss> ID токена;
3) клиент должен убедиться, что значение параметра <aud> содержит значение <client_id>, полученное клиентом от сервера авторизации при регистрации; ID токен должен быть отклонен, если <aud> не содержит значение <client_id> клиента;
4) если ID токен содержит несколько компонент в составе параметра <aud>, клиент должен проверить наличие параметра <azp> и при его наличии проверить, что значение равно <client_id>;
5) клиент должен проверить подпись структуры JWS ID токена, применяя алгоритм, указанный в параметре <alg>, используя ключ, предоставленный сервером авторизации. Если ID токен получен посредством прямого обмена данными между клиентом и конечной точкой токена, проверка сообщений протокола TLS от сервера может использоваться для проверки эмитента вместо проверки подписи токена;
6) значение параметра <alg> должно быть значением по умолчанию или алгоритмом, зарегистрированным клиентом в значении параметра <id_token_signed_response_alg> во время регистрации;
7) если в значении параметра <alg> указан алгоритм MAC, то в качестве ключа должны использоваться октеты UTF-8 представления <client_secret>, соответствующего <client_id> клиента;
8) текущее время проверки должно быть раньше времени, указанного в значении параметра <exp>;
9) для отзыва токенов, выпущенных слишком давно, может использоваться параметр <iat>, который ограничивает время, необходимое для хранения значений параметра <nonce>. Приемлемый диапазон определяется при разработке сервера авторизации;
10) если в запросе аутентификации, отосланным клиентом в адрес сервера авторизации, указано значение параметра <nonce>, в структуре ID токена также должно присутствовать значение параметра <nonce>. Следует убедиться, что эти два значения совпадают;
11) если запрашивалось значение параметра <auth_time> либо посредством специального запроса этого параметра, либо указанием параметра <max_age> в запросе аутентификации, клиенту следует проверить значение параметра <auth_time> на допустимость диапазону <max_age> и сделать запрос повторной аутентификации, если он определяет, что с момента последней аутентификации конечного пользователя прошло слишком много времени.
34. Токен доступа (access token) содержит указание на конкретные области действия, к которым разрешен доступ, длительность доступа и другие параметры. Рекомендуется время жизни токена ограничить однократным использованием или очень коротким временем жизни.
Сервер авторизации должен во время авторизации уведомлять владельца ресурса о том, что он должен обратить внимание на запрос долгосрочного разрешения на доступ клиента к защищенному ресурсу. Серверу авторизации следует предоставить конечному пользователю механизм отзыва токенов доступа и токенов обновления, предоставленных клиенту.
35. Токен обновления (refresh token) выдается клиенту сервером авторизации и используется для получения нового токена доступа, когда текущий токен доступа становится недействительным, или истекает его срок действия, или для получения дополнительных токенов доступа с идентичной или более узкой областью действия (токены доступа могут иметь более короткий срок службы и меньше разрешений на доступ, чем разрешено владельцем ресурса). Выдача токена обновления необязательна и выполняется по усмотрению сервера авторизации. Если сервер авторизации выдает токен обновления, он включается в ответ при выдаче токена доступа. Данная функциональность не входит в область действия настоящего документа и определяется на этапе разработки сервера авторизации, исходя из его прикладных целей и задач.
Для постоянного доступа к конечной точке UserInfo или другим защищенным ресурсам используется токен обновления. Клиент может обменять токен обновления в конечной точке токена на новый кратковременный токен доступа, который можно использовать для доступа к ресурсу.
Решение о необходимости выдачи токена обновления принимается на этапе разработки сервера авторизации.
36. Клиент может получить информацию о конечном пользователе, либо извлекая ее из параметров ID токена, либо с помощью запроса к конечной точке UserInfo сервера авторизации.
Чтобы получить значение параметра информации о конечном пользователе, клиент отправляет запрос конечной точке UserInfo, используя токен доступа, полученный при аутентификации на сервере авторизации. Значения параметров в ответ возвращаются в виде JSON объекта, который содержит коллекцию пар «имя и значение параметра». Конечная точка UserInfo должна принимать токены доступа на предъявителя («Bearer»).
Конечная точка UserInfo должна поддерживать использование методов HTTP GET и HTTP POST. Взаимодействие между клиентом и сервером авторизации при обращении клиента на точку UserInfo должно быть защищено протоколом TLS.
Глава 5
OpenID Connect. Гибридный сценарий аутентификации
37. При использовании гибридного сценария некоторые токены возвращаются из конечной точки авторизации, другие – из конечной точки токена.
Гибридный сценарий состоит из следующих действий:
1) клиент генерирует запрос аутентификации, содержащий желаемые параметры запроса;
2) клиент отправляет запрос на сервер авторизации;
3) сервер авторизации аутентифицирует конечного пользователя;
4) сервер авторизации получает согласие/авторизацию конечного пользователя;
5) сервер авторизации возвращает конечного пользователя на клиента с передачей кода авторизации и в зависимости от типа ответа – одного или нескольких дополнительных параметров;
6) клиент запрашивает ответ на конечной точке токена, используя код авторизации;
7) клиент получает ответ, содержащий ID токен и токен доступа;
8) клиент проверяет ID токен и извлекает идентификатор субъекта конечного пользователя (значение параметра <sub>).
При использовании гибридного сценария действия сервера авторизации и клиента, связанные с формированием запроса аутентификации, его передачей, проверкой, а также аутентификацией пользователя и получением его согласия, в целом те же, что и в сценарии с кодом авторизации в соответствии с пунктами 18–23 настоящего стандарта. При этом параметр <response_type> запроса аутентификации должен иметь одно из следующих значений: «code id_token», либо «code token», либо «code id_token token».
38. В случае ошибки проверки запроса аутентификации ответ возвращается клиенту, как описано в пункте 25 настоящего стандарта. Если конечный пользователь отклоняет запрос или аутентификация конечного пользователя завершается неудачно, сервер авторизации должен возвратить ответ об ошибке авторизации в компоненте фрагмента URI переадресации.
В случае успешного ответа на запрос аутентификации все параметры ответа добавляются к компоненту фрагмента URI переадресации. При этом клиенту возвращаются значения следующих параметров:
<access_token> – (обязательный) токен доступа, если значение параметра <response_type> запроса аутентификации равно «code token» или «code id_token token»;
<token_type> – (обязательный) тип токена, если значение параметра <response_type> запроса аутентификации равно «code token» или «code id_token token», а если присутствует, значением должен быть тип «Bearer»;
<id_token> – (обязательный) ID токен, если значением <response_type> является «code id_token» или «code id_token token»;
<code> – (обязательный) код авторизации;
<state> – (обязательный), если в составе запроса аутентификации присутствует значение параметра <state>), значение параметра <state> из запроса аутентификации приведено в пункте 18 настоящего стандарта. Клиент должен проверить равенство возвращенного значения параметра <state> значению параметра <state>, переданному им в составе запроса аутентификации;
<expires_in> – (опциональный) время жизни токена доступа в секундах с момента генерации ответа.
39. Формат ID токена в данном сценарии аналогичен формату, описанному в пункте 32 настоящего стандарта, со следующими дополнениями:
параметр <nonce> (обязательный);
добавлен параметр <at_hash> – (обязательный) хэш-значение токена доступа, вычисляется сервером авторизации и проверяется клиентом как base64url кодирование левой половины хэш-значения октетов ASCII представления значения <access_token>, а если токен доступа не запрашивается, значение параметра <at_hash> должно отсутствовать;
добавлен параметр <c_hash> – (обязательный) значение которого вычисляется сервером авторизации и проверяется клиентом как base64url кодирование левой половины значения хэш-функции октетов ASCII представления значения параметра <code>.
40. Клиент должен убедиться в правильности ответа аутентификации:
следуя правилам, приведенным в пункте 31 настоящего стандарта;
проверив целостность токена доступа (если значение параметра <response_type> запроса аутентификации равно «code token» или «code id_token token») путем сравнения значения base64url кодирования левой половины полученного хэш-значения <access_token> с полученным значением параметра <at_hash>;
проверив целостность кода авторизации (если значение параметра <response_type> запроса аутентификации равно «code id_token» или «code id_token token») путем сравнения значения base64url кодирования левой половины полученного хэш-значения <code> с полученным значением параметра <c_hash>.
41. При использовании гибридного сценария запрос токена клиентом, проверка запроса токена, генерация токена доступа и ID токена на конечной точке токена, их проверка клиентом, а также реакция на ошибки выполняются в соответствии с аналогичными действиями в сценарии с генерацией кода авторизации, как описано в пунктах 27–31 настоящего стандарта.
Если ID токен возвращается как из конечной точки авторизации, так и из конечной точки токена, что имеет место для одного из двух значений <response_type>: «code id_token» и «code id_token token», значения <iss> и <sub> должны быть идентичны в обоих ID токенах. Все значения параметров события аутентификации, присутствующие в любом из них, должны присутствовать в обоих ID токенах. Если какой-либо ID токен содержит параметр конечного пользователя, присутствующий в обоих ID токенах, он должен иметь одинаковые значения в обоих ID токенах. Сервер авторизации может вернуть меньшее количество параметров о конечном пользователе из конечной точки авторизации (по соображениям конфиденциальности).
Глава 6
OpenID Connect. Регистрация сервера авторизации (Discovery) и динамическая регистрация клиента
42. Прежде чем запустить сервис аутентификации и авторизации клиентов, сервер авторизации должен опубликовать свои метаданные, описывающие его адрес и параметры доступа в ходе процедуры OpenID Connect Discovery.
43. Настоящий стандарт не регламентирует способ получения адреса сервера авторизации. Этот адрес может предоставляться клиенту (с указанием его в документации на систему). Сервер авторизации может также запускать сервис, поддерживающий технологию WebFinger.
44. Клиент может, используя HTTP GET запрос по адресу сервера авторизации, получить конфигурацию сервера авторизации (документ Discovery), в которой в JSON формате перечислены метаданные сервера авторизации. В частности, в конфигурации перечислены значения таких параметров:
<issuer> – (обязательный) https URL адрес, являющийся идентификатором эмитента (Issuer Identifier), далее это значение должно быть указано в качестве параметра <iss> в ID токенах, получив ответ, клиент должен проверить совпадение значения параметра <issuer> с адресом сервера авторизации, на который он делал запрос;
<authorization_endpoint> – (обязательный) URI конечной точки авторизации согласно описанию в пунктах 18–25 настоящего стандарта, может включать в себя компоненту запроса в формате «application/x-www-form-urlencoded», не должен включать компоненту фрагмента;
<token_endpoint> – (обязательный, кроме неявного сценария) URI конечной точки токена согласно описанию в пунктах 26–30 настоящего стандарта может включать в себя компоненту запроса в формате «application/x-www-form-urlencoded», не должен включать компоненту фрагмента;
<userinfo_endpoint> – (рекомендуемый) URI конечной точки UserInfo, предназначенный для запроса информации об аутентифицированном конечном пользователе согласно описанию в пункте 36 настоящего стандарта;
<registration_endpoint> – (рекомендуемый) URI конечной точки динамической регистрации клиентов сервера авторизации согласно описанию в пункте 21 настоящего стандарта;
<jwks_uri> – (обязательный) URL документа Key Set согласно описанию в пункте 43 настоящего стандарта сервера авторизации, где публикуются его ключи в формате JWK. Публикуемые сертификаты должны передаваться доверенным образом;
<grant_types_supported> – (опциональный) перечень поддерживаемых сервером авторизации типов разрешений на доступ (grants). Сервера авторизации OIDC должны поддерживать значения «authorization_code» и «implicit», по умолчанию используется значение «authorization_code» и «implicit»;
<scopes_supported> – (рекомендуемый) JSON массив значений параметра <scope>, которые поддерживает сервер авторизации;
<response_types_supported> – (обязательный) JSON массив с перечнем поддерживаемых значений параметра <response_type>. Сервера авторизации OIDC должны поддерживать значения «code», «id_token» и «token id_token»;
<response_modes_supported> – (опциональный) JSON массив с перечнем поддерживаемых значений параметра <response_mode> по умолчанию «query», «fragment». В главе 27 настоящего стандарта приведен перечень значений <response_mode>, связанный с использованием технологии JARM;
<claims_supported> – (рекомендуемый) JSON массив, содержащий список имен параметров, значения которых сервер авторизации может предоставить клиенту;
<service_documentation> – (опциональный) URL-адрес страницы, содержащей читаемую информацию, которая представляется разработчиками или которую нужно знать при использовании сервера авторизации (если сервер авторизации не поддерживает динамическую регистрацию клиентов, в этой документации должна быть представлена информация о том, как регистрировать клиентов).
В главе 27 настоящего стандарта приведен перечень дополнительных метаданных сервера авторизации, связанных с использованием технологии JARM.
Адреса всех перечисленных выше конечных точек сервера авторизации должны быть разными.
45. Передача сообщений Discovery, в том числе и сообщений сервиса WebFinger, между клиентом и сервером авторизации должна быть защищена с помощью протокола TLS с обеспечением конфиденциальности и целостности. При этом должна выполняться аутентификация источника информации Discovery.
46. Процедура динамической регистрации клиента выполняется после того, как выполнена регистрация сервера авторизации, описанная выше.
Для регистрации клиент посылает HTTP POST запрос серверу авторизации на конечную точку регистрации клиентов (параметр <registration_endpoint> документа Discovery) с типом содержимого «application/json», в котором указываются следующие метаданные клиента:
<redirect_uris> – (обязательный) перечень поддерживаемых адресов переадресации клиента, одно из этих зарегистрированных значений URI переадресации должно точно соответствовать значению параметра <redirect_uri>, используемому в каждом запросе авторизации;
<response_types> – (опциональный) JSON массив, содержащий перечень поддерживаемых клиентом типов ответа согласно описанию в пункте 18 настоящего стандарта, по умолчанию – значение «code»;
<grant_types> – (опциональный) JSON массив, содержащий перечень поддерживаемых клиентом типов разрешений на доступ (grants) из перечня: «authorization_code», «implicit», «refresh_token», по умолчанию используется значение «authorization_code»;
<application_type> – (опциональный) тип клиента «native» или «web»;
<contacts> – (опциональный) массив адресов электронной почты лиц, ответственных за этого клиента;
<client_name> – (опциональный) имя клиента, которое будет показано конечному пользователю при запросе авторизации;
<logo_uri> – (опциональный) URL ссылка на логотип клиентского приложения, если присутствует, сервер должен отображать это изображение конечному пользователю во время запроса авторизации;
<client_uri> – (опциональный) URL домашней страницы клиента, если присутствует, сервер должен отображать этот URL-адрес конечному пользователю;
<policy_uri> – (опциональный) URL-адрес, который клиент предоставляет конечному пользователю с информацией о том, как будут использоваться данные его профиля, при присутствии, сервер авторизации должен показать этот URL-адрес конечному пользователю;
<tos_uri> – (опциональный) URL-адрес, который клиент предоставляет конечному пользователю для ознакомления с условиями обслуживания клиента, при отсутствии, сервер авторизации должен показать этот URL-адрес конечному пользователю;
<jwks_uri> – (опциональный) URI документа JWK Set согласно описанию в пункте 68 настоящего стандарта, содержащего ключи клиента в формате JWK, публикуемые сертификаты должны передаваться безопасным образом;
<jwks> – (опциональный) документ JWK Set, передаваемый по значению, параметры <jwks_uri> и <jwks> не должны одновременно присутствовать в метаданных клиента, сертификаты открытых ключей должны передаваться доверенным образом;
<default_max_age> – (опциональный) максимальный возраст аутентификации по умолчанию, указывает, что конечный пользователь должен быть повторно аутентифицирован, если с момента его аутентификации прошло более чем указанное количество секунд;
<require_auth_time> – (опциональный) логическое значение, указывающее, требуется ли указывать параметр <auth_time> в ID токене, значением по умолчанию является «false»;
<token_endpoint_auth_method> – (опциональный) поддерживаемый метод аутентификации клиента на конечной точке токена, возможные варианты: «client_secret_post», «client_secret_basic», «client_secret_jwt», «private_key_jwt», «tls_client_auth», «self_signed_tls_client_auth» и «none» согласно описанию в главе 7 настоящего стандарта.
47. Сервер авторизации может игнорировать значения, предоставленные клиентом, и должен игнорировать любые присланные клиентом метаданные, которые он не понимает. Сервер авторизации должен проверить все заявленные значения метаданных клиента на их совместимость со спецификациями OIDC, а также с ограничениями, которые устанавливаются при разработке сервера авторизации. Сервер авторизации может выбрать замену действительного значения для любого запрошенного параметра метаданных клиента.
В случае если все запрошенные значения параметров клиента корректны, сервер авторизации должен, используя код HTTP 201, возвратить клиенту JSON документ с типом содержимого «application/json» со следующей информацией:
<client_id> – (обязательный) уникальный идентификатор клиента, который далее будет использоваться клиентом в протоколах OIDC;
<client_secret> – (опциональный) конфиденциальная информация, которая возвращается конфиденциальным клиентам и используется для аутентификации клиента сервером авторизации, а также для защиты взаимодействия клиента и сервера авторизации, значение этого параметра обязательно при использовании механизма аутентификации клиента <client_secret_jwt>;
<client_id_issued_at> – (опциональный) время выдачи идентификатора клиента, значение представляет собой число, представляющее количество секунд от 1970-01-01T0:0:0Z UTC до текущего момента;
<client_secret_expires_at> – (обязательный, если присутствует <client_secret>) время окончания действия <client_secret> или 0, если он не устаревает никогда, значение представляет собой число, представляющее количество секунд от 1970-01-01T0:0:0Z UTC до текущего момента.
Кроме того, сервер авторизации возвращает клиенту в составе ответа метаданные клиента, принятые сервером в запросе регистрации.
Должна быть обеспечена конфиденциальность передачи значения параметра <client_secret>. Механизм защиты должен быть определен на этапе разработки сервера авторизации.
48. При ошибке обработки запроса регистрации согласно описанию в пункте 47 настоящего стандарта сервер авторизации не выполняет регистрацию клиента, а конечная точка регистрации возвращает клиенту код состояния HTTP 400, включая JSON объект, описывающий ошибку в теле ответа.
JSON объект, описывающий ошибку, содержит два обязательных параметра <error> и <error_description> в формате, приведенном в пункте 38 настоящего стандарта. Коды ошибки:
«invalid_redirect_uri» – значение одного или нескольких значений массива <redirect_uris> недопустимо;
«invalid_client_metadata» – значение одного из полей метаданных клиента недопустимо, и сервер отклонил этот запрос.
49. Передача информации между клиентом и конечной точкой регистрации сервера авторизации должна быть защищена с помощью протокола TLS с аутентификацией сервера авторизации.
Глава 7
Аутентификация клиента
50. При динамической регистрации согласно описанию в пункте 46 настоящего стандарта клиент может зарегистрировать метод аутентификации клиента, указав его идентификатор в качестве значения параметра <token_endpoint_auth_method>. Если этот метод не зарегистрирован, по умолчанию используется метод «client_secret_basic». Можно использовать следующие варианты механизмов аутентификации:
«client_secret_basic» – аутентификация с использованием базовой схемы аутентификации HTTP и <client_secret>;
«client_secret_post» – аутентификация с включением учетных данных клиента в тело запроса и с использованием <client_secret>;
«client_secret_jwt» – аутентификация с использованием структуры JWT на основе кода аутентификации HMAC и <client_secret> согласно описанию в пункте 51 настоящего стандарта;
«private_key_jwt» – аутентификация с использованием структуры JWT на основе электронной цифровой подписи согласно описанию в пункте 52 настоящего стандарта;
«tls_client_auth» – аутентификация с использованием TLS с взаимной аутентификацией и PKI для связывания сертификата с клиентом согласно описанию в пункте 53 настоящего стандарта;
«self_signed_tls_client_auth» – аутентификация с использованием TLS с взаимной аутентификацией и сертификата клиента согласно описанию в пункте 54 настоящего стандарта;
«none» – клиент не аутентифицирует себя в конечной точке токена либо потому, что он использует только неявный сценарий аутентификации (и поэтому не использует конечную точку токена), либо потому, что он является публичным клиентом без <client_secret>, либо используется другой механизм аутентификации.
В реализациях настоящего стандарта допускается использование механизмов аутентификации клиента «client_secret_basic», «client_secret_post» и «none» только в тестовом режиме.
51. Механизм аутентификации «client_secret_jwt».
Клиент, получивший при регистрации значение <client_secret> от сервера авторизации, создает токен JWT, используя для обеспечения его целостности алгоритмы вычисления кода аутентификации сообщения HMAC на основе хэш-функции и значение <client_secret> в качестве ключа.
Данный механизм использует следующие параметры JWT согласно описанию в главе 12 настоящего стандарта:
<iss> – (обязательный) источник; должен содержать <client_id> клиента;
<sub> – (обязательный) субъект; должен содержать <client_id> клиента;
<aud> – (обязательный) аудитория; значением должен быть URL-адрес конечной точки токена сервера авторизации;
<jti> – (обязательный) идентификатор JWT; уникальный идентификатор токена, который необходим для предотвращения повторного использования токена;
<exp> – (обязательный) время, по истечении которого токен не должен быть принят к обработке;
<iat> – (опциональный) время выпуска JWT.
Токен JWT должен быть отправлен клиентом серверу авторизации в качестве значения параметра <client_assertion>. Значение параметра <client_assertion_type> должно быть «urn:ietf:params:oauth:client-assertion-type:jwt-bearer». Эти параметры передаются в качестве утверждений (assertions) методом HTTP POST в адрес конечной точки авторизации с типом содержимого «application/x-www-form-urlencoded».
При использовании JWT для аутентификации клиента сервер авторизации должен проверить JWT в соответствии с приведенными ниже критериями:
JWT должен содержать значение параметра <iss> (эмитент);
JWT должен содержать значение параметра <sub> (субъект), идентифицирующего субъект JWT. Для аутентификации клиента это значение должно совпадать с <client_id> клиента;
JWT должен содержать значение параметра <aud> (аудитория), которое идентифицирует сервер авторизации как предполагаемую аудиторию. В качестве значения элемента <aud> может использоваться URL-адрес конечной точки токена сервера авторизации. Сервер авторизации должен отклонить JWT, который не содержит своего идентификатора в качестве аудитории;
JWT должен содержать значение параметра <exp> (время действия), ограничивающее временное окно, в течение которого JWT может отслеживаться. Сервер авторизации должен отклонить любой JWT с истекшим временем действия при условии допустимого расхождения часов. Сервер авторизации может отклонить JWT с необоснованно большим значением параметра <exp>;
JWT может содержать значение параметра <nbf> (не ранее), определяющее время, до которого токен не должен приниматься для обработки;
JWT может содержать значение параметра <iat> (время выпуска). Сервер авторизации может отклонять JWT со значением <iat>, которое необоснованно далеко от настоящего;
JWT может содержать значение параметра <jti> (JWT ID), которое предоставляет уникальный идентификатор токена. Сервер авторизации может гарантировать, что JWT не будут воспроизведены, поддерживая набор используемых значений <jti> в течение определенного промежутка времени, в течение которого JWT будет считаться действительным, на основе применимого момента <exp>;
JWT может содержать другие параметры;
JWT должен иметь цифровую подпись или MAC, применяемый эмитентом. Сервер авторизации должен проверить подпись JWT как JWS и отклонить JWT с недопустимой подписью или MAC.
В случае ошибки проверки JWT сервер авторизации должен ответить кодом ошибки «invalid_client» в качестве значения параметра <error> согласно описанию в пункте 25 настоящего стандарта. В случае успешной проверки JWT клиент считается аутентифицированным.
Для обеспечения безопасности передачи сообщений аутентификации клиента должен использоваться протокол TLS.
52. Механизм аутентификации «private_key_jwt».
Клиент, который зарегистрировал ключ проверки цифровой подписи, подписывает JWT, используя соответствующий ключ цифровой подписи для обеспечения целостности JWT. Перечень параметров JWT, а также процедура передачи такие же, как в пункте 51 настоящего стандарта.
53. Механизм аутентификации с использованием TLS с взаимной аутентификацией и PKI.
Механизм аутентификации клиента с использованием TLS с взаимной аутентификацией и PKI требует выполнения следующих действий:
1) в ходе динамической регистрации согласно описанию в пункте 46 настоящего стандарта клиент должен получить у сервера авторизации идентификатор <client_id>;
2) в ходе динамической регистрации клиент должен зарегистрировать механизм аутентификации «tls_client_auth»;
3) в ходе динамической регистрации клиент должен зарегистрировать ровно одно из имен субъекта сертификата клиента в качестве значения одного из следующих параметров:
<tls_client_auth_subject_dn> – отличительное имя субъекта сертификата;
<tls_client_auth_san_dns> – значение записи SAN dNSName в сертификате;
<tls_client_auth_san_uri> – значение записи SANiformResourceIdentifier в сертификате;
<tls_client_auth_san_ip> – IP-адрес IPv4 или IPv6 из записи iPAddress SAN в сертификате;
<tls_client_auth_san_email> – значение записи SAN rfc822Name в сертификате;
4) у клиента должен быть установлен сертификат открытого ключа формата X.509, в котором указано одно отличительное имя субъекта (subject distinguished name, DN) и одно альтернативное имя субъекта (SAN). Сертификат должен успешно проходить процедуру валидации цепочки сертификатов;
5) при установлении TLS-соединения сервер авторизации должен потребовать сертификат клиента и проверить его валидность, а также получить подтверждение владения закрытым ключом, соответствующим открытому ключу, указанному в сертификате;
6) сервер авторизации на основании предъявленного значения <client_id> должен извлечь из данных регистрации клиента его имя подпункт 3) настоящей части и сравнить с именем, полученным из предъявленного сертификата. В случае совпадения имен принимается решение об успешном прохождении аутентификации клиента. Иначе сервер авторизации должен ответить кодом ошибки «invalid_client».
Такой механизм аутентификации позволяет просто выполнять обновление ключей и сертификата клиента в соответствии со штатной процедурой PKI.
54. Механизм аутентификации с использованием TLS с взаимной аутентификацией и сертификата клиента.
MTLS-аутентификация клиента с использованием сертификата клиента (подписан ключом подписи клиента, соответствующим ключу проверки подписи в составе сертификата) требует выполнения следующих действий:
1) в ходе динамической регистрации клиент должен зарегистрировать механизм аутентификации «self_signed_tls_client_auth»;
2) в ходе динамической регистрации клиент должен зарегистрировать свои сертификаты формата X.509, либо непосредственно публикуя их в качестве значения параметра <jwks> в формате JWK Set, либо указывая в качестве значения параметра <jwks_uri> ссылку на доверенный источник, содержащий его сертификаты в формате JWK Set;
3) во время установления TLS-соединения сервер авторизации должен запросить сертификат клиента, проверить его валидность, а также выполнить проверку владения клиента закрытым ключом, соответствующим открытому ключу, представленному в сертификате. В отличие от метода PKI согласно описанию в пункте 53 настоящего стандарта цепочка сертификатов клиента в этом случае не проверяется сервером авторизации;
4) клиент успешно аутентифицируется, если сертификат, который он представил во время установления TLS-соединения, соответствует одному из сертификатов, зарегистрированных для этого клиентом в подпункте 2) настоящей части.
Метод самоподписанного сертификата позволяет использовать MTLS для аутентификации клиентов без необходимости поддерживать PKI. При использовании вместе с <jwks_uri> клиента он также позволяет клиенту обновлять свои сертификаты X.509 без необходимости изменять свои аутентификационные данные.
Глава 8
Доступ к защищенному ресурсу
55. Доступ клиента к защищенному ресурсу обеспечивает сервер ресурсов. Выполняя запрос, клиент передает ему полученный от сервера авторизации токен доступа. Сервер ресурса проверяет этот токен доступа: его срок действия, присутствие запрашиваемого ресурса в области действия токена. При этом предполагается использование связи сервера ресурса с сервером авторизации.
56. При запросе защищенного ресурса токен доступа может быть передан клиентом серверу ресурса в заголовке авторизации HTTP (Authorization Request Header). В этом случае значение заголовка <Authorization> должно иметь формат:
Authorization = «Bearer» || <token>,
где <token> – значение токена доступа в кодировании base64url.
Клиенту рекомендуется использовать этот метод авторизации. Сервер ресурса должен его поддерживать.
Альтернативный вариант передачи токена доступа от клиента серверу ресурса – в теле HTTP-запроса как значение параметра <access_token>. При этом должны быть выполнены следующие условия:
поле <Content-Type> заголовка HTTP-запроса имеет значение «application/x-www-form-urlencoded»;
тело запроса соответствует требованиям кодирования контента «application/x-www-form-urlencoded»;
тело HTTP-запроса состоит из одной части, то есть запрос не является запросом типа «multipart/form-data»;
содержимое тела запроса должно состоять исключительно из ASCII-символов;
должен использоваться HTTP метод, семантика тела запроса которого строго определена. В частности, это означает, что HTTP метод GET не должен использоваться.
Клиенту не рекомендуется использовать такой метод авторизации, кроме случаев, когда браузер не имеет доступа к <Authorization> заголовку HTTP-запроса. Сервер ресурсов может поддерживать этот метод.
57. Канал передачи информации между клиентом и сервером ресурса должен быть защищен с помощью протокола TLS с обеспечением конфиденциальности и целостности.
Глава 9
JWT. ЦИФРОВАЯ ПОДПИСЬ В ФОРМАТЕ JSON
58. JWS (JSON Web Signature) – структура данных в формате JSON, представляющая сообщение с цифровой подписью или кодом аутентификации сообщений.
59. JWS состоит из трех частей:
<JOSE Header> – JOSE заголовок – JSON-объект, содержащий параметры, описывающие криптографические операции и их параметры;
<JWS Payload> – функциональное содержимое JWS (полезная нагрузка) – последовательность октетов, подлежащих защите, т. е. сообщение, функциональное содержимое может состоять из произвольной последовательности октетов;
<JWS Signature> – цифровая подпись или код аутентификации сообщений, вычисленные на основе защищенного заголовка JWS и функционального содержимого JWS.
Заголовок <JOSE Header> JWS состоит из двух частей:
<JWS Protected Header> – защищенный заголовок JWS – JSON-объект, содержащий параметры заголовка, целостность которых защищена цифровой подписью JWS или операцией MAC;
<JWS Unprotected Header> – незащищенный заголовок JWS – JSON-объект, который содержит параметры заголовка, целостность которых не обеспечивается.
60. Для передачи структуры JWS может использоваться один из двух типов сериализации:
компактная сериализация – представление JWS в виде компактной URL-строки;
JSON-сериализация – представление JWS в виде объекта JSON.
При использовании компактной сериализации JWS представляется как строка:
BASE64URL(UTF8(<JWS Protected Header>) || ‘.’ || BASE64URL(<JWS Payload>) || ‘.’ || BASE64URL(<JWS Signature>)).
Порядок элементов строки критичен.
В JSON-сериализации JWS представляется в виде JSON-объекта, содержащего значения следующих параметров:
<protected> – со значением BASE64URL(UTF8(<JWS Protected Header>)), если значение параметра <JWS Protected Header> не пустое; иначе значение параметра <protected> должно отсутствовать;
<header> – со значением <JWS Unprotected Header>, этот параметр должен присутствовать, если значение <JWS Unprotected Header> не пустое, иначе он должен отсутствовать;
<payload> – (обязательный) со значением BASE64URL(<JWS Payload>);
<signature> – (обязательный) со значением BASE64URL(<JWS Signature>).
61. Имена параметров заголовка <JOSE Header> должны быть уникальными, синтаксические анализаторы JWS должны либо отклонить JWS с повторяющимися именами параметров заголовка, либо использовать анализатор JSON, который возвращает только лексически последнее повторяющееся имя элемента. Реализация настоящего стандарта должна принимать параметры <JOSE Header> и обрабатывать их так, как определено настоящим стандартом. Все остальные параметры <JOSE Header>, определенные в настоящем стандарте, но не обозначенные таким образом, должны игнорироваться, если они не поняты.
<JOSE Header> может включить следующие параметры:
<alg> – (обязательный) идентификатор криптографического алгоритма цифровой подписи или MAC, используемого для защиты JWS;
<jku> – (опциональный) URI, который указывает на ресурс, где находится ключ проверки подписи в представлении JWK согласно описанию в главе 11 настоящего стандарта, который используется для проверки цифровой подписи JWS;
<jwk> – (опциональный) ключ проверки подписи в представлении JWK согласно описанию в главе 11 настоящего стандарта, который используется для проверки цифровой подписи JWS;
<kid> – (опциональный) идентификатор ключа, который используется для защиты JWS;
<x5u> – (опциональный) URI, который ссылается на ресурс сертификата формата X.509 или цепочки сертификатов ключа проверки электронной цифровой подписи JWS. Данный ресурс должен содержать представление сертификата или цепочки сертификатов в соответствии со стандартом RFC 5280 в PEM кодировании. Сертификат ключа проверки цифровой подписи JWS должен быть первым сертификатом, в цепочке сертификатов каждый последующий сертификат должен использоваться для сертификации предыдущего. Получатель должен проверить цепочку сертификатов в соответствии со стандартом RFC 5280. Считать сертификат или цепочку сертификатов и подпись JWS недействительными в случае отрицательного результата проверки, для получения ресурса должен использоваться HTTP запрос GET и протокол TLS;
<x5c> – (опциональный) сертификат формата X.509 или цепочка сертификатов проверки цифровой подписи JWS. Сертификат или цепочка сертификатов представлены в виде JSON-массива строк значений сертификата, каждая строка массива содержит кодировку base64, в соответствии со стандартом RFC 4648, значения DER-представления сертификата формата X.509. Сертификат ключа проверки цифровой подписи JWS должен быть первым сертификатом, в цепочке сертификатов каждый последующий сертификат должен использоваться для сертификации предыдущего. Получатель должен проверить цепочку сертификатов в соответствии со стандартом RFC 5280. Считать сертификат или цепочку сертификатов и подпись JWS недействительными в случае отрицательного результата проверки;
<typ> (Type) – (опциональный) тип сериализации («JOSE» – компактная сериализация, «JOSE+JSON» – JSON-сериализация);
<cty> (Content Type) – (опциональный) тип (media type) функционального содержимого JWS, как правило, используется, если в приложении несколько типов объектов могут быть представлены в качестве содержимого <JWS Payload>;
<crit> – (опциональный) JSON-массив имен критичных параметров заголовка; если какой-то из параметров, чье имя внесено в этот массив, не поддерживается или не понято получателем, JWS считается недействительной; если параметр <crit> присутствует, он должен быть понят и обработан получателем.
Значение цифровой подписи или MAC <JWS Signature> вычисляется с помощью алгоритма, указанного значением параметра алгоритма <alg>, используя на входе алгоритма подписи (MAC) ключ, идентифицируемый параметрами <jku>, <jwk>, <kid>, <x5u>, <x5c>, и следующую подписываемую последовательность октетов:
ASCII(BASE64URL(UTF8((<JWS Protected Header>)) || ‘.’ || BASE64URL(<JWS Payload>)).
Проверка подписи JWS выполняется с помощью преобразования проверки цифровой подписи. Если проверка формата JWS или проверка подписи дала отрицательный результат, JWS отвергается как не валидная.
Глава 10
JWT. JSON-СТРУКТУРА ШИФРОВАННОГО ТЕКСТА
62. JWE (JSON Web Encryption) – структура данных в формате JSON, представляющая зашифрованное и защищенное от модификации сообщение.
Структура JWE:
<JOSE Header> – JOSE заголовок – JSON-объект, содержащий параметры, описывающие криптографические операции и их параметры согласно описанию в пункте 61 настоящего стандарта;
<JWE Encrypted Key> – зашифрованный ключ защиты содержимого JWE для каждого получателя;
<JWE Initialization Vector> – синхропосылка (вектор инициализации) JWE;
<JWE AAD> – дополнительные аутентифицируемые, не шифруемые данные JWE;
<JWE Ciphertext> – шифротекст JWE;
<JWE Authentication Tag> – имитовставка JWE.
В состав <JOSE Header> входят следующие компоненты:
<JWE Protected Header> – защищенный заголовок JWE, целостность значения которого будет защищаться JWE;
<JWE Shared Unprotected Header> – общий незащищенный заголовок JWE;
<JWE Per-Recipient Unprotected Header> – незащищенный заголовок для каждого получателя JWE.
Для обеспечения конфиденциальности и целостности открытого текста, а также целостности защищенного заголовка и <JWE AAD> используется алгоритм аутентифицированного шифрования с присоединенными данными.
63. Как и JWS, структура JWE использует компактную и JSON-сериализацию. В компактной сериализации JWE представляется следующим образом:
BASE64URL(UTF8(<JWE Protected Header>) || ‘.’ || BASE64URL(<JWE Encrypted Key>) || ‘.’ || BASE64URL(<JWE Initialization Vector>) || ‘.’ || BASE64URL(<JWE Ciphertext>) || ‘.’ || BASE64URL(<JWE Authentication Tag>).
Компактная сериализация не поддерживает параметры <JWE Shared Unprotected Header>, <JWE Per-Recipient Unprotected Header> и <JWE AAD>. Кроме того, она предполагает одного получателя сообщения.
В случае JSON-сериализации JWE представлен в виде JSON-объекта, содержащего следующие параметры:
<protected> – если заголовок <JWE Protected Header> не пустой, этот параметр должен присутствовать со значением BASE64URL(UTF8(<JWE Protected Header>)), иначе этот параметр должен отсутствовать;
<unprotected> – если заголовок <JWE Shared Unprotected Header> не пустой, этот параметр должен присутствовать со значением <JWE Shared Unprotected Header>, иначе этот параметр должен отсутствовать; как правило, это JSON-объект;
<recipients> – (обязательный) массив JSON-объектов, в адрес каждого получателя JWE, структура этого объекта<header>, если заголовок <JWE Per-Recipient Unprotected Header> не пустой, этот параметр должен присутствовать со значением <JWE Per-Recipient Unprotected Header>, иначе этот параметр должен отсутствовать; как правило, это JSON-объект;
<encrypted_key> – если значение <JWE Encrypted Key> не пустое, этот параметр должен присутствовать со значением BASE64URL(<JWE Encrypted Key>), иначе этот параметр должен отсутствовать;
<iv> – если значение <JWE Initialization Vector> не пустое, этот параметр должен присутствовать со значением BASE64URL(<JWE Initialization Vector>), иначе этот параметр должен отсутствовать;
<aad> – если значение <JWE AAD> не пустое, этот параметр должен присутствовать со значением BASE64URL(<JWE AAD>), иначе этот параметр должен отсутствовать;
<ciphertext> – (обязательный) шифротекст со значением BASE64URL (<JWE Ciphertext>);
<tag> – если значение <JWE Authentication Tag> не пустое, этот параметр должен присутствовать со значением BASE64URL (<JWE Authentication Tag>), иначе этот параметр должен отсутствовать.
64. Параметры JOSE заголовка:
<enc> – (обязательный) идентификатор алгоритма шифрования, используемого для выполнения аутентифицированного шифрования открытого текста, этот параметр должен быть понят и обработан получателем;
<zip> – (опциональный) идентификатор алгоритма сжатия, который применяется к незашифрованному тексту перед шифрованием, определено единственное значение: «DEF» – алгоритм сжатия DEFLATE, если значение этого параметра отсутствует, выполняется шифрование открытого текста без сжатия;
<alg>, <jku>, <jwk>, <kid>, <x5u>, <x5c>, <typ>, <cty>, <crit>: как в JWS (согласно описанию в главе 9 настоящего стандарта), при этом параметры <jku>, <jwk>, <kid>, <x5u>, <x5c> определяют открытый ключ, который был использован при формировании ключа шифрования, получатель может воспользоваться этой информацией, чтобы выбрать соответствующий закрытый ключ.
65. Шифрование выполняется следующим образом:
в соответствии с идентификатором алгоритма шифрования вычислить ключ шифрования содержимого CEK;
если используется алгоритм с шифрованием ключа, зашифровать ключ CEK, положив значением <JWE Encrypted Key> результат шифрования; если алгоритм шифрования не предполагает шифрования ключа, положить значение <JWE Encrypted Key> пустым;
если требуется для алгоритма шифрования, сгенерировать значение случайной синхропосылки <JWE Initialization Vector> необходимой длины; иначе значение <JWE Initialization Vector> должно быть пустое;
если указано значение параметра «zip», положить M – последовательность октетов, представляющих сжатый открытый текст; иначе M – последовательность октетов, представляющих открытый текст;
зашифровать M с помощью алгоритма, который идентифицирован параметрами <alg> и <enc>, с использованием значений ключа CEK, синхропосылки <JWE Initialization Vector> и <JWE AAD>; результат – шифротекст <JWE Ciphertext> и имитовставка <JWE Authentication Tag>.
Расшифрование выполняет получатель JWE обратным преобразованием. Если сообщение зашифровано в адрес нескольких получателей, обрабатывается только один из подходящих заголовков, адресованный получателю. Если проверка целостности дала отрицательный результат, зашифрованное сообщение должно быть отвергнуто.
Глава 11
JWT. JSON СТРУКТУРА КЛЮЧА
66. Параметры структуры JSON Web Key (JWK) представляют свойства ключа, в том числе и значение ключа. Ниже приведена типовая структура ключа, независимо от его типа.
67. В состав JWK входят следующие параметры:
<kty> – (обязательный) тип ключа, определены следующие значения:
«EC» – ключ для криптографического алгоритма на базе эллиптической кривой;
«oct» – последовательность октетов, используемая для представления симметричного ключа;
<use> – (опциональный) предполагаемое использование открытого ключа; определены следующие значения:
«sig» – подпись;
«enc» – шифрование;
<key_ops> – (опциональный) идентифицирует операции, для которых предполагается использовать ключ, определены следующие значения этого параметра:
«sign» – вычисление цифровой подписи или кода аутентификации сообщений;
«verify» – проверка цифровой подписи или кода аутентификации сообщений;
«encrypt» – шифрование контента;
«decrypt» – расшифрование контента и проверка расшифрованного, если возможно;
«wrapKey» – шифрование ключа;
«unwrapKey» – расшифрование ключа и проверка расшифрованного, если возможно;
«deriveKey» – вычисление производного ключа;
«deriveBits» – вычисление производных битов не для использования в качестве ключа;
<alg> – (опциональный) идентифицирует криптографический алгоритм, в котором предполагается использование ключа;
<kid> – (опциональный) идентификатор ключа, используется для того, чтобы выбрать нужный ключ в документе JWK Set;
<x5u>, <x5c>, <x5t>, <x5t#S256>: (опциональные) как в JWS согласно описанию в главе 9 настоящего стандарта.
В зависимости от типа ключа <kty> в состав структуры JWK включаются также другие специфические параметры.
68. JSON-структура набора ключей JWK Set состоит из одного параметра <keys>, который является JSON-массивом ключей в формате JWK.
Документ Key Set, на который указывает значение параметра <jwks_uri> документа Discovery сервера авторизации, содержит ключ(и) проверки подписи сервера авторизации. Он также может содержать открытые ключи, для которых вырабатывается общий ключ шифрования запросов к серверу авторизации. Набор Key Set, на который указывает значение параметра <jwks_uri> метаданных клиента, содержит ключ(и) проверки подписи клиента. Он также может содержать открытые ключи, для которых вырабатывается общий ключ шифрования запросов к клиенту.
Если в наборе Key Set присутствуют как ключи проверки подписи, так и ключи шифрования, в структуре JWK каждого ключа должно быть указано значение параметра <use>. Не допускается использование одного и того же ключа как для целей подписи, так и для шифрования. Параметр JWK <x5c> может использоваться для предоставления ключей в формате сертификата X.509. В этом случае значение открытого ключа также должно присутствовать в составе JWK и совпадать со значением в сертификате.
Глава 12
JWT. СТРУКТУРА JSON ВЕБ-ТОКЕНА
69. JSON веб-токен (JWT) – это набор параметров (claims) в формате JSON-объекта, закодированных в виде структуры JWS или JWE с цифровой подписью, кодом аутентификации и/или шифрованием.
Имена зарегистрированных параметров JWT:
<iss> – (опциональный) идентификатор эмитента JWT (сервера авторизации, выдавшего его);
<sub> – (опциональный) идентификатор субъекта JWT;
<aud> – (опциональный) перечень идентификаторов получателей, которым предназначен JWT;
<exp> – (опциональный) время завершения срока действия JWT в секундах;
<nbf> – (опциональный) время, до которого JWT не должен приниматься к обработке;
<iat> – (опциональный) время выпуска JWT;
<jti> – (опциональный) идентификатор JWT.
Эти параметры JWT помещаются в компоненте JWS Payload или в зашифрованном виде – в содержимое JWE Ciphertext.
70. JWT может быть либо подписан, либо подписан и зашифрован. Если JWT подписан и зашифрован, JSON-документ будет подписан, затем зашифрован, а результатом будет структура вложенного JWT – Nested JWT.
В JOSE-заголовке JWT независимо от типа (JWS или JWE) используются два параметра:
<typ> – (рекомендуется использовать строку «JWT»);
<cty> – при наличии вложенной подписи или шифрования его значением должна быть строка «JWT».
Глава 13
Механизмы защиты.
Цифровая подпись и шифрование
71. В зависимости от способа, с помощью которого отправляются сообщения, целостность сообщения может не гарантироваться, а отправитель сообщения может не проходить проверку подлинности. Чтобы уменьшить эти риски, при обработке значений ID токена, ответа UserInfo, объекта запроса и аутентификации клиента может использоваться JWS для цифровой подписи содержимого этих структур данных. Для обеспечения конфиденциальности сообщений также может использоваться JWE для шифрования содержимого этих структур данных.
Сервер авторизации может объявлять о поддерживаемых им алгоритмах подписи и шифрования в своем документе Discovery или предоставлять эту информацию другими способами. Клиент может декларировать свои алгоритмы цифровой подписи и шифрования в своем запросе динамической регистрации согласно описанию в пункте 46 настоящего стандарта или передавать эту информацию другими способами.
Сервер авторизации может объявлять свои открытые ключи цифровой подписи и шифрования через документ Discovery или предоставлять эту информацию другими способами. Клиент может объявлять свои открытые ключи через запрос динамической регистрации или передавать эту информацию другими способами.
72. Цифровая подпись.
Подписывающая сторона должна выбрать алгоритм цифровой подписи на основе алгоритмов, поддерживаемых получателем.
Ключ асимметричной цифровой подписи – ключ цифровой подписи, который используется для формирования подписи контента, должен быть связан с открытым ключом, используемым для проверки цифровой подписи и опубликованным отправителем в его документе JWK Set. Если в указанном документе JWK Set есть несколько ключей, в JOSE-заголовке должно присутствовать значение параметра <kid>. Параметр <use> соответствующего ключа должен указывать на то, что этот ключ поддерживает алгоритм цифровой подписи («sig»).
Ключ кода аутентификации сообщения – при использовании подписи JWS на основе кода аутентификации сообщения (MAC) значение параметра <alg> JOSE заголовка должно быть равно идентификатору алгоритма MAC. Используемый ключ MAC – это октеты UTF-8 представления значения <client_secret>. Требования к энтропии значений <client_secret> согласно описанию, приведенному в главе 14 настоящего стандарта. Симметричная цифровая подпись не должна использоваться публичными клиентами из-за их неспособности сохранять ключ клиента.
73. Смена асимметричных ключей цифровой подписи.
Смена асимметричных ключей цифровой подписи может быть выполнена с помощью следующего подхода. Подписывающий публикует свои ключи в документе JWK Set, местоположение которого указывает в качестве значения параметра <jwks_uri> документа Discovery, и включает идентификатор ключа цифровой подписи в качестве значения параметра <kid> JOSE-заголовка каждого JWS сообщения, чтобы указать проверяющему, какой ключ должен использоваться для проверки цифровой подписи. Ключи можно обновлять, периодически добавляя новые ключи проверки цифровой подписи в JWK Set по адресу <jwks_uri>. Подписывающий может начать использовать новый ключ цифровой подписи по своему усмотрению, сигнализируя об этом проверяющему, использовав новое значение параметра <kid>. Проверяющий понимает, что, обнаружив незнакомое значение параметра <kid>, он должен обратиться по адресу <jwks_uri> для повторного получения ключей отправителя. Документ JWK Set по адресу <jwks_uri> должен сохранять недавно выведенные из действия ключи проверки цифровой подписи в течение периода времени, соответствующего требованиям к СКЗИ, используемого при реализации криптографической защиты информации в соответствии с требованиями настоящего стандарта.
74. Шифрование.
Отправитель, выполняющий шифрование передаваемой информации, должен выбрать алгоритм шифрования из тех алгоритмов, которые поддерживает получатель. Перечень этих алгоритмов указан в конфигурации сервера авторизации и клиента согласно описанию в пункте 46 настоящего стандарта.
Асимметричное шифрование на основе арифметики эллиптической кривой. Генерируется эфемерный открытый ключ с использованием арифметики эллиптической кривой в качестве элемента <epk> JOSE-заголовка JWE. Второй открытый ключ, используемый для ключевого соглашения (key agreement), должен быть открытым ключом, опубликованным получателем в его документе JWK Set. Если в указанном документе JWK Set есть несколько ключей, в JOSE-заголовке JWE должно быть указано значение параметра <kid>. Для согласования ключа шифрования контента, который будет использован для шифрования подписанного JWT, следует использовать алгоритм ключевого соглашения с использованием арифметики эллиптической кривой. Параметр <use> соответствующего ключа должен включать шифрование («enc»).
Симметричное шифрование. Симметричный ключ шифрования вычисляется из значения <client_secret> с использованием усеченного слева хэш-значения октетов UTF-8 представления параметра <client_secret>. Симметричное шифрование не должно использоваться публичными клиентами из-за их неспособности сохранять ключ клиента.
75. Смена асимметричных ключей шифрования.
При смене ключей шифрования следует использовать процесс, отличный от процесса смены ключей цифровой подписи, поскольку процесс смены открытого ключа получателя запускает получатель, не являющийся отправителем (шифрующим), и, таким образом, отправитель не может полагаться на изменение параметра <kid> в качестве сигнала о необходимости смены ключей. Шифрующий продолжает использовать прежний параметр <kid> в заголовке JWE. При этом он должен выбрать наиболее подходящий ключ из представленных в JWK Set, расположенном по адресу <jwks_uri> получателя. При отсутствии в JWK Set открытого ключа получателя с разрешенным сроком использования шифрование не допускается. Об этом следует сообщить получателю, пользуясь другим надежным каналом связи.
Для смены ключей расшифровывающая сторона своевременно должна опубликовать новые ключи по своему адресу <jwks_uri> и удалить из JWK Set те ключи, которые выводятся из эксплуатации. Должны быть приняты меры по корректному кэшированию <jwks_uri>. Получатель должен удалить отозванные ключи из JWK Set, но сохранять их у себя в течение некоторого периода времени, согласованного с продолжительностью кэша, чтобы обеспечить плавный переход между ключами, предоставляя отправителю некоторое время на загрузку новых ключей. Продолжительность кэша следует также координировать с выдачей новых ключей подписи.
Глава 14
Механизмы защиты.
Требования к энтропии симметричных ключей
76. Ключи формирования MAC JWS и симметричного шифрования JWE вычисляются на основе значения личного ключа клиента <client_secret> согласно описанию в пункте 46 настоящего стандарта. Таким образом, при использовании с симметричными операциями подписи (MAC) или шифрования значения <client_secret> должны содержать достаточную энтропию для генерации криптографически стойких ключей.
77. Значения личного ключа клиента <client_secret> и другая ключевая информация должны генерироваться с помощью СКЗИ, используемого при реализации криптографической защиты информации в соответствии с требованиями настоящего стандарта.
78. Длина значения <client_secret> должна быть не менее той, которая требуется для ключей MAC для конкретного используемого алгоритма. При использовании кода аутентификации HMAC с длиной значения 256 битов значение <client_secret> должно быть не менее 256 битов. При использовании кода аутентификации HMAC с длиной значения 512 битов значение <client_secret> должно быть не менее 512 битов.
Глава 15
Механизмы защиты. Требования к TLS
79. Приложения, применяемые для реализации настоящего стандарта, должны использовать протокол TLS в соответствии с требованиями настоящего стандарта.
Реализация протокола TLS с использованием криптографических алгоритмов Республики Беларусь должна выполняться в соответствии с требованиями СТБ 34.101.65 и настоящего стандарта.
80. Все взаимодействия между клиентом и сервером авторизации, между клиентом и сервером ресурсов, между сервером авторизации и сервером ресурсов должны быть защищены с использованием TLS (HTTPS). Данное требование относится к взаимодействиям в рамках всех указанных в настоящем стандарте протоколов (регистрация клиентов, взаимодействие по протоколам OIDC), ко всем сценариям (с кодом авторизации и гибридный), ко всем режимам доступа к защищаемому ресурсу (только чтение и чтение/запись).
81. Для всех коммуникаций должен использоваться TLS версии 1.2 или более поздней.
82. Должна осуществляться проверка сертификата TLS-сервера.
83. Криптографические ключи, используемые в протоколе TLS, и ключи протокола OIDC должны быть различными.
Сервер авторизации, сервер ресурсов не должны быть доступны без использования TLS. В случае обращения клиента без использования TLS сервер авторизации, сервер ресурсов должны отказать в соединении или возвратить сообщение со статусом HTTP 301 и кодом ошибки «Moved Permanently».
Глава 16
Механизмы защиты. Токен доступа, связанный с MTLS-сертификатом клиента
84. Если клиент использует взаимную аутентификацию по протоколу TLS при подключении к конечной точке токена, сервер авторизации может связать выданный токен доступа с предъявленным сертификатом клиента. Такое связывание достигается путем встраивания хэш-значения сертификата в выданный токен доступа с использованием JWT-синтаксиса согласно описанию в пункте 85 настоящего стандарта или посредством интроспекции токена (запроса информации о токене) у сервера авторизации согласно описанию в пункте 86 настоящего стандарта. Эта привязка может выполняться как совместно с аутентификацией клиента по сертификату MTLS согласно описанию в пунктах 53 и 54 настоящего стандарта, так и отдельно от аутентификации клиента сервером авторизации, что позволяет MTLS во время защищенного доступа к ресурсам служить исключительно механизмом подтверждения владения закрытым ключом.
Чтобы сервер ресурсов мог использовать токены доступа с привязкой к сертификату, он должен заранее знать, что для обращения к защищенным ресурсам должен использоваться MTLS. В частности, сам токен доступа не может использоваться в качестве входных данных для принятия решения о том, запрашивать или нет установление MTLS-соединения.
В процессе доступа к ресурсам, защищенным протоколом TLS с взаимной аутентификацией сторон, клиент может выполнять запросы к защищенным ресурсам, как описано в главе 8 настоящего стандарта, однако эти запросы должны быть выполнены по аутентифицированному MTLS-соединению, используя тот же сертификат, который использовался для MTLS-соединения в конечной точке токена при запросе токена доступа.
Сервер ресурсов должен получить TLS-сертификат клиента, используемый для установления взаимно аутентифицированного TLS-соединения, должен проверить, что сертификат соответствует сертификату, связанному с предъявленным токеном доступа. Если они не совпадают, попытка доступа к ресурсу должна быть отклонена со статусом HTTP 401 и кодом ошибки «invalid_token».
Метаданные, необходимые для того, чтобы сервер и клиент сигнализировали о желании использовать токены доступа с привязкой к MTLS-сертификату клиента, определены в пункте 87 настоящего стандарта.
85. Метод подтверждения отпечатка сертификата с использованием JWT.
Чтобы представить хэш-значение X.509 сертификата в формате JWT согласно описанию в главах 9–12 настоящего стандарта, в качестве значения параметра токена <cnf> используется строка, идентифицирующая метод подтверждения на основе хэш-функции с длиной образа не менее 256 битов, и хэш-значение, которое формируется как base64url кодирование значения хэш-функции, вычисленное от DER-представления (сертификат формата X.509).
Ниже приведен пример функционального содержимого JWT, содержащего подтверждение отпечатка сертификата:
{
"iss": "https://server.example.com",
"sub": "ty.webb@example.com",
"exp": 1493726400,
"nbf": 1493722800,
"cnf":{
"x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2"
}
}
86. Метод подтверждения отпечатка сертификата с использованием интроспекции токена.
Интроспекция токена OAuth 2.0 определяет способ, с помощью которого сервер ресурсов может запрашивать у сервера авторизации информацию о состоянии активности токена доступа, а также другую метаинформацию о токене доступа.
Для токена доступа, связанного с сертификатом MTLS, хэш-значение сертификата, с которым связан токен, передается серверу защищенного ресурса в виде метаинформации в составе ответа интроспекции токена. Хэш-значение передается с использованием того же параметра <cnf> с элементом, идентифицирующим метод подтверждения на основе хэш-функции, что и при использовании метода подтверждения отпечатка сертификата, описанного в пункте 85 настоящего стандарта, в качестве параметра верхнего уровня JSON-ответа интроспекции. Сервер ресурсов сравнивает полученное таким образом хэш-значение сертификата с хэш-значением, вычисленным на основе сертификата клиента, использованного для взаимной аутентификации сеанса TLS, и отклоняет запрос, если они не совпадают.
Ниже приведен пример ответа интроспекции для токена на запрос о состоянии активности с подтверждением отпечатка сертификата:
HTTP/1.1 200 OK
Content-Type: application/json
{
"active": true,
"iss": "https://server.example.com",
"sub": "ty.webb@example.com",
"exp": 1493726400,
"nbf": 1493722800,
"cnf":{
"x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2"
}
}
87. Метаданные сервера авторизации и клиента для подтверждения отпечатка MTLS-сертификата.
Следующий параметр метаданных сервера авторизации, публикуемый в соответствии с требованиями, приведенными в пункте 42 настоящего стандарта, указывает на способность сервера авторизации выдавать токены доступа с привязкой к сертификату:
<tls_client_certificate_bound_access_tokens> – (опциональный) логическое значение, указывающее на поддержку сервером токенов доступа с привязкой к MTLS-сертификату клиента. Значением по умолчанию – «false».
Следующий параметр метаданных клиента, публикуемый в соответствии с требованиями, приведенными в пункте 46 настоящего стандарта, позволяет сигнализировать о намерении клиента использовать токены доступа с привязкой к сертификату:
<tls_client_certificate_bound_access_tokens> – (опциональный) логическое значение, используемое для указания намерения клиента использовать токены доступа, привязанные к MTLS-сертификату клиента. Значением по умолчанию – «false».
Если клиент, который указал намерение использовать токены доступа, привязанные к MTLS-сертификату клиента, отправляет запрос на конечную точку токена по соединению, не являющемуся MTLS, на усмотрение сервера авторизации остается принятие решения относительно того, следует ли возвращать ошибку или выдать токен, не связанный с сертификатом.
Раздел III
Профиль безопасности OpenID API для доступа к сервисам в режиме только для чтения
Глава 17
Положения обеспечения безопасности авторизации
88. В связи с тем, что на основании настоящего стандарта может предоставляться потенциально чувствительная информация, она требует более высокого уровня защиты, чем базовые требования OAuth 2.0.
89. Сервер авторизации:
1) должен поддерживать конфиденциальных клиентов;
2) не должен поддерживать доступ в режиме чтения со стороны публичных клиентов;
3) в случае использования симметричного ключа должен предоставлять личный ключ <client_secret>, соответствующий требованиям, приведенным в главе 14 настоящего стандарта;
4) должен аутентифицировать конфиденциального клиента в конечной точке токена, используя один из следующих методов:
TLS с взаимной аутентификацией сторон взаимодействия протокола OAuth 2.0 и его профилей, включая OIDC, как определено в пунктах 53 или 54 настоящего стандарта;
<client_secret_JWT> или <private_key_JWT>, как определено в пунктах 51 и 52 настоящего стандарта;
5) должен требовать ключ, размер которого составляет 256 бит или больше, если для аутентификации клиента используются алгоритмы, основанные на использовании эллиптической кривой;
6) должен требовать предварительной регистрации URI переадресации клиента;
7) должен требовать наличия параметра <redirect_URI> в запросе аутентификации согласно описанию в пункте 18 настоящего стандарта;
8) должен требовать, чтобы значение параметра <redirect_URI> точно соответствовало одному из предварительно зарегистрированных URI переадресации клиента согласно описанию в пункте 46 настоящего стандарта;
9) должен требовать явного согласия конечного пользователя на авторизацию доступа к запрашиваемой области действия (параметр <scope>), если она не была ранее авторизована;
10) должен исключать повторное использование кодов авторизации в соответствии с рекомендациями, приведенными в пункте 29 настоящего стандарта;
11) должен возвращать ответ с токеном доступа и, если это установлено при разработке сервера авторизации, с токеном обновления;
12) должен возвращать список предоставленных областей действия (параметр <scope>) по выданному токену доступа;
13) должен предоставлять непредсказуемые значения токенов доступа как минимум с 128-битной энтропией; при этом рекомендуется генерировать токены с энтропией не ниже 160 бит;
14) рекомендуется уведомлять владельца ресурса о том, что клиент запрашивает долгосрочное разрешение на доступ согласно описанию в пункте 35 настоящего стандарта;
15) рекомендуется предоставлять конечному пользователю механизм аннулирования токенов доступа и токенов обновления, выданных клиенту согласно описанию в пункте 35 настоящего стандарта;
16) при обращении к методам аутентификации клиента, которые могут передавать идентификатор клиента более чем одним разрешенным способом, в случае предоставления несовпадающих идентификаторов клиента должен возвращать код ошибки «invalid_client»;
17) должен требовать, чтобы сервисы по адресу URI переадресации использовали протокол HTTPS.
90. При предоставлении клиенту в ответе на запрос токена доступа идентификатора аутентифицированного пользователя сервер авторизации должен:
1) поддерживать запрос аутентификации в соответствии с описанием в пункте 18 настоящего стандарта;
2) осуществлять проверку запроса аутентификации в соответствии с пунктом 21 настоящего стандарта;
3) предоставлять ответ на запрос аутентификации в соответствии с пунктами 23 и 25 настоящего стандарта в зависимости от результата аутентификации;
4) осуществлять проверку запроса токена в соответствии с пунктом 28 настоящего стандарта;
5) если параметр <scope> запроса аутентификации включает «openid», генерировать ID токен в составе ответа на запрос токена в соответствии с пунктом 30 настоящего стандарта. При этом значение параметра <sub> должно соответствовать аутентифицированному пользователю.
91. Клиент:
1) может использовать механизмы, определенные в разделе IV настоящего стандарта;
2) должен использовать разные URI переадресации для каждого сервера авторизации, на котором зарегистрирован клиент;
3) должен поддерживать следующие методы аутентификации в конечной точке токена:
TLS с взаимной аутентификацией клиента OAuth, как определено в пунктах 53 и 54 настоящего стандарта;
<client_secret_JWT> или <private_key_JWT>, как определено в пунктах 51 и 52 настоящего стандарта;
4) должен использовать ключи криптографии с эллиптической кривой с минимальным размером 256 бит, если используются криптографические алгоритмы на основе арифметики эллиптической кривой;
5) должен проверять, что значение ключа клиента <client_secret> имеет длину не менее 256 бит, если используется криптография с симметричным ключом.
Если по результатам аутентификации клиент запрашивает получение постоянного идентификатора аутентифицированного клиента, клиент:
должен включать строку «openid» в перечень значений параметра <scope>;
должен включать параметр <nonce> (согласно описанию в пункте 18 настоящего стандарта) в состав запроса аутентификации.
Если строка «openid» не включена в перечень значений параметра <scope>, конфиденциальный клиент должен включать параметр <state> согласно описанию в пункте 18 настоящего стандарта.
Глава 18
Требования к доступу к защищенным ресурсам только для чтения
92. Конечные точки ресурсов возвращают клиенту защищенную информацию владельца ресурса, связанного с предъявленным токеном доступа.
93. Сервер ресурсов, предоставляющий доступ к данным, в соответствии с настоящим стандартом не должен принимать токены доступа в параметрах запроса и должен:
1) поддерживать метод HTTP GET;
2) принимать токены доступа в HTTP заголовке;
3) проверять, что срок действия токена доступа не истек и токен доступа не отозван;
4) проверять, что область действия (параметр <scope>), связанная с предъявленным токеном доступа, разрешает чтение ресурса, который запрашивается;
5) идентифицировать объект, связанный с токеном доступа;
6) возвращать только ресурс, соответствующий объекту, явно указанному в запросе на доступ, и при условии, что доступ к этому ресурсу является допустимым с учетом разрешенной области действия, иначе возвращать ошибку согласно описанию в пункте 25 настоящего стандарта;
7) кодировать ответ в UTF-8;
8) отправлять параметр <Content-Type> HTTP заголовка в виде «Content-Type: application/JSON; charset = UTF-8»;
9) отправлять текущую дату на сервере в HTTP заголовке даты;
10) устанавливать в качестве значения заголовка ответа <x-fapi-interaction-id> либо значение, полученное из соответствующего заголовка запроса клиента, либо значение UUID, если заголовок запроса не предоставлялся для отслеживания взаимодействия, например, «x-fapi-interaction-id: c770aef3-6784-41f7-8e0e-ff5f97bddb3a»;
11) регистрировать значение <x-fapi-interaction-id> в записи журнала регистрации.
94. Клиент, реализующий доступ к защищенному ресурсу в соответствии с требованиями настоящего стандарта:
1) должен отправлять токены доступа в заголовке HTTP в соответствии с пунктом 56 настоящего стандарта;
2) может отправлять последнюю дату регистрации пользователя в клиенте в заголовке <x-fapi-auth-date>, причем значение предоставляется в формате HTTP даты; например, «x-fapi-auth-date: Tue, 11 Sep 2012 19:43:31 GMT»;
3) может отправлять в заголовке <x-fapi-customer-ip-address> IP-адрес пользователя, если эти данные ему доступны; например, «x-fapi-customer-ip-address: 198.51.100.119»;
4) для синхронизации записей журналов регистрации клиента и сервера ресурсов может отправлять серверу заголовок <x-fapi-interaction-id> запроса, значением которого является UUID; например, «x-fapi-interaction-id: c770aef3-6784-41f7-8e0e-ff5f97bddb3a».
Раздел IV
Профиль безопасности OpenID API для доступа к сервисам в режиме чтения и записи
Глава 19
Положения обеспечения безопасности авторизации
95. Доступ для чтения и записи представляет повышенный риск; соответственно, требуемый уровень защиты выше, чем в случае доступа только для чтения.
Настоящий стандарт предписывает выполнение требований, приведенных в пунктах 96–98 настоящего стандарта, при использовании технологии авторизации OAuth 2.0 для защиты API чтения и записи.
96. Сервер авторизации должен поддерживать положения, определенные в пункте 89 настоящего стандарта.
Кроме того, для выполнения операции записи сервер авторизации должен:
1) требовать, чтобы параметр <request> или <request_URI> передавался как токен JWT согласно описанию в главе 12 настоящего стандарта, подписанный в соответствии с JWS согласно описанию в главе 9 настоящего стандарта;
2) требовать в качестве значения параметра <response_type>: «code id_token token»;
3) возвращать ID токен как отдельную подпись (detached signature) ответа на запрос авторизации;
4) если клиент предоставил значение <state>, для защиты этого значения включать в ID токен значение параметра <s_hash> (<s_hash>: параметр ID токена, значение которого равно хэш-значению параметра <state>. Его значение вычисляется как base64url кодирование левой половины значения хэш-функции октетов ASCII представления значения <state>. При этом используется алгоритм хэширования, указанный в параметре <alg> JOSE заголовка ID токена. Значение параметра <s_hash> вычисляет сервер авторизации, а проверяет клиент при получении ID токена). Значение <s_hash> может быть опущено в ID токене, возвращенном из конечной точки токена, когда <s_hash> присутствует в ID токене, возвращенном из конечной точки авторизации;
5) генерировать только код авторизации, токен доступа и токен обновления, которые связаны с владельцем ключа, чей сертификат был предъявлен серверу на этапе установления TLS-соединения;
6) поддерживать механизм подтверждения владения ключом с привязкой токена к MTLS-сертификату согласно описанию в главе 16 настоящего стандарта или с привязкой токенов к TLS-соединению;
7) поддерживать подписанные ID токены;
8) требовать, чтобы все параметры передавались в качестве атрибутов подписанного объекта запроса, передаваемого в параметре <request> или <request_URI>;
9) требовать, чтобы объект запроса (согласно описанию в пункте 20 настоящего стандарта) содержал параметр <exp>;
10) аутентифицировать конфиденциального клиента в конечной точке токена, используя один из следующих методов (в этом случае не используются методы, приведенные в подпункте 4) пункта 89 настоящего стандарта):
TLS с взаимной аутентификацией клиента OAuth, как определено в пунктах 53 или 54 настоящего стандарта;
<private_key_JWT>, как определено в пункте 52 настоящего стандарта.
Кроме того, для выполнения операции записи сервер авторизации может поддерживать конечную точку API для обработки запроса, включающего в качестве своей компоненты <payload> объект запроса, как описано в главе 21 настоящего стандарта, и ему рекомендуется поддерживать подписанные и зашифрованные ID токены.
97. Клиент должен поддерживать положения согласно описанию из пункта 91 настоящего стандарта.
Кроме того, для выполнения операций записи клиент должен:
1) поддерживать механизм подтверждения владения ключом с привязкой токена к MTLS-сертификату согласно описанию в главе 16 настоящего стандарта или с привязкой токена к TLS-соединению.
2) включать в запрос аутентификации параметр <request> или <request_URI> согласно описанию в пункте 20 настоящего стандарта;
3) требовать, чтобы конечные точки возвращали ID токен, подписанный с использованием JWS согласно описанию в главе 12 настоящего стандарта;
4) используя ID токен в качестве отдельной подписи, необходимо проверять, что ответ на запрос авторизации не был подделан;
5) при проверке ID токена проверять значение параметра <state> запроса аутентификации, путем проверки значения параметра <s_hash> согласно описанию в пункте 96 настоящего стандарта;
6) отправлять все параметры в составе подписанного объекта запроса авторизации согласно описанию в пункте 20 настоящего стандарта;
7) дополнительно отправлять дубликаты параметров с использованием синтаксиса запроса OAuth 2.0, когда этого требует спецификация OAuth;
8) требовать, чтобы конечные точки возвращали подписанные с использованием JWS согласно описанию в главе 9 настоящего стандарта и зашифрованные с использованием JWE согласно описанию в главе 10 настоящего стандарта ID токены, необходимые для обеспечения защиты любых персональных данных, содержащихся в ID токене, предоставленном в качестве отдельной подписи в ответе на запрос авторизации.
98. Режим защищенного ответа на запрос авторизации на базе JWT.
В дополнение к положениям, представленным в пункте 96 настоящего стандарта, сервер авторизации может обеспечивать защиту ответов на запрос авторизации клиентов, используя JARM.
JARM позволяет клиенту потребовать от сервера авторизации, чтобы он кодировал ответы на запросы авторизации (любого типа), используя JWT. Это альтернатива использованию ID токенов в качестве отдельных подписей для обеспечения безопасности ответов на запросы авторизации.
Серверу авторизации рекомендуется известить о поддержке режимов ответа JARM, используя параметр метаданных <response_modes_supported>.
В случае использования JARM для защиты ответов на запросы авторизации, действия описанные в подпунктах 2)–4) пункта 96 настоящего стандарта не применяются. Например, клиенты могут использовать JARM в сочетании с типом ответа «code».
Глава 20
Требования к доступу к защищенным ресурсам только для чтения и записи (с использованием токенов)
99. Конечные точки – это конечные точки ресурсов, защищенных с помощью протокола OAuth 2.0, которые возвращают защищенную информацию для владельца ресурса, связанного с предоставленным токеном доступа.
100. Сервер ресурсов должен:
1) поддерживать положения, определенные в пункте 93 настоящего стандарта;
2) поддерживать механизм подтверждения владения ключом с привязкой токена к MTLS-сертификату согласно описанию в главе 16 настоящего стандарта или с привязкой токена к TLS-соединению.
101. Клиенты должны поддерживать положения, определенные в пункте 94 настоящего стандарта.
Глава 21
Конечная точка объекта запроса
102. Вводная информация.
В случае, когда клиент не желает отправлять объект запроса согласно описанию в пункте 20 настоящего стандарта в качестве параметра с передачей его содержимого по значению либо потому что он слишком большой, либо потому что он содержит конфиденциальную информацию, а клиент не хочет шифровать объект запроса, объект запроса может быть отправлен по ссылке с использованием параметра <request_URI>.
В общем случае <request_URI> может быть либо URL, либо URN.
Хотя URI запроса может размещаться на стороне клиента, в спецификации настоящего стандарта он должен размещаться на сервере авторизации. Преимущество сервера авторизации, на котором размещается объект запроса, состоит в том, что он не должен поддерживать исходящие запросы к определенному клиентом URI запроса и не полагается на энтропию URI для обеспечения конфиденциальности объекта запроса.
В случае если объект запроса хранится на сервере авторизации, значением <request_URI> обычно является URN.
В настоящей главе определяются методы, позволяющие конечной точке объекта запроса сервера авторизации осуществлять обмен объектом запроса на URI запроса.
103. Запрос:
1) конечной точкой объекта запроса должен быть RESTful API на сервере авторизации, который принимает подписанный объект запроса как значение компоненты <payload> HTTP-запроса.
2) объект запроса должен подписываться для аутентификации клиента и для подтверждения факта представления клиентом объекта запроса, то есть должно удовлетворять свойству неотказуемости.
104. Успешный ответ:
1) сервер авторизации должен проверить действительность объекта запроса и то, что параметр, идентифицирующий алгоритм подписи, не является пустым, а подпись корректна;
2) если проверка прошла успешно, сервер должен сгенерировать URI запроса и вернуть в составе <payload> JSON-структуры параметры <request_URI.aud.iss> и <exp> с кодом ответа HTTP «201 Created»;
3) во избежание его угадывания значение <request_URI> должно быть сгенерировано с использованием СКЗИ, используемого при реализации криптографической защиты информации в соответствии с требованиями настоящего стандарта. Механизм формирования <request_URI> определяется на этапе разработки сервера авторизации, исходя из его прикладных целей и задач;
4) URI запроса должен быть привязан к идентификатору клиента, который определил объект запроса в виде компоненты <payload> соответствующего запроса;
5) поскольку URI запроса может быть повторно воспроизведен, рекомендуется сделать срок его службы коротким и однократно используемым;
6) значения параметров компоненты <payload> JSON-структуры JWT должны быть следующими:
<request_URI> – URI запрос, соответствующий присланному объекту запроса;
<aud> – JSON-строка, представляющая идентификатор клиента, который послал объект запроса;
<iss> – JSON-строка, представляющая идентификатор отправителя (issuer identifier) сервера авторизации. Если используется OAuth 2.0, значением является URI переадресации. При использовании OpenID Connect значением является значение отправителя (issuer value) сервера авторизации;
<exp> – JSON-число, представляющее время окончания срока жизни URI запроса.
Пример такого ответа:
HTTP/1.1 201 Created
Date: Tue, 2 May 2017 15:22:31 GMT
Content-Type: application/JSON
{
"iss":"https://as.example.com/",
"aud":"s6BhdRkqt3",
"request_URI":"urn:example:MTAyODAK",
"exp":1493738581
}
105. Обработка ошибок. Требуется авторизация.
Если подтверждение достоверности подписи завершилось неудачей, сервер авторизации должен вернуть HTTP ответ с кодом ошибки «401 Unauthorized».
106. Обработка ошибок. Недействительный запрос.
Если полученный объект запроса не прошел успешно структурную/синтаксическую валидацию, сервер авторизации должен вернуть HTTP ответ с кодом ошибки «400 Bad Request».
107. Обработка ошибок. Метод не разрешен.
Если запрос не направлен методом POST, сервер авторизации должен вернуть HTTP ответ с кодом ошибки «405 Method Not Allowed».
108. Обработка ошибок. Длина запроса слишком велика.
Если размер запроса превышает верхнюю границу, допускаемую сервером авторизации, сервер авторизации должен вернуть HTTP ответ с кодом ошибки «413 Request Entity Too Large».
109. Обработка ошибок. Слишком много запросов.
Если число запросов от клиента за период времени превышает границу, допускаемую сервером авторизации, сервер авторизации должен вернуть HTTP ответ с кодом ошибки «429 Too Many Requests».
110. Обработка ошибок. Метаданные обнаружения поставщика OpenID.
Если сервер авторизации имеет конечную точку объекта запроса и поддерживает сервис Discovery, он должен включать в ответы об обнаружении следующий параметр метаданных сервера авторизации:
<request_object_endpoint> – URL конечной точки объекта запроса, на котором клиент может осуществлять обмен объекта запроса на URI запроса.
Раздел V
Защищенный с использованием JWT режим ответа на запрос авторизации для OAuth 2.0 (JARM)
Глава 22
Режим ответа на основе JWT.
Структура данных JWT-ответа
111. JWT согласно описанию в главах 9–12 настоящего стандарта содержит следующие базовые параметры, используемые для обеспечения безопасности передачи:
<iss> – URL сервера авторизации, который создал ответ,
<aud> – <client_id> клиента, для которого предназначен ответ,
<exp> – окончание срока действия JWT.
Кроме того, JWT содержит параметры ответа конечной точки авторизации, определенные для конкретных типов ответов даже в случае ответа об ошибке. Этот шаблон применим ко всем типам ответов. В пунктах 112 и 113 настоящего стандарта иллюстрируется шаблон с типами ответов «code» и «token» соответственно.
В JWT также добавляются дополнительные параметры ответа конечной точки авторизации, определяемые расширениями, например <session_state>.
112. Тип ответа «code».
В случае если разрешение на авторизацию имеет тип «code», JWT содержит параметры <code> и <state>, определенные в пункте 24 настоящего стандарта.
Следующий пример демонстрирует параметры компоненты <payload> токена JWT для успешного значения <code> ответа на запрос авторизации:
{
"iss":"https://accounts.example.com",
"aud":"s6BhdRkqt3",
"exp":1311281970,
"code":"PyyFaux2o7Q0YfXBU32jhw.5FXSQpvr8akv9CeRDSd0QA",
"state":"S8NJ7uqk5fY4EjNvP_G_FtyJu6pUsvH9jsYni9dMAJw"
}
В случае ответа об ошибке JWT будет содержать параметры ответа об ошибке, <error>, <error_description>, <error_URI>, <state>, определенные в пункте 25 настоящего стандарта.
Следующий пример демонстрирует содержимое токена JWT для такого сообщения об ошибке:
{
"error":"access_denied",
"state":"S8NJ7uqk5fY4EjNvP_G_FtyJu6pUsvH9jsYni9dMAJw"
}
113. Тип ответа «token».
В случае если сгенерированное сервером авторизации разрешение, подтверждающее факт авторизации доступа к конфиденциальному ресурсу его владельцем, имеет тип «token», JWT содержит следующие параметры ответа:
<access_token> – токен доступа;
<token_type> – тип токена доступа;
<expires_in> – окончание срока действия токена доступа;
<scope> – область действия, предоставляемая токеном доступа;
<state> – значение состояния, отправленное клиентом в запросе авторизации.
Следующий пример показывает параметры JWT для успешного ответа типа «token» на запрос авторизации:
{
"iss":"https://accounts.example.com",
"aud":"s6BhdRkqt3",
"exp":1311281970,
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"state":"S8NJ7uqk5fY4EjNvP_G_FtyJu6pUsvH9jsYni9dMAJw",
"token_type":"bearer",
"expires_in":"3600",
"scope":"example"
}
В случае ответа об ошибке JWT содержит параметры ответа об ошибке, как в случае типа ответа «code».
Глава 23
Режим ответа на основе JWT.
Цифровая подпись и шифрование
114. JWT может быть либо подписан (JWS), либо подписан и зашифрован (JWS и JWE). Если JWT подписан и зашифрован, JSON документ будет подписан, затем зашифрован, а результатом будет Nested JWT.
115. Сервер авторизации определяет, какой алгоритм использовать для обеспечения защиты JWT для конкретного ответа на запрос авторизации. Это решение может быть основано на зарегистрированных параметрах метаданных для клиента, как определено в главе 26 настоящего стандарта.
Рекомендации по управлению ключами в целом и, в особенности, по использованию симметричных алгоритмов для подписи и шифрования на основе ключа клиента, приведены в главе 13 настоящего стандарта.
Глава 24
Режим ответа на основе JWT. Кодирование ответа
116. Настоящий стандарт определяет следующие значения параметра <response_mode> в составе запроса аутентификации:
«query.jwt»;
«fragment.jwt»;
«form_post.jwt»;
«jwt».
117. Режим ответа «query.jwt» заставляет сервер авторизации отправлять ответ на запрос авторизации в виде HTTP переадресации на URI переадресации (<redirect_URI>) клиента. Сервер авторизации добавляет параметр <response>, содержащий JWT, как определено в главе 22 настоящего стандарта, к компоненту <query> <redirect_URI>, используя формат «application/x-www-form-urlencoded».
Режим ответа «query.jwt» не должен использоваться в сочетании с типами ответов, которые содержат «token» или «id_token», если JWT ответа не зашифрован для предотвращения утечки токена в URL.
Режим ответа «fragment.jwt» заставляет сервер авторизации отправлять ответ на запрос авторизации как HTTP переадресацию на URI переадресации (<redirect_URI>) клиента. Сервер авторизации добавляет параметр <response>, содержащий JWT, как определено в главе 22 настоящего стандарта, к компоненту <fragment> <redirect_URI>, используя формат «application/x-www-form-urlencoded».
Режим ответа «form_post.jwt». Параметр <response>, содержащий JWT, кодируется как значение HTML-формы, которое автоматически передается в агент пользователя и, таким образом, доставляется клиенту с помощью метода HTTP POST, а параметры результата кодируются в теле с использованием формата «application/x-www-form-urlencoded».
Режим ответа «jwt» является ссылкой и указывает на формат включения JWT в URI переадресации по умолчанию (<query> либо <fragment>) для запрошенного типа ответа. Значением по умолчанию для типа ответа «code» является «query.jwt», для типа ответа «token» и других типов ответов, за исключением «none», – «fragment.jwt».
Глава 25
Режим ответа на основе JWT. Правила обработки
118. В случае, если предположить, что клиент хранит на своей стороне состояние сессии, в котором записывается идентификатор сервера авторизации, на который направлен запрос авторизации, и связанная с этим значением информация о браузере (коммуникационном агенте) пользователя.
Клиент должен обрабатывать защищенный с помощью JWT ответ следующим образом:
1) (опционально) клиент расшифровывает JWT, используя ключ, определенный параметром заголовка <kid> полученного JWT. Ключ может быть закрытым ключом, соответствующий открытый ключ которого зарегистрирован ожидаемым отправителем ответа («use:enc» в метаданных клиента <jwks> или <jwks_URI>), или ключом, полученным из ключа клиента согласно описанию в главе 23 настоящего стандарта;
2) клиент получает значение параметра JWT <state> и проверяет его привязку к агенту пользователя. Если проверка не пройдена, клиент должен прервать обработку и отказать в ответе;
3) клиент получает параметр JWT <iss>, проверяет, известно ли ему это значение, и идентифицирует ожидаемого отправителя текущей сессии авторизации. Если проверка не пройдена, клиент должен прервать обработку и отказать в ответе;
4) клиент получает параметр JWT <aud> и проверяет, соответствует ли он идентификатору клиента, который использовал клиент для идентификации себя в соответствующем запросе авторизации. Если проверка не пройдена, клиент должен прервать обработку и отказать в ответе;
5) клиент проверяет параметр JWT <exp>, чтобы определить, действителен ли еще JWT. Если проверка не пройдена, клиент должен прервать обработку и отказать в ответе;
6) клиент получает личный ключ, необходимый для проверки подписи, используя элемент JWT <iss> и элемент заголовка <kid>, после чего проверяет подпись. Если проверка не пройдена, клиент должен прервать обработку и отказать в ответе.
Значение <state> обрабатывается как одноразовый CSRF-токен. Он должен быть объявлен недействительным после осуществления проверки согласно подпункту 2) настоящего пункта.
Получение клиентом личных ключей для проверки подписи JWT согласно подпункту 5) настоящего пункта должно выполняться в соответствии с алгоритмами, приведенными в пункте 73 настоящего стандарта.
119. Пока все проверки не будут успешно пройдены, клиент не должен обрабатывать параметры ответа на запрос авторизации, специфичные для типа разрешения.
Глава 26
Метаданные клиента
Названия параметров следуют шаблону, установленному динамической регистрацией клиентов OpenID Connect согласно описанию в пункте 46 настоящего стандарта для конфигурирования алгоритмов подписи и шифрования JWT ответов в конечной точке UserInfo.
Определены следующие параметры метаданных клиента:
<authorization_signed_response_alg> – алгоритм цифровой подписи JWS согласно описанию в главе 9 настоящего стандарта типа <alg>, который требуется для формирования подписи ответов на запросы авторизации. Если этот параметр определен, ответ будет подписан в соответствии с требованиями JWS согласно описанию в главе 9 настоящего стандарта и сконфигурированного алгоритма. Алгоритм «none» не допускается;
<authorization_encrypted_response_alg> – алгоритм шифрования JWE согласно описанию в главе 10 настоящего стандарта типа <alg>, который требуется для шифрования ответов на запросы авторизации. Если требуются и подписание, и шифрование, ответ будет подписан, затем зашифрован, и результатом будет структура Nested JWT. По умолчанию, если не указано, шифрование не выполняется;
<authorization_encrypted_response_enc> – алгоритм шифрования, который требуется для шифрования ответов на запросы авторизации, если определен <authorization_encrypted_ response_alg>. Если включен <authorization_encrypted_response_enc>, также должен присутствовать и <authorization_encrypted_response_alg>.
120. В процессе регистрации на сервере авторизации клиенты могут давать последнему ссылки на ресурсы хранения своих открытых ключей, используя параметры метаданных <jwks_URI> или <jwks> согласно описанию в пункте 46 настоящего стандарта.
Глава 27
Метаданные сервера авторизации
121. Серверам авторизации рекомендуется публиковать типы поддерживаемых алгоритмов формирования цифровой подписи и шифрования JWT ответа на запрос авторизации, используя параметры метаданных сервера авторизации.
Определены следующие параметры поддерживаемых алгоритмов формирования цифровой подписи и шифрования:
<authorization_signing_alg_values_supported> – (опционально) JSON-массив, содержащий список значений типа <alg> алгоритмов подписи JWS, поддерживаемых конечной точкой авторизации для подписания ответа;
<authorization_encryption_alg_values_supported> – (опционально) JSON-массив, содержащий список значений типа <alg> алгоритмов шифрования JWE, поддерживаемых конечной точкой авторизации для шифрования ответа;
<authorization_encryption_enc_values_supported> – (опционально) JSON-массив, содержащий список значений типа <enc> алгоритмов шифрования JWE, поддерживаемых конечной точкой авторизации для шифрования ответа.
122. Серверам авторизации рекомендуется публиковать значения поддерживаемых режимов ответа с использованием параметра <response_modes_supported>. Настоящий стандарт представляет следующие возможные значения этого параметра:
«query.jwt»;
«fragment.jwt»;
«form_post.jwt»;
«jwt».