BRD Corporate - Account Information Service (AIS) APIs

Some General Remarks Related to this version:

-This API definition is based on the Implementation Guidelines of the Berlin Group PSD2 API. It is not a replacement in any sense. The main specification is (at the moment) always the Implementation Guidelines of the Berlin Group PSD2 API.

-This API definition contains the REST-API for requests from the PISP/AISP to the ASPSP.

Fallback

In case the APIs do not work, we have developed a fallback solution that requires accessing the URL https://tppbck-corp.devbrd.ro. This solution allows web scraping with certificate as in the case of a classic request.

Data Types

The character set is UTF 8 encoded. This specification is only using the basic data elements "string", "boolean", "ISODateTime", "ISODate", "UUID" and "integer" and ISO based code lists (with a byte length of 32 bytes). For codes defined by ISO, a reference to the corresponding ISO standard is given in 13.21.

Max35Text, Max70Text, Max140Text and Max512Text are defining strings with a maximum length of 35, 70, 140 and 512 characters respectively.

ASPSPs will accept for strings at least the following character set:

a b c d e f g h i j k l m n o p q r s t u v w x y z

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

0 1 2 3 4 5 6 7 8 9

/ - ? : ( ) . , ' +

Exceptions from these rules are mentioned for the particular service.

HTTP Response Codes

Response codes follow the standard definitions, for instance:

200 OK / 201 Created / etc.

Addition Information inside the body/ Optional for all responses

The TPP receives a message only in case of an event which is identified as an ERROR or WARNING or INFO (as defined by the Berlin Group).

The PSU should receive a message at least in case of a required action of the PSU (e.g. SCA required).

Case: Creation of a consent / creation of payments)

psuMessage: (string)

“psuMessage”: “text” //:”Max512Text //Additional explaining text

// Sample:

//“Dear customer, please login to your Corporate online banking //application and approve the new consent.”

tppMessages: array of messages

“tppMessages”:[ {

“category”:”String”, // ERROR or WARNING :Max

// 35

“code”: “CERTIFICATE_REVOKED”, // Message code – Mandatory

// String Max 35

“path”:”String” //optional MaxText140

“text”:”Max512Text” //Additional explaining text

//Always English

}]

With Corporate APIs, BRD extends the Messages scope also for pure information only. The category includes also “INFO”, in order to support the TPP for the optimization of the workflows.

Beside the categories ERROR and WARNING the system also generates INFO – Messages.

Sample:

Response creation of a consent for account information:

"tppMessages":

[{"category":"INFO", "code":"TPPMSG_AIS_ACCOUNT_CONSENT_CREATED",

"path":"","text":""}],

Overview

The Account Information APIs for Corporate allow Third Party Providers to request access to Payment Accounts of a BRD-GROUPE SOCIETE GENERALE Corporate user (PSU) on his behalf; with the condition of a valid consent allowing the following operations:

- Transaction reports for a given account including balances if applicable
- Balances of a given account
- A list of available accounts
- Account details of a given account

The Account Information Service is separated in two phases:

1. Establish Account Information Consent

Within this phase of the Account Information Service, the Corporate PSU is giving the consent to the AISP on:

- the type of Account Information Service to grant an access to (see list at the beginning of this section),

- the multiplicity of the Account Information Service, i.e. a one-off or recurring access, and

- in the latter case on the duration of the consent in days or the maximum offered by the ASPSP and optionally the frequency of a recurring request.

The result of this process is a consent resource. A link to this resource is returned to the AISP within this process. The TPP can retrieve the consent object by submitting a GET method on this resource. This object contains a.o. the detailed access rights, the current validity, a Consent-ID token and a message for the client informing/requesting the PSU for approval of the consent in his BRD Corporate application.

The Consent API allows the following request methods: GET, POST and DELETE and the following operations:

- Create consent

- Retrieve consent details

- Retrieve consent status

- Delete consent

2. Read Account Data

Within this phase, the AISP gets access to the account data as defined by the PSU-s consent, see above. The Read Account Data Request is addressing the corresponding consent resource by using the above mentioned link to this resource.

The Read Account Data Request will indicate:

- the type of account data to be accessed,

- the identification of the addressed account, where applicable,

- whether a PSU has directly initiated the request real-time,

- whether balances should be delivered in addition where applicable,

- in case of transaction reports as Account Information type additionally:

- the addressed account identification

- the period of the transaction report

- the preferred formats of the transaction reports.

Basic Rules for establish Account Information Consent:

- One user owns one and only one consent per scope (e.g. AIS) with a TPP.

- All or nothing principle for a new consent.

- More than one valid consent is not allowed . An existing consent will expire as soon as a new consent is created and authorized.

- A consent is only valid for 90 days. The period starts with the approval. The PSU has to renew the approval with strong customer authentication after this time period.

- Max number of usage per day exceeded:

The system distinguishes between two cases: If the PSU is directly involved (active using the TPP interface) the access is unlimited; otherwise the access is restricted to the number of 4 as defined in the consent.

- CombinedService (not supported):

The request will be rejected if the attribute is set to -true-.

- recurringIndicator:

If the request contains the "recurringIndicator" equals -true-, and if a former consent exists for recurring access on account information for the addressed PSU, then the former consent automatically expires as soon as the new consent request is authorized by the PSU.

- One-Off Access:

For a one-off access, the -FrequencyPerDay- attribute is set to "1" and the -recurringIndicator- is set to -false-.

- Permission attributes (implicit permissions):

Please note that a "transactions", "balances" or "accounts" access right also gives access to the generic /accounts endpoints, i.e. is implicitly supporting also the "accounts" access:

GET ../v1/accounts/{query-parameters}

Result: List of accounts {Array of account details}

- We allow only 3 options for the consent initiation:

Option 1: consent request contains a set of accounts inside the body

E.g.
{

"access": {

"balances": [

{"iban": "RO11BRDE111SV11111111111"}

],

"transactions": [

{"iban": "RO11BRDE111SV11111111111","currency": "RON"}

],

"accounts": [

{"iban": "RO11BRDE111SV11111111111","currency": "RON"}

]

},

"recurringIndicator": true,

"validUntil": "2020-09-09",

"frequencyPerDay": 4,

"combinedServiceIndicator":false

}

Option 2: consent request contains no accounts inside the body. Create Account Consent for all accounts (Global consent for all accounts for all account information services).

E.g.
{

"access":

{"allPsd2":"allAccounts"},

"recurringIndicator": true,

"validUntil": "2020-09-30",

"frequencyPerDay": 4,

"combinedServiceIndicator":false

}

Option 3: consent request on Account list without indication of accounts

E.g.

{

"access": {

"availableAccounts": "allAccounts"

},

"recurringIndicator": true,

"validUntil": 2020-09-30,

"frequencyPerDay": 4,

"combinedServiceIndicator":false

}

Strong Customer Authentication (SCA) authorization in a decoupled method

The user follows the instructions and starts the BRD Corporate Online Application, using his credentials for authentication in BRD Corporate Online Application. Based on the reference and information about the TPP, the user is able to identify the consent and approve it.

Note: currently, in Sandbox there is no SCA required.

Please note that the system supports for the authorisation of the consent the implicit authorisation method only. Based on the permissions of the user who is related to the consent it is expected that the user is - beside the initiation of a consent - also able to authorize the consent by himself. A distributed signature procedure is not supported.

If the user who is linked to a consent has no permission rights for the collection of account information, the system will refuse the creation of the consent with Return code 401.

Basic principles for Read Account Data

- Account information/ Balances are defined in JSON.

- Account information will be formatted in JSON.

- Transactions follow one type of formatting rules, either TXT/SWIFT which is indicated by the following

Content-Type:

Content-Type : application/text

and in case of CAMT-based account information :

Content-Type : application/json

- The TPP can indicate the priority of transaction information format using the Accept tag in the HTTP header.

Sample: The TPP creates the following Accept tag with a specified weight, highest priority is application text

Accept: application/text; q=1.0, application/xml; q=0.8

In the response the system indicates the real content type of the delivered information Content-Type = application/text. If the system is not able to offer the text-format the system will deliver the XML instead.

The system does not check the requested content type, so it will not answer with return code 415 in case of requested media types which are not supported by the System.

- It might happen that the account information service was switched at a certain time from TXT to CAMT XML. It depends on the time period of the request for historical information if the system offers either the XML or the TXT format. A mixture of both is not supported. The system will respond with an error in case of a period which contains TXT as well as XML based account information.