Document from CIS Legislation database © 2003-2022 SojuzPravoInform LLC

RESOLUTION OF BOARD OF NATIONAL BANK OF THE REPUBLIC OF BELARUS

of August 26, 2022 No. 314

About approval of standards of carrying out calculations

Based on the paragraph of the sixty sixth 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:

standard of carrying out calculations of SPR 6.02-1-2022 "Banking activity. Information technologies. Open bank API. Payment API. The specification" (is attached);

standard of carrying out calculations of SPR 6.02-2-2022 "Banking activity. Information technologies. Open bank API. Payment API. Information security" (is applied).

2. This resolution becomes effective after its official publication.

Chairman of the board

P.V.Kallaur

 

Approved by the Resolution of Board of National Bank of the Republic of Belarus of August 26, 2022, No. 314

Standard of carrying out calculations of SPR 6.02-1-2022 "Banking activity. Information technologies. Open bank API. Payment API. Specification"

Section I. General provisions

1. This standard of carrying out calculations (further – the standard) establishes requirements to open payment 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 it is provided:

1.1. receipt of information on the bank account (further – the account) (accounts) of the client:

creation and receipt of the status of consent for receipt of information on the account (accounts) of the client;

removal (response) of consent to receipt of information on the account (accounts) of the client;

receipt of information on the account (accounts);

receipt of information on account balance (all accounts);

creation of the account statement and receipt of the account statement on the created statement identifier;

creation of the list of account transactions and receipt of the list of account transactions on the created identifier of the list of transactions;

1.2. initiation of payments:

creation and receipt of the status of consent to initiation of all payment types;

creation and receipt of the status of payment specifying on initiation of payment by the payer for goods, works, services;

creation and receipt of the status of payment specifying on initiation of payment by the payer in the budget;

creation and receipt of the status of payment specifying on initiation of the payment by the payer containing the list of beneficiaries with indication of accounts of beneficiaries;

creation and receipt of the status of payment specifying on initiation of the payment by the payer containing the list of beneficiaries when implementing the translation without opening of the account;

creation and receipt of the status of payment specifying on initiation of payment by the beneficiary for goods, works, services;

creation and receipt of the status of payment specifying on initiation of payment by the beneficiary (claimant) in the budget;

creation and receipt of the status of payment specifying on initiation of payment from structure of recurrent payments;

withdrawal of payment specifying on initiation of all payment types.

2. This standard is intended for participants of ecosystem of open banking for the purpose of realization of processes at development stage of API. This standard does not extend to initiation of payments by means of the program and technical infrastructure intended for acceptance of bank payment cards on the physical carrier.

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, and also the following terms and their determinations are used:

long-term consent – consent which is provided by the client on the party of the supplier of API for implementation of data exchange between the user of API and the supplier of API for the long term (no more than three years);

short-term consent – single consent which is provided by the client on the party of the supplier of API for implementation of data exchange between the user of API and the supplier of API on initiation only of one payment;

idempotence – property of object or transaction in case of repeated application of transaction to object to yield the same result, as in case of the first;

open banking – the complex of approaches to provision of banking services based on easy, convenient, effective, instant and safe way of rendering such services to users including by means of provision to their legal entities, not being the financial organizations, information access about banking services and clients of banks according to the requirements established by the legislation;

pagination – the mechanism of breakdown of the list of records on pages by provision of big data sets through API;

useful load – part of packet of data (message) without office information (without heading, bits of synchronization of other office information);

the user of API of the second type – the legal entity using API for the customer service delivery receiving monetization due to additional services of suppliers of API;

the user of API of the first type – the client who is trading on API and also for receipt of competitive advantages in the course of the subsequent production of goods, performance of works, rendering services (without direct use of API for rendering services to clients);

the supplier of information payment services – the user of API of the second type providing to the client service of receipt of information on the account (accounts) of the client;

the payment service provider of initiation of payment – the user of API of the second type providing to the client service of initiation of money transfer;

recurrent payment – the payment initiated with certain frequency the user of API of the second type based on the consent of the client provided to it by means of use of customer account details;

resource – any essence (payment, the account, transaction) in certain format (JSON or other). Each resource is identified by means of the permanent identifier which does not change in case of change of condition of resource;

consent – the consent of the client to provision of data of the client, the data necessary for carrying out transactions of the client, on initiation of payment of the client to the user of API of the second type from the supplier of API and/or on data transmission to the user of API of the second type to the supplier of API on behalf of the client, API expressed in writing personally to the supplier, or consent provided to the supplier of API in electronic form using the software and hardware and technologies allowing to determine authentically that it proceeds from the corresponding persons;

access token – the certificate representing the authorization issued to the client by the authorization server from approval of the owner of resource. The token of access contains specifying on specific scopes to which access, duration of access and other parameters is resolved;

ecosystem of open banking – the interconnected group of persons, interacting in the course of creation, realization, use and conclusion from operation of open API for achievement of the mutually advantageous purposes, directly open API, and also the software products implemented in case of their use.

In this standard the following designations are used:

About – availability of component and (or) element of data is obligatory;

N – availability of component and (or) element of data is optional;

At – availability of component and (or) element of data is determined by condition;

DELETE – the HTTP method for removal of the specified resource;

GET – the HTTP method for request of content of the specified resource;

HTTPS – extension of the HTTP protocol for support of enciphering for the purpose of increase in safety;

JSON – the text format of data exchange based on JavaScript;

OAuth 2.0 – the open protocol (scheme) of authorization which allows to provide to the user of API limited access to the protected client's resources without need to transfer it (to the user of API) login and the password;

POST – the HTTP method for sending content of the specified resource for the server;

REST – architectural style of interaction of components of the distributed appendix in network. REST represents the approved set of the restrictions considered when designing of the distributed system;

XML – the extensible markup language determining set of rules for coding of documents in format which is convenient for reading by both the person, and the computer.

5. For API the architecture corresponding to the concept of RESTful API is determined.

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

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

8. Participants of ecosystem of open banking interact according to logical structure. The structure of interaction of participants in case of participation of the user of API of the second type is provided in the figure 1.

Figure 1

314-1

The structure of interaction of participants in case of participation of the user of API of the first type is provided in the figure 2.

Figure 2

314-2

9. The client provides long-term consent to the supplier of API for implementation of data exchange between the user of API of the second type and the supplier of API within consent to long term (no more than three years). At any time the client can withdraw long-term consent both through open API, and through the provided means of the supplier of API.

10. The client provides short-term consent to the supplier of API for payment initiation.

11. The supplier of API in case of application of this standard is guided by the bank law, the legislation on information, informatization and information security, on personal data.

Section II. General requirements to API

Chapter 1. Requirements to elements of data

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

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.

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

{m} – precisely m of symbols;

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

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

14. 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. n] – the element of data is obligatory, no more n of times (n> 1) can repeat;

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

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

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

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

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

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

16. 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.

16.1. Element of the data "Name".

The element of the data "Name" (name) shall contain the short bank name, the organizations or surname, own name and middle name (in the presence) of physical person or the name of the described component.

The element of the data "Name" has unstructured type of the data Max140Text.

16.2. Element of the data "International Bank Account Number".

The element of the data "International Bank Account Number" shall conform to requirements of state standard of the Republic of Belarus of STB ISO 13616-1-2015 "Financial services. International bank account number (IBAN). Part 1. Structure of IBAN", the State committee on standardization of the Republic of Belarus approved by the resolution of October 7, 2015 No. 47.

The element of the data "International Bank Account Number" for bank account number opened in participating bank of the BISS system, except for nonresident banks of the Republic of Belarus has type of the data IBAN2007Identifier and format of the fixed length, to equal 28 symbols: [A-Z]{2}[0-9]{2}[A-Z0-9]{4}[0-9]{4}[A-Z0-9]{16}, where:

[A-Z]{2} – the international country code according to the reference book N013 (the table 80);

[0-9] {2} – target figures of bank account number which are used for check of its reliability and are calculated according to STB ISO 13616-1-2015;

[A-Z0-9]{4} – the first four symbols of bank identification code of banks, their branches;

[0-9] {4} – the balance sheet account according to the chart of accounts of financial accounting;

[A-Z0-9]{16} – number of the individual account.

The element of the data "International Bank Account Number" for bank account number opened in nonresident bank of the Republic of Belarus has type of the data IBAN2007Identifier and format: [A-Z]{2}[0-9]{2}[a-zA-Z0-9] {1,30}.

16.3. Element of the data "The Registered BIC Code".

The element of the data "The Registered BIC Code" shall conform to requirements of state standard of the Republic of Belarus of STB ISO 9362-2015 "Banking activity. The messages transferred on communication channels. Business identification codes (BIC)", the State committee on standardization of the Republic of Belarus approved by the resolution of October 7, 2015 No. 47.

The element of the data "The Registered BIC Code" (BICFI) of participating banks of the BISS system has format [A-Z0-9] of {4}[A-Z] {2}[A-Z0-9] {2} ([A-Z0-9]{3})?, where:

[A-Z0-9]{4} – the tsifrobukvenny code which is unambiguously identifying bank of the Republic of Belarus, nonresident bank (prefix of the business participating);

[A-Z]{2} – alphabetic country code according to the reference book N013 (the table 80);

[A-Z0-9]{2} – tsifrobukvenny code of location of the participant of calculations (suffix of the business participating);

[A-Z0-9]{3} – optional categories which may contain value of conditional number of the participant of calculations who is used only for identification of branches.

The element of the data "The Registered BIC Code" (BICFI) of banks not of participants of the BISS system has format [A-Z0-9] of {4}[A-Z] {2}[A-Z0-9] {2} ([A-Z0-9]{3})?.

16.4. The elements of data containing values of the amount, currency, the exchange rate of money and percent.

The elements of data containing values of cash amounts (amount, chargeAmount, balanceAmount, etc.), 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 and shall correspond 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 (further – OKRB 016);

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 (amount, equivalentAmount, balanceEquivalentAmount, etc.), shall have format 0 <=decimal td=18 fd=2.

The elements of data containing values of the exchange rate of currencies (exchangeRate) 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.

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

The elements of data containing values of percent (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 element of the data "Currency" (currency, sourceCurrency, targetCurrency, unitCurrency, etc.) contains currency code value, it is specified according to OKRB 016 (the reference book N 003, the table 80), has type of data CurrencyCode and format of [A-Z] {3}, for example: BYN.

16.5. The elements of data containing values of date and time.

The element of the data "Date" (valueDate, fromBookingDate, toBookingDate, expirationDate, transactionFromDate, transactionToDate, etc.) – 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).

The element of the data "Date and Time" (toBookingDateTime, fromBookingDateTime, creationDateTime, statusUpdateDateTime, etc.) – 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:ss±hh:mm format. For example, for specifying of date and time on March 26, 2021 17 h 19 min. 33 sec. (on the Minsk time): 2021-03-26T17:19:33+03:00.

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±hh:mm format.

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

16.6. Element of the data "Country".

The element of the data "Country" (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 (further – OKRB 017), (the reference book N 013, the table 80), has the structured type of data CountryCode and format of [A-Z] {2}, for example: PL.

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

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

In element of the data "Tax ID number" (taxIdentification) the status of the party 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 party according to the reference book N 061, table 80 (INB, INI, INN, INP, INU, INZ);

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

Chapter 2. Requirements to structure of API

17. 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.

Examples:

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. Headings of requests (headers).

Applicability of attributes of heading depending on method is specified in table 1.

Table 1

Parameter

Determination and rules of use

Method
POST

Method
GET

Method
DELETE

Content-Type

The standard heading HTTP, represents useful load format in request.
Application/json value, except for final points which support Content-Type other than application/json is established.
Application/jose+jwe value for the ciphered requests is established.
If other value is established, then the supplier of API sends the answer: 415 (Unsupported Media Type)

About

Accept

The standard HTTP heading determining type of content which is required from the server.
If the user of API of the second type expects not ciphered answer, then he specifies obviously that only the answer in the JSON format is accepted (transferring application/json value) as content heading for all final points which answer in the JSON format.
If the user of API of the second type expects the ciphered answer, then he specifies obviously that only the reply of JWT is accepted (transferring application/jose+jwe value) as content heading for all final points which answer JSON.
If unacceptable value is established, then the supplier of API sends the answer: 406 (Not Acceptable).
If value is not specified, application/json is by default used

N

N

Authorization

The standard heading HTTP, is used for users of API of the second type.
Allows to provide accounting data to the server of authorization and (or) the server of resources depending on type of required resource.
For OAuth 2.0/OIDC includes Basic or Bearer of the scheme of authentication

About

About

About

x-jws-signature

Specifies that the request is signed by JSON

At

At

At

x-fapi-auth-date

Date of the last authorization in system of the user of API of the second type.
Value is provided in the form of HTTP-date.
[RFC7231]. For example, x-fapi-auth-date: Mon, 26 Aug 2019 0:23:11 PM GMT

N

N

N

x-fapi-customer-ipaddress

The client's IP address if the client is connected to the user of API of the second type at present (in appendix of the user of API of the second type)

N

N

N

x-fapi-interaction-id

RFC4122 UID used as the correlation identifier.
If it is necessary, then the supplier of API transfers back value of the identifier of communication of request and the answer in heading of the answer x-fapi-interaction-id

About

About

About

x-idempotency-key

The unique identifier of request for idempotence support.
It is used for the problem resolution of loss of communication and sending repeated request.
Surely for the POST methods. For other requests it is not specified

N

x-customer-useragent

In heading the type of the device (user-agent) which is used by the client is specified.
The user of API of the second type can fill this field with the device (user-agent) value specified by the client.
If the mobile application of the user of API of the second type is used, the user of API of the second type checks that the device (user-agent) line differs from device (user-agent) line on the basis of the browser

N

N

N

x-api-key

The Apikey identifier generated in system of remote bank servicing (further – SDBO) the supplier of API, and intended for identification and authorization of requests of the user of API of the first type

About

About

About

X-accountConsentId

The identifier of consent within which request is sent. It is intended for identification and authorization of requests for receipt of information on the account (accounts) of the user of API of the first type

N

N

N

19. Attributes of headings of answers are specified in table 2.

Table 2

Parameter

Determination and rules of use

Applicability

Content-Type

Standard parameter of the heading HTTP. Represents format of the useful load returned in the answer
The supplier of API returns the Content-Type value equal to application/json, as heading for all not ciphered final points.
The supplier of API returns the Content-Type value equal to application/jwe, for all ciphered final points

About

Retry-After

The heading parameter specifying time (in seconds) during which the user of API of the second type expects before transaction repeating.
The supplier of API should include this heading together with answers with code of condition of HTTP 429 (Too Many Requests)

N

x-jws-signature

Specifies that the request is signed by JSON

At

x-fapi-interaction-id

RFC4122 UID used as the correlation identifier.
The supplier of API fills the parameter of heading of the answer x-fapi-interaction-id with the value received in the corresponding parameter of heading of request or UID RFC value 4122, if value was not provided in request for interaction tracking

About

20. Status codes of execution of requests.

Status codes of execution of requests of HTTP for various HTTP methods which can be received as a result of work of certain requests are given in table 3. The list of answers is not exhaustive.

Table 3

Status HTTP code

Name

Description

Method
POST

Method
GET

Method
DELETE

200

OK

The request is successfully executed

no

yes

no

201

Created

Transaction of creation is executed successfully. Creation of new resource is result of transaction

yes

no

no

204

No Content

Transaction of removal is successfully complete

no

no

yes

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

yes

yes

yes

401

Unauthorized

The heading of authorization is absent or incorrect token of access.
To transaction it was denied access.
Repeated authentication of the client can lead to creation of the corresponding token of access which can be used

yes

yes

yes

403

Forbidden

The token of access 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 of access which can be used

yes

yes

yes

404

(Not Found)

1. The user of API of the second type tries to receive resource which is specified in the specification, but is not implemented on the party of the supplier of API (for example, the supplier of API decided not to realize final point of API of the status for the internal planned payments).
2. The user of API of the second type tries to receive resource which is not determined.
3. The user of API of the second type tries to receive resource to final points of idempotent resource in the absence of communication

yes

yes

yes

405

Method Not Allowed

The user of API of the second type tried to get access to resource by means of method which is not supported

yes

yes

yes

406

Not Acceptable

The request contained the heading Accept parameter other than the permitted media types, and the character set other than UTF-8

yes

yes

yes

415

Unsupported Media Type

Transaction was rejected as useful load is in the format which is not supported by this method on target resource

yes

no

no

429

Too Many Requests

Transaction was rejected as too much request was made during the certain period of time.
Suppliers of API limit requests if they are made over their policy of bona fide use.
Suppliers of API document the politicians of bona fide use on the portals for developers.
Suppliers of API answer with this status if the amount of requests was in unit of time exceeded.
The supplier of API should include the heading Retry-After in reply specifying how long the user of API of the second type expects before transaction repeating

yes

yes

yes

500

Internal Server Error

Internal error of the server.
In attempt of accomplishment of request for the server there was mistake

yes

yes

yes

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

yes

yes

yes

Chapter 3. General model of data

21. In this Chapter the general top level structure of useful load of requests and answers is described. Detailed structures of requests and answers for the specific API methods are given in appropriate sections of the standard.

21.1. Structure of requests.

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

Request Line

Message Headers

{

"data": {

...

},

"risk": {

...

}

}

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 message 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.

The Section "risk" contains risk indicators for specific request of API provided by the user of API of the second type.

The risk indicators containing in this element can differ for each final point of API.

21.2. Structure of answers.

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

Response Line

Message Headers

{

"data": {

...

},

"risk": {

...

}

"links": {

...

},

"meta": {

...

}

}

Answers join the following additional top level Sections:

links – this block 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 contains metainformation about the page: how many pages in system of pagination and, for example, for transactions, date and time of the first and last account transaction.

According to the principle of RESTful API the complete resource is reproduced as part of the answer.

21.3. In objects, where value for the optional field [0. 1] it is not specified, the field is excluded from useful load of JSON.

For example, the following options are not allowed:

"unstructed": "";

"unstructed": 0;

"unstructed": { };

"unstructed": "null".

In objects where half of the massif it is determined as having values 0. n, half of the massif joins in useful load with the empty massif.

For example, correct option: "balances": [].

21.4. In this standard some models of requests and answers include subject of additional data (Supplementary Data).

This object allows the supplier of API to accept or transfer data which do not enter the structured blocks.

Subject of additional data (Supplementary Data) is determined as empty object of JSON in this standard.

If the supplier of API uses structure with additional data (Supplementary Data), then it spreads the detailed description of structure in the resources. The supplier of API does not use structure of Supplementary Data if the element added there already exists in the structured blocks.

22. The structure of answers with mistakes is specified general for all API methods described in this document.

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

{

"code": "...",

"id": "...",

"message": "...",

"errors": [

{

"errorCode": "...",

"message": "...",

"path": "...",

"url": "..."

}

]

}

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

Table 4

Name

Description

Frequency rate

Type of data /
Format

errorResponse

The massif of detailed codes of errors of messages and URL addresses to documentation for the help in correction

code

High-level error code necessary for classification

[1. 1]

Max40Text
text {1,40}

id

Unique identifier of mistake

[0. 1]

Max40Text
text {1,40}

message

Short description of mistake. For example: "Something not so with the provided request parameters"

[1. 1]

Max500Text
text {1,500}

errors

The massif of mistakes with the description

[1. n]

errorCode

Low-level description of mistake

[1. 1]

errorCode
according to the description in table 5.

message

The disaggregated description of mistake. For example: "The obligatory field is not specified"

[1. 1]

Max500Text
text {1,500}

path

Way to element with mistake in JSON object

[0. 1]

Max500Text
text {1,500}

url

URL for the help in elimination of problem. In this element there can be reference to the web page explaining the correct behavior.
Also through URL it is possible to provide the additional information

[0. 1]

xs:anyURI

22.3. The approximate list of codes of low-level mistakes is provided in table 5 taking into account response code of HTTP.

Table 5

Value

HTTP status

Description

BY.NBRB.Field.Expected

400

If elements are transferred by couple (key value) and value was not transferred. The way to the expected element shall be transferred in the path element (for example, errorResponse. errors.path "accountResponse.data.account.accountDetails.identification"). For example, for admissible value of the schemeName element the corresponding value of the identifier shall be transferred in the identification element

BY.NBRB.Field.Invalid

400

In element unacceptable value or length of the provided value is specified exceeds the corresponding maximum length of element in the domain of the supplier of API. The reference to inadmissible element shall be specified in the path element (for example, errorResponse.errors.path "accountResponse.data.account.accountDetails. schemeName"). The problem shall be in detail described in the error message, the specific element is specified

BY.NBRB.Field.InvalidDate

400

Incorrect date is specified. In the message it is possible to specify urgent problem with date. The reference to inadmissible element shall be specified in the path element

BY.NBRB.Field.Missing

400

The obligatory element is absent. This error code can be used if the mistake is not determined even when checking BY.NBRB.Resource.InvalidFormat. The reference to the absent element shall be specified in the path element

BY.NBRB.Header.Invalid

400

In element of the heading HTTP incorrect value is specified. The element of the heading HTTP shall be specified in the path element

BY.NBRB.Header.Missing

400

The obligatory element of HTTP heading was not provided. The element of the heading HTTP shall be specified in the path element

BY.NBRB.Resource.ConsentMismatch

400

Discrepancy of resources of consent and payment specifying. For example, if the element in the Section "initiation" or "risk" of resource of payment specifying does not match the element of the same name in appropriate section of resource of consent. The path element shall be filled with element of resource of payment specifying which does not correspond to consent

BY.NBRB.Resource.InvalidConsentStatus

400

Consent corresponding to resource is in the incorrect status which would allow to create resource or to execute request. For example, if the resource of consent has the status of AwaitingAuthorisation or Rejected, then the resource cannot be created with such status of consent corresponding to it. The path element shall be filled with consent resource element which is inadmissible

BY.NBRB.Resource.InvalidFormat

400

When the json-scheme of useful load does not correspond to final point. For example, the final point of POST/payments is caused with useful load of JSON which cannot be analysed in class of request of payment specifying

BY.NBRB.Resource.NotFound

400

The resource with the specified identifier does not exist (the resource cannot be processed)

BY.NBRB.Resource.NotCreated

400

The resource with the specified identifier is not created yet and cannot be transferred in the response message. For asynchronous challenges. For example, receipt of the account statement where at first the statement resource is created (the POST/statements/method {accountId}) and in the response message comes the identifier of the created statement resource, but filling of the statement by data of the supplier of API requires some time. Will come respectively this error message

BY.NBRB.Resource.NotCancel

400

The resource cannot be withdrawn

BY.NBRB.Rules.AfterCutOffDateTime

400

The resource of consent or resource of payment specifying is requested after date of cutOffDateTime

BY.NBRB.Signature.Invalid

400

The heading of the signature x-jws-signature was analysed and has the valid heading JOSE meeting specifications, but the signature cannot be checked

BY.NBRB.Signature.InvalidClaim

400

The heading JOSE in the x-jws-signature element has one or several approvals (claim) with unacceptable value (for example, approval of kid which does not accept the certificate). The name of the absent approval shall be transferred in the answer path element about mistake

BY.NBRB.Signature.MissingClaim

400

The heading JOSE in the x-jws-signature element has one or several obligatory approvals which are not specified. The name of the missed approval shall be entered in the answer path element about mistake

BY.NBRB.Signature.Malformed

400

x-jws-signature in heading of request was distorted and could not be analysed as admissible JWS

BY.NBRB.Signature.Missing

400

The request of API assumes x-jws-signature in heading, but the element was absent

BY.NBRB.Unsupported.AccountIdentifier

400

The account ID is not supported for this scheme. The path element contains way to the accountIdentifier element

BY.NBRB.Unsupported.LocalInstrument

400

The specified localInstrument is not supported by the supplier of API. The path element contains way to the localInstrument element. The URL element shall be filled with the reference to documentation of the supplier of API with the list of the supported localInstrument

BY.NBRB.Reauthenticate

403

Processing of request requires repeated authentication of the client

BY.NBRB.Rules.ResourceAlreadyExists

409

The resource with the same parameters already exists

BY.NBRB.UnexpectedError

5khkh

Emergence of unforeseen mistake. The supplier of API shall fill in the message with the detailed description

mistakes, without opening confidential information

The list of low-level text mistakes is not exhaustive and can be added by the supplier of API, using the scheme of numbering of mistakes "BY.NAME_BANK.errorCode".

Example:

{

"code": "400 Bad Request",

"id": "2b5f0fb2-730b-11e8-adc0-fa7ae0ghfsfh",

"message": "Non-valid parameters of request",

"errors": [

{

"errorCode": "BY.NBRB.Resource.ConsentMismatch",

"message": "The initiation elements in paymentConsents and in payments do not match among themselves",

"path": "data.initiation"

}

]

}

23. System of pagination for big json of answers.

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 the first page of records in the links.first element;

total quantity of pages in the meta.totalPages element.

Warning!!!

This is not a full text of document! Document shown in Demo mode!

If you have active License, please Login, or get License for Full Access.

With Full access you can get: full text of document, original text of document in Russian, attachments (if exist) and see History and Statistics of your work.

Get License for Full Access Now

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

Effectively work with search system

Database include more 50000 documents. You can find needed documents using search system. For effective work you can mix any on documents parameters: country, documents type, date range, teams or tags.
More about search system

Get help

If you cannot find the required document, or you do not know where to begin, go to Help section.

In this section, we’ve tried to describe in detail the features and capabilities of the system, as well as the most effective techniques for working with the database.

You also may open the section Frequently asked questions. This section provides answers to questions set by users.

Search engine created by SojuzPravoInform LLC. UI/UX design by Intelliants.