Accounts Service - SMBC NextGenPSD2

Transcription

1 Accounts Service - SMBC NextGenPSD2 1.3.SMBC February 2019 Framework (Berlin Group V1.3) Summary OAS3 SMBC offers third party access to accounts (XS2A) in a safe and efficient way using Application Programming Interfaces (APIs) in line with the Berlin Group's NextGenPSD2 Framework Version 1.3. SMBC supports the following NextGenPSD2 services: Consents Accounts Payments Signing-baskets Funds-confirmations SMBC uses an OAuth authentication approach for which the following service is supported: Tokens The NextGenPSD2 framework supports a number of SCA approaches for granting TPPs safe and secure access to accounts as well as SCA approaches for submitting payments. SMBC supports the following approach: Redirect SCA Approach Under our implementation, TPPs will first use our Token service to obtain a TPP Access Token via a Client Credentials Grant Flow which will then be used to create a Consent Resource using our Consents service. The creation of the Consent Resource starts an OAuth Grant Flow resulting in the PSU performing SCA via redirect and the TPP obtaining a PSU Access Token and Refresh Token. PSU Access Tokens are short lived while Refresh Tokens will remain valid for the duration of the requested access (maximum of 90 days). Using a valid PSU Access Token and accompanying Consent-Id, the TPP may make unlimited AISP requests using our Accounts service and may create Payments and read Payment data using our Payments and Signing-baskets services. In addition to holding a valid PSU Access Token, every Payment requires two PSUs to undergo an additional SCA using the Redirect SCA Approach for authorisation. PSUs may provide their authorisation to multiple Payments at once using a Signing-basket.

2 Accounts This document, based on the NextGenPSD2 YAML, which itself is based on the NextGenPSD2 Implementation Guidelines, defines SMBC's Accounts service. In this document we describe which endpoints are supported and the request and response specifications for each. According to the OpenAPI-Specification [ "If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored." The element "Accept" will not be defined in this file at any place. The elements "Content-Type" and "Authorization" are implicitly defined by the OpenApi tags "content" and "security". We omit the definition of all standard HTTP header elements (mandatory/optional/conditional) except they are mention in the Implementation Guidelines. Therefore the implementer might add the in his own realisation of a PSD2 comlient API in addition to the elements define in this file. General Remarks on Data Types The Berlin Group definition of UTF-8 s in context of the PSD2 API have to support at least the following characters 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 / -? : ( )., ' + Space The Berlin Group - A European Standards Initiative - Website Send to The Berlin Group - A European Standards Initiative Creative Commons Attribution 4.0 International Public License Full Documentation of NextGenPSD2 Access to Account Interoperability Framework (General Introduction Paper, Operational Rules, Implementation Guidelines) Servers

3 - SMBC Sandbox PSD2 Project Authorize Accounts Details of accounts GET /berlingroup/v1/accounts Read Account List Read the identifiers of the available payment accounts together with booking balance information, depending on the consent granted. Consent of the PSU to this access must have already been given and stored on the ASPSP system via the Consents serivce. The addressed list of accounts depends then on the PSU ID and the stored consent addressed by consentid, respectively the OAuth2 access token. Returns all identifiers of the accounts, to which an account access has been granted to through the /consents endpoint by the PSU. In addition, relevant information about the accounts and hyperlinks to corresponding account information resources are provided if a related consent has been already granted. Remark: Note that the Query Paramater withbalance is ignored and interimavailable balance is always returned with each account if the consent includes access to balances. Parameters Try it out Name Description X-Requestrequired ID * Consent- ID * required ID of the request, unique to the call, as determined by the initiating party. This then contains the consentid of the related AIS consent, which was performed prior to this payment initiation.

4 Name Description PSU-IP- Address PSU- Device-ID The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. It must be contained if and only if this request was actively initiated by the PSU. UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. It must be contained if and only if this request was actively initiated by the PSU. PSU-IP-Port PSU-Accept The forwarded IP Port header field consists of the corresponding HTTP request IP Port field between PSU and TPP, if available. The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available. PSU- Accept- Charset PSU- Accept- Encoding The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available. The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.

5 Name Description PSU- Accept- Language PSU-User- Agent PSU-Http- Method The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available. The forwarded Agent header field of the HTTP request between PSU and TPP, if available. HTTP method used at the PSU? TPP interface, if available. Valid values are: GET POST PUT PATCH DELETE Available values : GET, POST, PUT, PATCH, DELETE PSU-Geo- Location The forwarded Geo Location of the corresponding http request between PSU and TPP if available. Responses Code Description Links 200 OK No links

6 Code Description Links application/json Controls Accept header. Example Value Schema accountlist List of accounts with details. accounts* accountdetails [ SMBC will give the following for account reference identifiers: iban bban bic entity currency Customers will multiple accounts may use the same IBAN for all their accounts. Therefore when referencing an account using the iban identifier, it must be accompanied with its currency code. resourceid The account may be addressed by the resourceid on the /accounts/account-id endpoint. iban iban pattern: [A-Z]2,2[0-9]2,2[a-zA-Z0-9]1,30 example: FR IBAN of an account bban bban pattern: [a-za-z0-9]1,30 example: BARC Basic Bank Account Number (BBAN) Identifier This data element can be used in the body of the Consent Request Message for retrieving Account access Consent from this Account. This data elements is used for payment Accounts which have no IBAN. ISO20022: Basic Bank

7 Account Number (BBAN). Code Description Links Identifier used nationally by financial institutions, i.e., in individual countries, generally as part of a National Account Numbering Scheme(s), which uniquely identifies the account of a customer. amount* amountvalue currency* currencycode pattern: [A-Z]3 example: EUR ISO 4217 Alpha 3 currency code name maxlength: 35 Name of the account given by the bank or the PSU in online-banking. bic bicfi pattern: [A-Z]6,6[A-Z2-9][A-NP-Z0-9]([A-Z0-9]3,3)0,1 example: AAAADEBBXXX BICFI entity entity maxlength: 35 Title of the account holder, given by the bank in online banking. balances balancelist [ A list of balances regarding this account, e.g. the current balance, the last booked balance. The list might be restricted to the current balance. balance A single balance element balanceamount* amount currency* currencycode pattern: [A-Z] 3 example: EUR ISO 4217 Alpha 3 currency code

8 Code Description pattern: -?[0-9]1,14(\.[0-9]1,3)? example: The amount given with fractional digits, where fractions must be compliant to the currency definition. Up to 14 significant figures. Negative amounts are signed by minus. The decimal separator is a dot. Links Example: Valid representations for EUR with up to two decimals are: balancetype* balancetype The following balance types are defined: "closingbooked": Balance of the account at the end of the pre-agreed account reporting

9 Code Description of the opening booked balance at the beginning of the period and all entries booked to the account during the pre-agreed account reporting period. "openingbooked": Book balance of the account at the beginning of the account reporting period. It always equals the closing book balance from the previous report. "interimavailable": Available balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. "interimbooked": Booked balance calculated at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit Links

10 items during the Code Description calculation Links time/period specified. Enum: referencedate [ interimavailable, closingbooked, openingbooked, interimbooked ] ($date) Reference date of the balance _links ] _linksaccountdetails Links to the account, which can be directly used for retrieving account information from this dedicated account. Links to "balances" and/or "transactions" These links are only supported, when the corresponding consent has been already granted. balances hreftype example: /v1/payments/sepacredittransfers/1234- wertiq-983 Link to a resource transactions hreftype example: /v1/payments/sepa-

11 credit Code Description transfers/1234- wertiq-983 Links Link to a resource ] X-Request-ID ID of the request, unique to the call, as determined by the initiating party. Date Current time in UTC datetime

12 Code Description Links 400 Bad Request No links application/json Example Value Schema Error400_AIS_SMBC Error definition for additional SMBC validation. error* MessageCode400_AIS_SMBC Error attribute defining the type of error encountered. Enum: error_description* [ invalid_request, invalid_client ] ($uri) maxlength: 70 A description of the cause of the error, e.g. a mandatory request header is missing. X-Request-ID ID of the request, unique to the call, as determined by the initiating party.

13 Code Description Links 401 Unauthorized No links application/problem+json Example Value Schema Error401_AIS type* Standardised definition of reporting error information according to [RFC7807] in case of a HTTP error code 401 for AIS. ($uri) maxlength: 70 A NextGenPSD2 URI reference [RFC3986] that identifies the problem type. code* MessageCode401_AIS Message codes defined for AIS for HTTP Error code 401 (UNAUTHORIZED). Enum: [ TOKEN_UNKNOWN, TOKEN_INVALID, TOKEN_EXPIRED ] X-Request-ID ID of the request, unique to the call, as determined by the initiating party.

14 Code Description Links 405 Method Not Allowed No links application/problem+json Example Value Schema Error405_AIS type* Standardised definition of reporting error information according to [RFC7807] in case of a HTTP error code 405 for AIS. ($uri) maxlength: 70 A NextGenPSD2 URI reference [RFC3986] that identifies the problem type. code* MessageCode405_AIS Message codes defined for AIS for HTTP Error code 405 (METHOD NOT ALLOWED). Enum: [ SERVICE_INVALID ] X-Request-ID ID of the request, unique to the call, as determined by the initiating party.

15 Code Description Links 429 Too Many Requests No links X-Request-ID ID of the request, unique to the call, as determined by the initiating party. 500 Internal Server Error No links X-Request-ID ID of the request, unique to the call, as determined by the initiating party. 503 Service Unavailable No links X-Request-ID ID of the request, unique to the call, as determined by the initiating party. GET /berlingroup/v1/accounts/account-id Read Account Details Reads details about an account.consent of the PSU to this access must have already been given and stored on the ASPSP system via the Consents serivce. The addressed details of this account depends then on the stored consent addressed by consentid, respectively the OAuth2 access token. Remark: Note that the Query Paramater withbalance is ignored and interimavailable balance is always returned with the account if the consent includes access to balances.

16 Parameters Try it out Name Description accountid * (path) X-Requestrequired ID * PSU-IP- Address PSU- Device-ID Consent- ID * required required This identification is denoting the addressed account. The account-id is retrieved by using a "Read Account List" call. The account-id is the "id" attribute of the account structure. Its value is constant at least throughout the lifecycle of a given consent. ID of the request, unique to the call, as determined by the initiating party. The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. It must be contained if and only if this request was actively initiated by the PSU. UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. It must be contained if and only if this request was actively initiated by the PSU. This then contains the consentid of the related AIS consent, which was performed prior to this payment initiation. PSU-IP-Port The forwarded IP Port header field consists of the corresponding HTTP request IP Port field between PSU and TPP, if available.

17 Name Description PSU-Accept The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available. PSU- Accept- Charset PSU- Accept- Encoding PSU- Accept- Language PSU-User- Agent The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available. The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available. The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available. The forwarded Agent header field of the HTTP request between PSU and TPP, if available.

18 Name Description PSU-Http- Method HTTP method used at the PSU? TPP interface, if available. Valid values are: GET POST PUT PATCH DELETE Available values : GET, POST, PUT, PATCH, DELETE PSU-Geo- Location The forwarded Geo Location of the corresponding http request between PSU and TPP if available. Responses Code Description Links 200 OK No links application/json Controls Accept header. Example Value Schema accountdetails SMBC will give the following for account reference identifiers: iban bban bic entity currency

19 Code Description Customers will multiple accounts may use the same IBAN for all their Links accounts. Therefore when referencing an account using the iban identifier, it must be accompanied with its currency code. resourceid The account may be addressed by the resourceid on the /accounts/account-id endpoint. iban iban pattern: [A-Z]2,2[0-9]2,2[a-zA-Z0-9]1,30 example: FR IBAN of an account bban bban pattern: [a-za-z0-9]1,30 example: BARC Basic Bank Account Number (BBAN) Identifier This data element can be used in the body of the Consent Request Message for retrieving Account access Consent from this Account. This data elements is used for payment Accounts which have no IBAN. ISO20022: Basic Bank Account Number (BBAN). Identifier used nationally by financial institutions, i.e., in individual countries, generally as part of a National Account Numbering Scheme(s), which uniquely identifies the account of a customer. currency* currencycode pattern: [A-Z]3 example: EUR ISO 4217 Alpha 3 currency code name maxlength: 35 Name of the account given by the bank or the PSU in online-banking. bic bicfi pattern: [A-Z]6,6[A-Z2-9][A-NP-Z0-9]([A-Z0-9]3,3)0,1 example: AAAADEBBXXX BICFI entity entity maxlength: 35 Title of the account holder, given by the bank in online banking. balances balancelist [ A list of balances regarding this account, e.g. the current balance,

20 the last booked balance. The list might be restricted to the current Code Description balance. Links balance A single balance element balanceamount* amount currency* amount* currencycode pattern: [A-Z] 3 example: EUR ISO 4217 Alpha 3 currency code amountvalue pattern: -?[0-9] 1,14(\.[0-9] 1,3)? example: The amount given with fractional digits, where fractions must be compliant to the currency definition. Up to 14 significant figures. Negative amounts are signed by minus. The decimal separator is a dot. Example: Valid representations for EUR with up to two decimals are:

21 Code Description Links balancetype* balancetype The following balance types are defined: Enum: "closingbooked": Balance of the account at the end of the pre-agreed account reporting period. It is the sum of the opening booked balance at the beginning of the period and all entries booked to the account during the pre-agreed account reporting period. "openingbooked": Book balance of the account at the beginning of the account reporting period. It always equals the closing book balance from the previous report. "interimavailable": Available balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. "interimbooked": Booked balance calculated at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. referencedate [ interimavailable, closingbooked, openingbooked, interimbooked ] ($date) Reference date of the balance _links ] _linksaccountdetails

22 Code Description Links to the account, which can be directly used for retrieving account Links information from this dedicated account. Links to "balances" and/or "transactions" These links are only supported, when the corresponding consent has been already granted. balances hreftype example: /v1/payments/sepa-credittransfers/1234-wertiq-983 Link to a resource transactions hreftype example: /v1/payments/sepa-credittransfers/1234-wertiq-983 Link to a resource X-Request-ID ID of the request, unique to the call, as determined by the initiating party. Date Current time in UTC datetime

23 Code Description Links 400 Bad Request No links application/json Example Value Schema Error400_AIS_SMBC Error definition for additional SMBC validation. error* MessageCode400_AIS_SMBC Error attribute defining the type of error encountered. Enum: error_description* [ invalid_request, invalid_client ] ($uri) maxlength: 70 A description of the cause of the error, e.g. a mandatory request header is missing. X-Request-ID ID of the request, unique to the call, as determined by the initiating party.

24 Code Description Links 401 Unauthorized No links application/problem+json Example Value Schema Error401_AIS type* Standardised definition of reporting error information according to [RFC7807] in case of a HTTP error code 401 for AIS. ($uri) maxlength: 70 A NextGenPSD2 URI reference [RFC3986] that identifies the problem type. code* MessageCode401_AIS Message codes defined for AIS for HTTP Error code 401 (UNAUTHORIZED). Enum: [ TOKEN_UNKNOWN, TOKEN_INVALID, TOKEN_EXPIRED ] X-Request-ID ID of the request, unique to the call, as determined by the initiating party.

25 Code Description Links 404 Not found No links application/problem+json Example Value Schema Error404_AIS type* Standardised definition of reporting error information according to [RFC7807] in case of a HTTP error code 404 for AIS. ($uri) maxlength: 70 A NextGenPSD2 URI reference [RFC3986] that identifies the problem type. code* MessageCode404_AIS Message codes defined for AIS for HTTP Error code 404 (NOT FOUND). Enum: [ RESOURCE_UNKNOWN ] X-Request-ID ID of the request, unique to the call, as determined by the initiating party.

26 Code Description Links 405 Method Not Allowed No links application/problem+json Example Value Schema Error405_AIS type* Standardised definition of reporting error information according to [RFC7807] in case of a HTTP error code 405 for AIS. ($uri) maxlength: 70 A NextGenPSD2 URI reference [RFC3986] that identifies the problem type. code* MessageCode405_AIS Message codes defined for AIS for HTTP Error code 405 (METHOD NOT ALLOWED). Enum: [ SERVICE_INVALID ] X-Request-ID ID of the request, unique to the call, as determined by the initiating party.

27 Code Description Links 429 Too Many Requests No links X-Request-ID ID of the request, unique to the call, as determined by the initiating party. 500 Internal Server Error No links X-Request-ID ID of the request, unique to the call, as determined by the initiating party. 503 Service Unavailable No links X-Request-ID ID of the request, unique to the call, as determined by the initiating party. GET /berlingroup/v1/accounts/account-id/balances Read Balance Reads account data from a given account addressed by "account-id". Remark: This account-id can be a tokenised identification due to data protection reason since the path information might be logged on intermediary servers within the ASPSP sphere. This account-id then can be retrieved by the "GET Account List" call. The account-id is constant at least throughout the lifecycle of a given consent.

28 Parameters Try it out Name Description accountid * (path) X-Requestrequired ID * Consent- ID * PSU-IP- Address PSU- Device-ID required required This identification is denoting the addressed account. The account-id is retrieved by using a "Read Account List" call. The account-id is the "id" attribute of the account structure. Its value is constant at least throughout the lifecycle of a given consent. ID of the request, unique to the call, as determined by the initiating party. This then contains the consentid of the related AIS consent, which was performed prior to this payment initiation. The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. It must be contained if and only if this request was actively initiated by the PSU. UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. It must be contained if and only if this request was actively initiated by the PSU. PSU-IP-Port The forwarded IP Port header field consists of the corresponding HTTP request IP Port field between PSU and TPP, if available.

29 Name Description PSU-Accept The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available. PSU- Accept- Charset PSU- Accept- Encoding PSU- Accept- Language PSU-User- Agent The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available. The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available. The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available. The forwarded Agent header field of the HTTP request between PSU and TPP, if available.

30 Name Description PSU-Http- Method HTTP method used at the PSU? TPP interface, if available. Valid values are: GET POST PUT PATCH DELETE Available values : GET, POST, PUT, PATCH, DELETE PSU-Geo- Location The forwarded Geo Location of the corresponding http request between PSU and TPP if available. Responses Code Description Links 200 OK No links application/json Controls Accept header. Example Value Schema readaccountbalanceresponse-200 Body of the response for a successful read balance for an account request. account accountreference Reference to an account using:

31 iban Code Description bban bic Links entity currency iban iban pattern: [A-Z]2,2[0-9]2,2[a-zA-Z0-9] 1,30 example: FR IBAN of an account bban bban pattern: [a-za-z0-9]1,30 example: BARC Basic Bank Account Number (BBAN) Identifier This data element can be used in the body of the Consent Request Message for retrieving Account access Consent from this Account. This data elements is used for payment Accounts which have no IBAN. ISO20022: Basic Bank Account Number (BBAN). Identifier used nationally by financial institutions, i.e., in individual countries, generally as part of a National Account Numbering Scheme(s), which uniquely identifies the account of a customer. currency currencycode pattern: [A-Z]3 example: EUR ISO 4217 Alpha 3 currency code entity entity maxlength: 35 Title of the account holder, given by the bank in online banking. bic bicfi pattern: [A-Z]6,6[A-Z2-9][A-NP-Z0-9]([A- Z0-9]3,3)0,1 example: AAAADEBBXXX BICFI

32 Example: Valid representations for EUR with up to two decimals are: Code Description Links balances* balancelist [ A list of balances regarding this account, e.g. the current balance, the last booked balance. The list might be restricted to the current balance. balance balanceamount* A single balance element amount currency* amount* currencycode pattern: [A-Z] 3 example: EUR ISO 4217 Alpha 3 currency code amountvalue pattern: -?[0-9] 1,14(\.[0-9] 1,3)? example: The amount given with fractional digits, where fractions must be compliant to the currency definition. Up to 14 significant figures. Negative amounts are signed by minus. The decimal separator is a dot.

33 Code Description Links balancetype* balancetype The following balance types are defined: Enum: "closingbooked": Balance of the account at the end of the pre-agreed account reporting period. It is the sum of the opening booked balance at the beginning of the period and all entries booked to the account during the pre-agreed account reporting period. "openingbooked": Book balance of the account at the beginning of the account reporting period. It always equals the closing book balance from the previous report. "interimavailable": Available balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. "interimbooked": Booked balance calculated at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. referencedate [ interimavailable, closingbooked, openingbooked, interimbooked ] ($date) Reference date of the balance

34 Code Description Links ] X-Request-ID ID of the request, unique to the call, as determined by the initiating party. Date Current time in UTC datetime

35 Code Description Links 400 Bad Request No links application/json Example Value Schema Error400_AIS_SMBC Error definition for additional SMBC validation. error* MessageCode400_AIS_SMBC Error attribute defining the type of error encountered. Enum: error_description* [ invalid_request, invalid_client ] ($uri) maxlength: 70 A description of the cause of the error, e.g. a mandatory request header is missing. X-Request-ID ID of the request, unique to the call, as determined by the initiating party.

36 Code Description Links 401 Unauthorized No links application/problem+json Example Value Schema Error401_AIS type* Standardised definition of reporting error information according to [RFC7807] in case of a HTTP error code 401 for AIS. ($uri) maxlength: 70 A NextGenPSD2 URI reference [RFC3986] that identifies the problem type. code* MessageCode401_AIS Message codes defined for AIS for HTTP Error code 401 (UNAUTHORIZED). Enum: [ TOKEN_UNKNOWN, TOKEN_INVALID, TOKEN_EXPIRED ] X-Request-ID ID of the request, unique to the call, as determined by the initiating party.

37 Code Description Links 404 Not found No links application/problem+json Example Value Schema Error404_AIS type* Standardised definition of reporting error information according to [RFC7807] in case of a HTTP error code 404 for AIS. ($uri) maxlength: 70 A NextGenPSD2 URI reference [RFC3986] that identifies the problem type. code* MessageCode404_AIS Message codes defined for AIS for HTTP Error code 404 (NOT FOUND). Enum: [ RESOURCE_UNKNOWN ] X-Request-ID ID of the request, unique to the call, as determined by the initiating party.

38 Code Description Links 405 Method Not Allowed No links application/problem+json Example Value Schema Error405_AIS type* Standardised definition of reporting error information according to [RFC7807] in case of a HTTP error code 405 for AIS. ($uri) maxlength: 70 A NextGenPSD2 URI reference [RFC3986] that identifies the problem type. code* MessageCode405_AIS Message codes defined for AIS for HTTP Error code 405 (METHOD NOT ALLOWED). Enum: [ SERVICE_INVALID ] X-Request-ID ID of the request, unique to the call, as determined by the initiating party.

39 Code Description Links 429 Too Many Requests No links X-Request-ID ID of the request, unique to the call, as determined by the initiating party. 500 Internal Server Error No links X-Request-ID ID of the request, unique to the call, as determined by the initiating party. 503 Service Unavailable No links X-Request-ID ID of the request, unique to the call, as determined by the initiating party. GET /berlingroup/v1/accounts/account-id/transactions Read transaction list of an account Read transaction reports or transaction lists of booked transactions for a given account addressed by "account-id". A maximum of 50 records will be returned accompanied with a "next" link to retrieve further records, sorted in descending order by booking datetime. Optional query parameters "datefrom" and "dateto" may be given to request a period of up to 90 days between today and 730 days ago.

40 Optional query parameter "entryreferencefrom" may be given to request transactions starting with the transaction addressed by "entryreferencefrom" and up to 50 previous transactions. Remark: openingbooked balance will always be returned if the consent includes access to balances. Remark: If dateto is today and the consent includes access to balances, interimavailable and interimbooked balances will be returned otherwise closingbooked balance will be returned. Remark: if datefrom and dateto are not given, only transaction booked today will be returned. Parameters Try it out Name Description account-id * (path) datefrom (query) dateto (query) entryreferencefrom (query) required This identification is denoting the addressed account. The account-id is retrieved by using a "Read Account List" call. The account-id is the "id" attribute of the account structure. Its value is constant at least throughout the lifecycle of a given consent. Conditional: Starting date (inclusive the date datefrom) of the transaction list, mandated if no delta access is required. For booked transactions, the relevant date is the booking date. For pending transactions, the relevant date is the entry date, which may not be transparent neither in this API nor other channels of the ASPSP. End date (inclusive the data dateto) of the transaction list, default is "now" if not given. This data attribute is indicating that the AISP is in favour to get all transactions after the transaction with identification entryreferencefrom alternatively to the above defined period. bookingstatus * required Only "booked" is permitted. Available values : booked (query)

41 Name Description X-Request-ID * Consent-ID * PSU-IP-Address PSU-Device-ID PSU-IP-Port PSU-Accept PSU-Accept-Charset PSU-Accept-Encoding required required ID of the request, unique to the call, as determined by the initiating party. This then contains the consentid of the related AIS consent, which was performed prior to this payment initiation. The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. It must be contained if and only if this request was actively initiated by the PSU. UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. It must be contained if and only if this request was actively initiated by the PSU. The forwarded IP Port header field consists of the corresponding HTTP request IP Port field between PSU and TPP, if available. The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available. The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available. The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.

42 Name Description PSU-Accept-Language PSU-User-Agent PSU-Http-Method The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available. The forwarded Agent header field of the HTTP request between PSU and TPP, if available. HTTP method used at the PSU? TPP interface, if available. Valid values are: GET POST PUT PATCH DELETE Available values : GET, POST, PUT, PATCH, DELETE PSU-Geo-Location The forwarded Geo Location of the corresponding http request between PSU and TPP if available. Responses Code Description 200 OK application/json Controls Accept header. Example Value Schema

43 Code Description transactionsresponse-200_json Body of the JSON response for a successful read transaction list request. This account report contains transactions resulting from the query parameters. account accountreference Reference to an account using: iban bban bic entity currency iban iban pattern: [A-Z]2,2[0-9]2,2[a-zA-Z0-9]1,30 example: FR IBAN of an account bban bban pattern: [a-za-z0-9]1,30 example: BARC Basic Bank Account Number (BBAN) Identifier This data element can be used in the body of the Consent Request Message for retrieving Account access Consent from this Account. This data elements is used for payment Accounts which have no IBAN. ISO20022: Basic Bank Account Number (BBAN). Identifier used nationally by financial institutions, i.e., in individual countries, generally as part of a National Account Numbering Scheme(s), which uniquely identifies the account of a customer. currency currencycode pattern: [A-Z]3 example: EUR ISO 4217 Alpha 3 currency code entity entity maxlength: 35 Title of the account holder, given by the bank in online banking. bic bicfi pattern: [A-Z]6,6[A-Z2-9][A-NP-Z0-9]([A-Z0-9]3,3)0,1 example: AAAADEBBXXX BICFI

44 Code Description transactions accountreport JSON based account report. This account report contains transactions resulting from the query parameters. 'booked' shall be contained if bookingstatus parameter is set to "booked" or "both". booked transactionlist Array of transaction details [ transactiondetails entryreference endtoendid mandateid checkid creditorid Transaction details maxlength: 35 Is the identification of the transaction as used e.g. for reference for the entryreferencefrom query parameter. The same identification as for example used within camt.053 message. maxlength: 35 Unique end to end identity. maxlength: 35 Identification of Mandates, e.g. a SEPA Mandate ID. maxlength: 35 Identification of a Cheque. maxlength: 35 Identification of Creditors, e.g. a SEPA Creditor ID. bookingdate bookingdate ($date) The Date when an entry is posted to an account on the ASPSPs books. valuedate ($date) The Date at which assets become available to the account owner in case of a credit.

45 Code Description transactionamount* amount currency* currencycode pattern: [A-Z] 3 example: EUR ISO 4217 Alpha 3 currency code amount* amountvalue pattern: -?[0-9] 1,14(\.[0-9] 1,3)? example: The amount given with fractional digits, where fractions must be compliant to the currency definition. Up to 14 significant figures. Negative amounts are signed by minus. The decimal separator is a dot. Example: Valid representations for EUR with up to two decimals are: exchangerate exchangeratelist Array of exchange rates [

46 bban bban pattern: [a-za-z0-9]1,30 Code Description exchangerate Exchange Rate sourcecurrency* currencycode pattern: [A-Z] 3 example: EUR ISO 4217 Alpha 3 currency code rate* unitcurrency* targetcurrency* currencycode pattern: [A-Z] 3 example: EUR ISO 4217 Alpha 3 currency code ] creditorname creditorname maxlength: 70 example: Creditor Name Creditor Name creditoraccount accountreference Reference to an account using: iban bban bic entity currency iban iban pattern: [A-Z]2,2[0-9] 2,2[a-zA-Z0-9]1,30 example: FR IBAN of an account

47 Code Description example: BARC Basic Bank Account Number (BBAN) Identifier This data element can be used in the body of the Consent Request Message for retrieving Account access Consent from this Account. This data elements is used for payment Accounts which have no IBAN. ISO20022: Basic Bank Account Number (BBAN). Identifier used nationally by financial institutions, i.e., in individual countries, generally as part of a National Account Numbering Scheme(s), which uniquely identifies the account of a customer. currency currencycode pattern: [A-Z]3 example: EUR ISO 4217 Alpha 3 currency code entity entity maxlength: 35 Title of the account holder, given by the bank in online banking. bic bicfi pattern: [A-Z]6,6[A-Z2-9] [A-NP-Z0-9]([A-Z0-9]3,3) 0,1 example: AAAADEBBXXX BICFI ultimatecreditor ultimatecreditor maxlength: 70 example: Ultimate Creditor

48 Code Description Ultimate Creditor debtorname debtorname maxlength: 70 example: Debtor Name Debtor Name debtoraccount accountreference Reference to an account using: iban bban bic entity currency iban iban pattern: [A-Z]2,2[0-9] 2,2[a-zA-Z0-9]1,30 example: FR IBAN of an account bban bban pattern: [a-za-z0-9]1,30 example: BARC Basic Bank Account Number (BBAN) Identifier This data element can be used in the body of the Consent Request Message for retrieving Account access Consent from this Account. This data elements is used for payment Accounts which have no IBAN. ISO20022: Basic Bank Account Number (BBAN). Identifier used nationally by financial institutions, i.e., in individual countries, generally as part of a National Account Numbering Scheme(s), which uniquely identifies the

49 Code Description account of a customer. currency currencycode pattern: [A-Z]3 example: EUR ISO 4217 Alpha 3 currency code entity entity maxlength: 35 Title of the account holder, given by the bank in online banking. bic bicfi pattern: [A-Z]6,6[A-Z2-9] [A-NP-Z0-9]([A-Z0-9]3,3) 0,1 example: AAAADEBBXXX BICFI ultimatedebtor ultimatedebtor maxlength: 70 example: Ultimate Debtor Ultimate Debtor remittanceinformationunstructured maxlength: 140 remittanceinformationstructured maxlength: 140 Reference as contained in the structured remittance reference structure (without the surrounding XML structure). Different from other places the content is containt in plain form not in form of a structered field. purposecode purposecode ExternalPurpose1Code from ISO Values from ISO External Code List ExternalCodeSets_1Q2018 June Enum: Array [ 286 ] banktransactioncode banktransactioncode

50 amount* amountvalue pattern: -?[0-9]1,14(\.[0-9]1,3)? example: Code Description example: PMNT-RCDT-ESCT Bank transaction code as used by the ASPSP and using the sub elements of this structured code defined by ISO This code type is concatenating the three ISO20022 Codes Domain Code, Family Code, and SubFamiliy Code by hyphens, resulting in DomainCode - FamilyCode - SubFamilyCode. _links* ] _linksaccountreport account* hreftype example: /v1/payments/sepa-credit-transfers/1234- wertiq-983 Link to a resource next hreftype example: /v1/payments/sepa-credit-transfers/1234- wertiq-983 Link to a resource balances balancelist [ A list of balances regarding this account, e.g. the current balance, the last booked balance. The list might be restricted to the current balance. balance balanceamount* A single balance element amount currency* currencycode pattern: [A-Z]3 example: EUR ISO 4217 Alpha 3 currency code

51 Code Description The amount given with fractional digits, where fractions must be compliant to the currency definition. Up to 14 significant figures. Negative amounts are signed by minus. The decimal separator is a dot. Example: Valid representations for EUR with up to two decimals are: balancetype* balancetype The following balance types are defined: "closingbooked": Balance of the account at the end of the preagreed account reporting period. It is the sum of the opening booked balance at the beginning of the period and all entries booked to the account during the pre-agreed account reporting period. "openingbooked": Book balance of the account at the beginning of the account reporting period. It always equals the closing book balance from the previous report. "interimavailable": Available balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. "interimbooked": Booked balance calculated at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. Enum: referencedate [ interimavailable, closingbooked, openingbooked, interimbooked ] ($date) Reference date of the balance ]

52 Code Description X-Request-ID ID of the request, unique to the call, as determined by the initiating party. Date Current time in UTC datetime 400 Bad Request application/json Example Value Schema Error400_AIS_SMBC Error definition for additional SMBC validation. error* MessageCode400_AIS_SMBC Error attribute defining the type of error encountered. Enum: error_description* [ invalid_request, invalid_client ] ($uri) maxlength: 70 A description of the cause of the error, e.g. a mandatory request header is missing. X-Request-ID ID of the request, unique to the call, as determined by the initiating party.

53 Code Description 401 Unauthorized application/problem+json Example Value Schema Error401_AIS type* Standardised definition of reporting error information according to [RFC7807] in case of a HTTP error code 401 for AIS. ($uri) maxlength: 70 A NextGenPSD2 URI reference [RFC3986] that identifies the problem type. code* MessageCode401_AIS Message codes defined for AIS for HTTP Error code 401 (UNAUTHORIZED). Enum: [ TOKEN_UNKNOWN, TOKEN_INVALID, TOKEN_EXPIRED ] X-Request-ID ID of the request, unique to the call, as determined by the initiating party.

54 Code Description 404 Not found application/problem+json Example Value Schema Error404_AIS type* Standardised definition of reporting error information according to [RFC7807] in case of a HTTP error code 404 for AIS. ($uri) maxlength: 70 A NextGenPSD2 URI reference [RFC3986] that identifies the problem type. code* MessageCode404_AIS Message codes defined for AIS for HTTP Error code 404 (NOT FOUND). Enum: [ RESOURCE_UNKNOWN ] X-Request-ID ID of the request, unique to the call, as determined by the initiating party.

55 Code Description 405 Method Not Allowed application/problem+json Example Value Schema Error405_AIS type* Standardised definition of reporting error information according to [RFC7807] in case of a HTTP error code 405 for AIS. ($uri) maxlength: 70 A NextGenPSD2 URI reference [RFC3986] that identifies the problem type. code* MessageCode405_AIS Message codes defined for AIS for HTTP Error code 405 (METHOD NOT ALLOWED). Enum: [ SERVICE_INVALID ] X-Request-ID ID of the request, unique to the call, as determined by the initiating party. 429 Too Many Requests X-Request-ID ID of the request, unique to the call, as determined by the initiating party.

56 Code Description 500 Internal Server Error X-Request-ID ID of the request, unique to the call, as determined by the initiating party. 503 Service Unavailable X-Request-ID ID of the request, unique to the call, as determined by the initiating party. Schemas