How to access transactions older than 90 days (from current date)
General Info
According to the EBA regulation https://eba.europa.eu/single-rule-book-qa/-/qna/view/publicId/2018_4177 ASPSP is mandated to trigger SCA when PSU / TPP requests transactions older than 90 days (from the current date).
In order to fulfill this requirement, XS2A offers some special endpoints:
Endpoint | Description |
---|---|
POST | Create authorisation for transactions older than 90 days |
PUT | Update PSU Data for transaction history |
GET | Get Status of the authorisation |
GET | Read transaction list of an account |
Prerequisites
Your TPP certificate must contain the PSP role = PSP_AI.
Get transaction history by authorisationId
You can retrieve a list of transactions that are older than 90 days through /v1/transaction-history/{authorisationId}
by passing a mandatory URL parameter {authorisationId}
.
Given authorisation resource
must exist in XS2A
must have
scaStatus
=finalized
-> SCA must be completed successfully prio to this callmust have
expired
=false
-> you haven't already used this ID for obtaining a transaction list
If these 3 conditions are satisfied, XS2A will return the response with the transaction list equals the response given from the /v2/accounts/{account_id}/transactions
endpoint.
No consentId
is required to access this endpoint because the {authorisationId}
is playing the role of a consent in this case.
Note: this is the custom implementation - Berlin Group doesn't provide any official requirements of the transaction request SCA.
Below are the steps of the embedded authorisation flow to get transactions older than 90 days.
Step 1 - Request transactions older than 90 days through /v1/accounts/{account_id}/transactions endpoint
In this step, a usual get transaction list request is sent to the XS2A account service. Learn more at How to Access Account Balances and Transactions.
XS2A validates the role from the certificate, the syntax, and the dateFrom
parameter.
Validation of dateFrom, dateTo parameters
GET /v1/accounts/{account-id}/transactions?bookingStatus
allows 2 optional query parameters dateFrom
and dateTo
.
If both parameters are not available in the incoming request from TPP, then no SCA is triggered. XS2A returns the transaction list for the maximum allowed period: current date + 90 calendar days.
If
dateFrom
parameter is present anddateTo
is missing in the incoming request from TPP, then XS2A must check whether SCA has to be triggered or not.If
dateFrom
parameter is missing anddateTo
is present in the incoming request from TPP, then no SCA is triggered. XS2A returns the transaction list for the maximum allowed period: current date + 90 calendar days.If both parameters are available in the incoming request and
dateTo
is beforedateFrom
then XS2A rejects such a request.
SCA trigger
SCA must be triggered if the query parameter dateFrom
contains the date, that is equal to or older than (current date - 91 calendar days).
Flow
Go to
/v2/accounts/{account-id}/transactions
Fill in mandatory data
Data field | Value |
---|---|
HTTP-Method |
|
Header | Random UUID for this request |
Header | Learn how to create and authorise consents in XS2A Creation and Authorisation of an AIS Consent in Steps. |
URL path variable | one of |
Query parameter |
|
Query parameter | date that is equal to or older than (current date - 91 calendar days) |
Execute the request.
The response should have the HTTP status code:
401
- UnauthorizedFor examples of the response payload see XS2A OpenAPI Reference
Note: it is possible to request a transaction list directly through /v2/transaction-history-authorisation/{account-id}
endpoint without calling /v1/accounts/{account_id}/transactions
in advance.
Step 2 - Initiate authorisation of access to transaction history
In this step, an authorisation request is sent to XS2A.
XS2A validates the role from the certificate, PSU-ID
and request syntax.
If all the validations have been completed successfully, XS2A returns an authorisationId
.
It means that a transaction history authorisation resource has been created and must be authorised by PSU.
The created resource will be accessible under the given authorisationId
during 30
minutes from the moment of creation. Authorisation must be completed within this time.
If it is not authorised and its validity time is over, access to this resource will be canceled, and the transaction history authorisation flow will be terminated.
Flow
Go to
/v2/transaction-history-authorisation/{account-id}
or follow thestartAuthorisation
link from Step 1.Fill in mandatory data
Data field | Value |
---|---|
HTTP-Method |
|
Header | one of PSU-ID from Sandbox Test Accounts and Test Data |
Header | Random UUID for this request |
URL path variable | Same as Step 1 |
Body parameter | Same as Step 1 |
Body parameter | date that is equal to or older than (current date - 91 calendar days) |
Body parameter | date, that is younger than |
Execute the request.
The response should have the HTTP status code:
201
- CreatedFor examples of the response payload see XS2A OpenAPI Reference
Step 3 - Provide PSU password
In this step, the PSU password must be provided.
Please, use the correspondent password from Sandbox Test Accounts and Test Data.
Flow
Go to
/v1/transaction-history-authorisation/{authorisationId}
or follow theupdatePsuAuthentication
link from the response in Step 2.Fill in mandatory data
Data field | Value |
---|---|
HTTP-Method |
|
Header | Same as Step 2 |
Header | Random UUID for this request |
URL path variable |
|
Fill in
psuData
bodyExecute the request.
The response should have the HTTP status code:
200
- OKFor examples of the response payload see XS2A OpenAPI Reference
Step 4 - Select SCA method
PSU was authenticated successfully with its PSU-ID
and password in the previous step, and now XS2A offers a selection of authentication methods.
An authentication method is a format of the 2nd factor that must be provided by PSU in order to complete the authorisation.
To trigger Decoupled SCA, please use authenticationMethodId
where authenticationType
= PUSH_OTP
in the response in Step 3.
Flow
Go to
/v1/transaction-history-authorisation/{authorisationId}
or follow theselectAuthenticationMethod
link from the response in Step 3.Fill in mandatory data
Data field | Value |
---|---|
HTTP-Method |
|
Header | Same as Step 2 |
Header | Random UUID for this request |
URL path variable |
|
Fill in
authenticationMethodId
bodyExecute the request.
The response should have the HTTP status code:
200
- OKFor examples of the response payload see XS2A OpenAPI Reference
Note: authoriseTransaction
link will only be returned if EMBEDDED
SCA has been chosen.
Step 5 - Provide 2nd factor
This is the step where PSU completes the authorisation through providing the 2nd factor.
In real-life operations, a Bank will generate and send the 2nd factor to PSU.
In the Sandbox, the behaviour of a Bank is simulated: XS2A doesn't generate and sent any challenges but offers a default format of authentication data.
Please, see Sandbox Test Accounts and Test Data.
After successful validation of the 2nd factor and successful completion of the authorisation procedure, XS2A returns a link to the endpoint where transaction history can be requested.
Flow
Go to
/v1/transaction-history-authorisation/{authorisationId}
or follow theauthoriseTransaction
link from the response in Step 4.Fill in mandatory data
Data field | Value |
---|---|
HTTP-Method |
|
Header | Same as Step 2 |
Header | Random UUID for this request |
URL path variable |
|
Fill in
scaAuthenticationData
body, according to the authentication method selected in the previous step. Please, see Sandbox Test Accounts and Test Data.Execute the request.
The response should have the HTTP status code:
200
- OKFor examples of the response payload see XS2A OpenAPI Reference
Step 6 - Get transaction history
This is the final step where requested transaction list can be obtained from XS2A.
You have to use the authorisationId
that has been authorised by PSU only once - each request of transactions that are older than 90 days must be authorised newly.
Flow
Go to
/v1/transaction-history/{authorisationId}
or follow thegetTransactionHistory
link from the response in Step 5.Fill in mandatory attributes
Data field | Value |
---|---|
HTTP-Method |
|
Header | Random UUID for this request |
URL path variable |
|
Execute the request.
The response should have the HTTP status code:
200
- OKFor examples of the response payload see XS2A OpenAPI Reference