RESOLUTION OF BOARD OF NATIONAL BANK OF THE REPUBLIC OF BELARUS

of November 27, 2024 No. 369

About approval of the standard of financial services and technologies

Based on the paragraph of the fifty seventh of Article 26 and part one of article 39 of the Bank code of the Republic of Belarus the Board of National Bank of the Republic of Belarus DECIDES:

1. Approve the standard of financial services and SFUT 6.03-2024 technologies "Open bank API. Information API. The specification" (is attached).

2. This resolution becomes effective in six months after its official publication.

 

Approved by the Resolution of Board of National Bank of the Republic of Belarus of November 27, 2024, No. 369

Standard of financial services and SFUT 6.03-2024 technologies "Open bank API. Information API. Specification"

Section I. General provisions

1. This standard of financial services and technologies (further – the standard) establishes requirements to open information bank interfaces of programming of appendices (the application programming interfaces, API) (further, unless otherwise specified, – API), to methods and the API parameters by means of which information is provided:

about service points of clients of bank (departments, exchange points), ATMs (further – ATM (Automated teller machine), payment and help terminals (further – PST) with indication of the address and operating time, contact telephone numbers, the e-mail address, geolocation and other information;

about the performed banking, payment transactions and the related services (further – services) (attraction of money in deposits (deposits) (further – the deposit), loan granting, issue of bank payment cards (further – BPK), provision of information on the exchange rates on currency exchange transactions (further – currency exchange), attraction of precious metals in deposits, realization of gemstones, commemorative and ingot (investment) coins (further, unless otherwise specified, – coins), carrying out money transfers (electronic money) (further – money), and also other information).

2. This standard is intended for the participants of ecosystem of open banking for the purpose of applications programming providing or using API.

3. This standard is applied jointly with the standard of carrying out calculations of SPR 6.01-2020 "Banking activity. Information technologies. Open bank API. Regulations of interaction of suppliers of API and users of API", the approved resolution of Board of National Bank of the Republic of Belarus of December 31, 2019 No. 552 (further – SPR 6.01).

4. In this standard terms in the values established in the regulatory legal acts of National Bank including accepted together with other state bodies, SPR 6.01, the standard of carrying out calculations of SPR 6.02-1-2022 "Banking activity are used. Information technologies. Open bank API. Payment API. The specification", No. 314 approved by the resolution of Board of National Bank of the Republic of Belarus of August 26, 2022.

5. In this standard designations according to the standard of carrying out calculations of SPR 6.02-1-2022 "Banking activity are used. Information technologies. Open bank API. Payment API. Specification".

6. JSON schemes of the corresponding electronic messages are applied to ensuring structural control of request at the physical level.

7. The text of request shall be created in the code UTF-8 page.

8. The main requirements to information security are described in SPR 6.01.

Section II. General requirements to API

Chapter 1. Requirements to elements of data

9. The symbolical set of elements of data permitted to use includes the following character set:

values of elements of data shall get out of the following character set, put in square brackets []:

A … Z – capital Latin letters;

a … z – lowercase Latin letters;

And … I – capital letters of Cyrillics, including I, Yo and Ў;

and … I – lowercase letters of Cyrillics, including i, yo and ў;

0 … 9 – figures;

/ – + = _.:; """ """ "~! @ # No. of $ % ^? * () [] { } – special graphical symbols: gap, fractional line right and left, hyphen (minus), plus, equally, underscore, point, comma, colon, semicolon, apostrophe, single, pair and angular quotes (left and right), tilde, exclamation mark, commercial at, lattice, number sign, dollar sign, percent, carriages, question mark, asterisk, round, square and braces (left and right).

Decimal numbers are specified in the following format: m <=decimal <= M td=T fd=F, where m – the minimum value, M – the maximum value, T – total quantity of figures, F – the number of figures in fractional part. At the same time the elements of data stated in subitems 14. 8, 14.9, 14.10 and 14.11 Items 14 of this standard, are specified in JSON by the string type.

10. Designations of dimension consist in braces and are specified after transfer of admissible symbols:

{n} – precisely n of symbols;

{ n, m } – is at least, than n of symbols, but no more than m of symbols;

text { n, m } – minimum (n) and the maximum (m) length of text element of data, the permitted character set consisting from;

MaxMText – the maximum (M) length of the text element of data consisting of the permitted character set.

Various values placed in need of one element of data are divided by two fractional lines//.

11. Optional part of value of element of data consists in parentheses after which the question mark is put "?", for example: [A-Z0-9] of {4}[A-Z] {2}[A-Z0-9] {2} ([A-Z0-9]{3})?.

12. For specifying of frequency rate of repeatings (or pluralities) components or elements of data the designations concluded in square brackets are used []:

[1. 1] – the element of data is obligatory, repeatings are not allowed;

[1. *] – the element of data is obligatory, can repeat without restrictions;

[1. m] – the element of data is obligatory, no more m of times (m> 1) can repeat;

[n. *] – the element of data is obligatory, at least n of times (n> 1) shall repeat;

[n. m] – element of data is obligatory, at least n of times of no more m of times (n> 0, of m> n shall repeat);

[0. 1] – the element of data is optional, repeatings are not allowed;

[0. *] – the element of data is optional, can repeat without restrictions;

[0. m] – the element of data is optional, no more m of times (m> 1) can repeat.

If frequency rate of repeating of component or element of data is not specified, then they are filled in once.

13. Types of the elements of the data containing in components of details and used in case of development of information systems:

boolean: the primitive type of data accepting two possible values called by the truth (true) and lie (false). For value the truth can be used 1, for value lie – 0;

decimal: in JSON type of data string (for numerical fields with floating point (according to the description in subitems 14.8-14.11 of Item 14 of this standard);

float: in JSON type of data number;

number: type of the numbers this for designation (for integer values);

string: the line type containing symbols from Item 9 of this standard.

Massif []: the structure of data containing set of values (massif elements).

14. In API basic elements of data and components which format is identical to all API are used if about it it is not specified separately in the description of specific API.

14.1. Element of the data "Name".

The element of the data "Name" shall contain the abbreviated name of bank, other legal entity, or surname, own name, middle name (in the presence) of physical person, the notary, the individual entrepreneur or the name of the described component.

The element of the data "Name" has unstructured type of data of text {1,140}.

14.2. Element of the data "Date".

The element of the data "Date" – the element of data containing value of date is specified according to expanded format of the state standard specification ISO 8601-2001 interstate standard "System of standards according to information, library and to publishing. Representation of dates and time. General requirements", the Committee on standardization, metrology and certification approved by the resolution under Council of Ministers of the Republic of Belarus of August 22, 2002 No. 37 (further – GOST ISO 8601), has type of data ISODate and the YYYY-MM-DD format (year-month-day).

14.3. Element of the data "Date and Time".

The element of the data "Date and Time" – the element of data containing value of date and time is specified according to the state standard specification ISO expanded format 8601, has type of data ISODateTime and the YYYY-MM-DDThh:mm:ssZ or YYYY-MM-DDThh:mm:ss±hh:mm format.

For example, for specifying of date and time on March 26, 2022 of 17 h 19 min. 33 sec. (on the Minsk time) one of options can be used: 2022-03-26T17:19:33Z or 2022-03-26T17:19:33+03:00.

Time is specified taking into account the time zone of the country, in case of the Republic of Belarus GMT+3 is used.

14.4. Element of the data "Time".

The element of the data "Time" – the element of data containing value of time is specified according to the state standard specification ISO format 8601, has type of data ISOTime and the hh:mm:ss format ±hh:mm.

Time is specified taking into account the time zone of the country, in case of the Republic of Belarus GMT+3 is used.

The termination of day is specified in the following type: "11:59:59 PM".

14.5. Element of the data "Country".

The element of the data "Country" is specified in the coded form according to the nation-wide qualifier of the Republic of Belarus to OKRB 017-99 "The countries of the world" approved by the resolution of the State committee on standardization, metrology and certification of the Republic of Belarus of June 16, 1999 No. 8, has the structured type of data CountryCode and format of [A-Z] {2}.

The element of the data "Country" shall be specified by separate element of data in case of identification of nonresidents of the Republic of Belarus.

14.6. Element of the data "Currency".

The element of the data "Currency" contains currency code value, it is specified according to the nation-wide qualifier of the Republic of Belarus to OKRB 016-99 "Currencies" approved by the resolution of the State committee on standardization, metrology and certification of the Republic of Belarus of June 16, 1999 No. 8, has type of data CurrencyCode and format of [A-Z] {3}.

14.7. Element of the data "Tax ID number".

In element of the data "Tax ID number" the status of the partner and accounting number of the payer (further – UNP) appropriated by tax authorities in format [A-Z]{3}[A-Z0-9]{9} where are specified:

[A-Z]{3} – value of the status of the partner according to the reference book of the statuses of subjects N061 in table 125;

[A-Z0-9]{9} – UNP.

14.8. Elements of the data "Width" and "Longitude".

The elements of data containing values of width and longitude shall have the decimal td=8 fd=5 format and be created according to the following rules:

value consists of the whole part, divider and fractional part;

the whole part shall contain at least one figure;

in the whole part zero before the first significant figure are absent;

as divider of the whole and fractional parts there shall be symbol "." (point);

fractional part is specified if it is present at value;

in fractional part zero after the last significant figure are absent;

if fractional part is present at value and is equal to zero, then the quantity of symbols "0" in fractional part shall be to the equally most admissible quantity of signs for the chosen parameter.

14.9. Element of the data "Exchange rate".

The element of data containing values of the exchange rate shall have format 0 <=decimal td=11 fd=10 and be created according to the following rules:

value consists of the whole part, divider and fractional part;

as divider of the whole and fractional parts the symbol is used "." (point);

the total quantity of figures shall not exceed 11, the divider is not considered;

the whole and fractional parts shall contain at least one figure;

in the whole part zero before the first significant figure are absent;

in fractional part zero after the last significant figure are absent.

The exchange rate of Belarusian ruble is specified to unit of this or that currency without use of scale of rate, for example: 0.034537 there corresponds 3,4537 BYN for 100 RUB.

14:10. The elements of data containing values of percent, and "Interest rate".

The elements of data containing values of percent and "Interest rate" shall have format 0 <=decimal <=100 td=11 fd=10 and be created according to the following rules:

value consists of the whole part, divider and fractional part;

as divider of the whole and fractional parts the symbol is used "." (point);

the total quantity of figures shall not exceed 11, the divider is not considered;

the whole and fractional parts shall contain at least one figure;

in the whole part zero before the first significant figure are absent;

in fractional part zero after the last significant figure are absent;

the maximum value shall not exceed 100.

For example: 20.0 corresponds 20 0.05 there corresponds % 0,05.

The additional description for elements of the data "Minimum Remuneration (Payment), % (FeeRateMin)" and "Maximum Remuneration (Payment), % (FeeRateMax)" is provided in table 1.

Table 1

Minimum remuneration (payment), (%) (feeRateMin)	Maximum remuneration (payment), (%) (feeRateMax)	Range of the amounts
no	no	For all amounts
no	is present	From 0 before the maximum remuneration (payment), (including)
is present	no	From the minimum remuneration (payment) (excepting) to the amount exceeding the maximum remuneration (payment)
is present	is present	From the minimum remuneration (payment) (excepting) before the maximum remuneration (payment) (including)

The additional description for elements of the data containing values of percent, and "Interest rate" can be specified in the field of rateFormula type of the data Max140Text text {1,140}.

14:11. The elements of data containing values of the amount, and "Cash amount".

The elements of data containing values of the amounts and "Cash amount" shall have format 0 <=decimal td=18 fd=5 and be created according to the following rules:

value consists of the whole part, divider and fractional part;

as divider of the whole and fractional parts the symbol is used "." (point);

the total quantity of figures shall not exceed 18, the divider is not considered;

the whole part shall contain at least one figure;

in the whole part zero before the first significant figure are absent;

fractional part is specified if it is present at this currency;

the number of figures in fractional part of the amount cannot exceed five, cannot exceed the most admissible number of signs for this currency and there shall correspond to the nation-wide qualifier of the Republic of Belarus OKRB 016-99 "Currencies";

if fractional part is present at this currency and is equal to zero, then the quantity of symbols "0" in fractional part shall be to the equally most admissible quantity of signs in fractional part for this currency, for example: 126.00.

Values of the cash amounts provided in Belarusian rubles shall have format 0 <=decimal td=18 fd=2.

The additional description for elements of the data "Minimum Amount (AmountMin)" and "Maximum Amount (AmountMax)" is provided in table 2.

Table 2

Minimum amount (amountMin)	Maximum amount (amountMax)	Range of cash amounts
no	no	For all amounts
no	is present	From 0 to maximum amount (including)
is present	no	From minimum amount (including) to the amount exceeding maximum
is present	is present	From minimum amount (including) to maximum amount (including)

14:12. Element of the data "Period".

The elements of data containing values of the period of placement of money and the period of payment deferral according to the credit agreement shall have the number type.

The additional description for elements of the data "Minimum Condition (TermMin)" and "Maximum Condition (TermMax)" is provided in table 3.

Table 3

Minimum condition (termMin)	Maximum condition (termMax)	Criteria range
no	no	For the entire periods
no	is present	From 0 to the maximum condition (including)
is present	no	From the minimum condition (excepting) to the term exceeding the maximum condition
is present	is present	From the minimum condition (excepting) to the maximum condition (including)

The additional description for elements of the data "Minimum Period (PeriodMin)" and "Maximum Period (PeriodMax)" is provided in table 4.

Table 4

Minimum period (periodMin)	Maximum period (periodMax)	Range of the periods
no	no	For the entire periods
no	is present	From 0 till the maximum period (including)
is present	no	From the minimum period (excepting) till the period exceeding maximum
is present	is present	From the minimum period (excepting) till the maximum period (including)

Chapter 2. Requirements to structure of API

15. Structure of way of URI.

The way of URI corresponds to the following structure:

[participant-path-prefix]/open-banking / [version] / [resource] / [resource-id] / [sub-resource].

The structure of URI of way consists of the following elements:

[participant-path-prefix] – optional prefix of the supplier of API;

open-banking – permanent open-banking value;

[version] – the version of API expressed in type/v[major-version]. [minor-version]/;

[resource]/[resource-id] – the name of resource and its identifier;

[sub-resource] – the name of subresource (resource of the 2nd level).

The supplier of API uses the same participant-path-prefix and host name for all the resources.

Example:

https://api.bank.by/oapi-channel/open-banking/v1.0/banks/BANKBY2X/deposit.

16. Statuses of execution of requests.

The statuses of execution of requests through API which can be received as a result of work of certain requests are provided in table 5. The list of answers is not exhaustive.

Table 5

Response code	Name	Description
200	OK	The request is successfully executed
400	Bad Request	The request has the incorrect absent or incompatible body of JSON, the URL parameters or header fields. The requested transaction will not be executed
401	Unauthorized	The heading of authorization is absent or incorrect token. To transaction it was denied access. Repeated authentication of the client can lead to creation of the corresponding token which can be used
403	Forbidden	The token has incorrect scope or security policy was broken. To transaction it was denied access. Repeated authentication of the client can lead to creation of the corresponding token which can be used
404	Not Found	Refusal performed by request
406	Not Acceptable	The request contained the heading Accept parameter other than the permitted media types, and the character set other than UTF-8
419	Request Timeout	Waiting time expired
500	Internal Server Error	Internal error of the server. In attempt of accomplishment of request on the server there was mistake
503	Service Unavailable	Obsolete version of the server. If API became outdated and is not supported by the supplier of API any more, its way of URI can still be active and accept requests. In this context it is recommended to return 503 Service Unavailable to notify that the version of API is in offline mode

Chapter 3. Structure of requests and answers

17. Structure of requests.

The structure of the top level for requests of API has the following appearance:

Request Line

Message Headers

{

"data": {

...

}

}

The line of request contains transfer method, way of URI for the appeal to specific request of API and the version of the HTTP.Request Line protocol.

Headings of requests (Message Headers) characterize request body, parameters of transfer and other data.

The Section "data" contains data for specific request of API. The structure of this element differs for each final point of API.

18. Structure of answers.

The supplier of API provides the paginal answer for the GET methods which return multiple records.

The top level structure of replies of API has the following appearance:

Response Line

Message Headers

{

"data": {

...

},

"links": {

...

"self": "",

"next": ""

...

},

"meta": {

...

"totalPages": ""

...

}

}

Answers join the following additional top level Sections:

links – this block is obligatory, contains the reference to the current request and may contain for system of pagination references to the first page, current and on the following page;

meta – this block is obligatory, contains metainformation about the page: how many pages in system of pagination, for example, for the exchange rates, date and time of receipt of information on the last update of the exchange rates.

The supplier of API provides the paginal answer for the GET methods which return multiple records.

If there is the following page of records, then the supplier of API gives the reference to the following page of records in the answer links.next element. Lack of the following link will mean that the current page is the last page of records.

For multipage answers the supplier of API guarantees that the number of records on one page makes at least 25 records (except the last page where there are no records any more) and at most 100 records.

The supplier of API includes "self" the reference to resource in the links.self element.

In addition the supplier of API provides:

the reference to receipt of the remained records in the links.next element;

total quantity of pages in the meta.totalPages element.

This standard does not determine how parameters of browsing of pages are transferred by the supplier of API. Each supplier of API can use own mechanisms for breakdown of the answer. If the initial request from the user of API included filter parameters, then in the answer only those results (broken into pages) which correspond to the filter return.

19. Structure of answers with mistakes.

The structure for answers with mistakes of API has the following appearance:

{

"errorDateTime": "...",

"code": "...",

"id": "...",

"message": "...",

"errors": [

{

"errorCode": "...",

"message": "...",

"path": "...",

"URL": "..."

}

]

}

The description of elements of these answers with mistakes is provided in table 6.

Table 6

Name of element of data	Description of element of data	Frequency rate of element of data	Type of data / format of element of data
errorResponse	The massif of detailed codes of errors of requests and URL addresses to documentation for the help in correction	–	–
errorDateTime	Data on date and time	[1. 1]	ISODateTime According to the description of element of the data "Date and Time" in subitem 14.3 of Item 14 of this standard
code	High-level error code necessary for classification	[1. 1]	Max40Text text {1,40}

Disclaimer! This text was translated by AI translator and is not a valid juridical document. No warranty. No claim. More info