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:

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 call

• must 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.

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

2. If dateFrom parameter is present and dateTo is missing in the incoming request from TPP, then XS2A must check whether SCA has to be triggered or not.

3. If dateFrom parameter is missing and dateTo 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.

4. If both parameters are available in the incoming request and dateTo is before dateFrom 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

  • See OpenAPI XS2A Reference

• Fill in mandatory data

• Execute the request.

• The response should have the HTTP status code: 401 - Unauthorized

  • For 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 the startAuthorisation link from Step 1.

  • See OpenAPI XS2A Reference

• Fill in mandatory data

• Execute the request.

• The response should have the HTTP status code: 201 - Created

  • For 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 the updatePsuAuthentication link from the response in Step 2.

  • See OpenAPI XS2A Reference

• Fill in mandatory data

• Fill in psuData body

• Execute the request.

• The response should have the HTTP status code: 200 - OK

  • For 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 the selectAuthenticationMethod link from the response in Step 3.

  • See OpenAPI XS2A Reference

• Fill in mandatory data

• Fill in authenticationMethodId body

• Execute the request.

• The response should have the HTTP status code: 200 - OK

  • For 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 the authoriseTransaction link from the response in Step 4.

  • See OpenAPI XS2A Reference

• Fill in mandatory data

• 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 - OK

  • For 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 the getTransactionHistory link from the response in Step 5.

  • See OpenAPI XS2A Reference

• Fill in mandatory attributes

• Execute the request.

• The response should have the HTTP status code: 200 - OK

  • For examples of the response payload see XS2A OpenAPI Reference