Skip to main content

13. How to access transactions older than 90 days (from current date)

  • Updated

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 current date).

In order to fulfill this requirement XS2A offers 2 special endpoints

  • /v1/transaction-history/{authorisationId}: to get list of transactions by authorisationId after successful SCA.
  • /v1/transaction-history-authorisation/{accountId}/{bookingStatus}/{dateFrom}/{dateTo}?withBalances: to create authorisationId and execute SCA.

Prerequisites

Your TPP certificate must contain the PSP role = PSP_PI.

Get transaction history by authorisationId

You can retrieve a list of transactions that are older than 90 days through /v1/transaction-history by passing a mandatory 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 /v1/accounts/{account_id}/transactions endpoint.

No consentId is required to access this endpoint because {authorisationId} is playing the role of a consent in this case.

Method: GET

Attribute

Type

Condition

Location

Description

X-Request-Id

UUID

mandatory

header

Unique identifier of a request as determined by sending party

authorisationId

string

mandatory

path

Unique identifier of a transaction history authorisationId resource in XS2A

Note: this is the custom implementation - Berlin Group doesn't provide any official requirements of the transaction request SCA.

Authorisation of access to transactions older than 90 days (transaction history)

Authorisation is done through the dedicated endpoint /v1/transaction-history-authorisation/{accountId}/{bookingStatus}/{dateFrom}/{dateTo}?withBalances.

No consentId is required to access this endpoint because PSU is directly involved in the authorisation process and no user-sensitive data is given to TPP.

Note: this is the custom implementation - Berlin Group doesn't provide any official requirements of the transaction request SCA.

Method: POST, PUT

Attribute

Type

Condition

Location

Description

X-Request-Id

UUID

mandatory

header

Unique identifier of a request as determined by sending party

PSU-ID

string

mandatory

header

Unique identifier of a PSU in ASPSP

accountId

string

mandatory

path

Unique identifier of an account resource in ASPSP

bookingStatus

string

mandatory

path

Permitted codes are

·        "booked"

·        "pending"

·        "both"

dateFrom

ISODate

mandatory

path

Starting date (inclusive the date dateFrom) of the transaction list

dateTo

ISODate

mandatory

path

End date (inclusive the date dateTo) of the transaction list

withBalances

boolean

optional

query

If contained, this function reads the list of transactions including the booking balance,

if granted by the PSU in the related consent and available by the ASPSP.

If not given, default = "false"

Below are the steps of the embedded authorisation flow.

Step 1 Request transactions older than 90 days through /v1/accounts/{account_id}/transactions endpoint

On this step a usual get transaction list request is sent to XS2A account service. Learn more at 05. 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 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 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 query parameter "dateFrom" contains the date that is equal to or older than (current date - 91 calendar days).

Request

  1. Go to /v1/accounts/{account-id}/transactions
  2. Fill in mandatory data
  3. Execute the request.

Response

HTTP status code: 401 Unauthorized

Example

{"tppMessages": [{
"category": "ERROR",
"code": "UNAUTHORIZED",
"text": "Access to transactions older than 90 days must be authorized by PSU."
}],
"_links": {"startAuthorisation": "/v1/transaction-history-authorisation/{accountId}/{bookingStatus}/{dateFrom}/{dateTo}"
}

Note: it is possible to request transaction list directly through transaction-history-authorisation endpoint without calling /v1/accounts/{account_id}/transactions in advance.

XS2A triggers SCA flow - embedded or decoupled, and returns requested transaction list after SCA has been completed successfully.

Step 2 Initiate authorisation of access to transaction history

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

Created resource will be accessible under 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 the access to this resource will be cancelled and transaction history authorisation flow will be terminated.

Request

  1. Go to /v1/transaction-history-authorisation/{accountId}/{bookingStatus}/{dateFrom}/{dateTo} or follow the "startAuthorisation" link from the Step 1. 
  2. Fill in mandatory data
  3. Execute the request.

Response

HTTP status code: 201 Created

Example

{ "scaStatus": "received",
"_links": "updatePsuAuthentication": "/v1/transaction-history-authorisation/{authorisationId}"}
}

 

Step 3 Provide PSU password

On this step PSU password must be provided.

Please, use correspondent password from 09. Sandbox Test Accounts and Test Data.

Request

  1. Go to /v1/transaction-history-authorisation/{authorisationId} or follow the "updatePsuAuthentication" link from the response in Step 2.
  2. Fill in mandatory data
    • Method: PUT
    • PSU-ID: same as in Step 1
    • X-Request-ID: valid UUID
    • authorisationId:authorisationId received in response in Step 2
  3. Fill in psuData
Example

{
"psuData": {"password": "string"}
}
  1. Execute the request.

Response

HTTP status code: 200 Ok

Example

{
"scaStatus": "psuAuthenticated",
"scaMethods": [
{
"authenticationType": "SMS_OTP",
"authenticationMethodId": "sms"
},
{
"authenticationType": "CHIP_OTP",
"authenticationMethodId": "chip"
},
{
"authenticationType": "PUSH_OTP",
"authenticationMethodId": "push"
}
],
"_links": {"selectAuthenticationMethod": "/v1/transaction-history-authorisation/{authorisationId}"}
}

 

Step 4 Select SCA method

PSU was authenticated successfully with its PSU-ID and password in the previous step and now XS2A offers 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 the Step 3.

Request

  1. Go to /v1/transaction-history-authorisation/{authorisationId} or follow the "selectAuthenticationMethod" link from the response in Step 3.
  2. Fill in mandatory data
    • Method: PUT
    • PSU-ID: same as in Step 2
    • X-Request-ID: valid UUID
    • authorisationId:authorisationId received in response in Step 2
  3. Fill in authenticationMethodId 
Example

{
"authenticationMethodId": "chip"
}
  1. Execute the request.

Response

HTTP status code: 200 Ok

Note: "authoriseTransaction" link will only be returned if EMBEDDED SCA has been chosen.

Example

{
"scaStatus": "scaMethodSelected",
"chosenScaMethod": {
"authenticationType": "CHIP_OTP",
"authenticationMethodId": "chip"
},
"_links": {"scaStatus": "/v1/consents/{consentId}/authorisations/{authorisationId}",
"authoriseTransaction": "/v1/consents/{consentId}/authorisations/{authorisationId}"}
}

 

Step 5 Provide 2nd factor

This is the step where PSU completes the authorisation through providing the 2nd factor.

In real-live 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 default format of authentication data. Please, see 09. 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.

Request

  1. Go to /v1/transaction-history-authorisation/{authorisationId} or follow the "authoriseTransaction" link from the response in Step 4.
  2. Fill in mandatory attributes
    • Method: PUT
    • PSU-ID: same as in Step 2
    • X-Request-ID: valid UUID
    • authorisationId:authorisationId received in response in Step 2
  3. Fill in scaAuthenticationData according to the authentication method selected in the previous step. Please, see 09. Sandbox Test Accounts and Test Data.
Example

{ "scaAuthenticationData": "string" }
  1. Execute the request.

Response

HTTP status code: 200 Ok

Example

{
"_links": {"getTransactionHistory": "/v1/transaction-history/{authorisationId}"}
}

 

Step 6 Get transaction history

This is the final step where requested transaction list can be obtained from XS2A.

You can use the authorisationId that has been authorised by PSU only once - each request of transactions that are older than 90 days must be authorized newly.

Request

  1. Go to /v1/transaction-history/{authorisationId} or follow the "getTransactionHistory" link from the response in Step 5.
  2. Fill in mandatory attributes
    • Method: GET
    • X-Request-ID: valid UUID
    • authorisationId:authorisationId received in response in Step 2.
  3. Execute the request.

Response

HTTP status code: 200 Ok

Example

{
    "account": {
        "iban": "LU280019400644750000",
        "bban": "80019400644750000",
        "pan": "EWQPS8534R",
        "maskedPan": "PS8534R****",
        "currency": "EUR"
    },
    "transactions": {
        "booked": [
            {
                "transactionId": "0005",
                "entryReference": "",
                "endToEndId": "",
                "mandateId": "",
                "checkId": "",
                "bookingDate": "2018-03-02",
                "valueDate": "2018-03-02",
                "transactionAmount": {
                    "currency": "EUR",
                    "amount": 40
                },
                "creditorName": "Schmidt",
                "creditorAccount": {
                    "iban": "LU280019400644750000",
                    "bban": "80019400644750000",
                    "pan": "EWQPS8534R",
                    "currency": "EUR"
                },
                "ultimateCreditor": "Schmidt",
                "debtorName": "Müller",
                "debtorAccount": {
                    "iban": "DE89370400440532013000",
                    "bban": "9370400440532013000",
                    "pan": "AEYPM5403H",
                    "currency": "EUR"
                },
                "ultimateDebtor": "Müller",
                "remittanceInformationUnstructured": "",
                "remittanceInformationStructured": "",
                "bankTransactionCode": "",
                "proprietaryBankTransactionCode": ""
            },
            {
                "transactionId": "0007",
                "entryReference": "",
                "endToEndId": "",
                "mandateId": "",
                "checkId": "",
                "bookingDate": "2018-01-02",
                "valueDate": "2018-01-02",
                "transactionAmount": {
                    "currency": "EUR",
                    "amount": 120
                },
                "creditorName": "Schmidt",
                "creditorAccount": {
                    "iban": "LU280019400644750000",
                    "bban": "80019400644750000",
                    "pan": "EWQPS8534R",
                   "currency": "EUR"
                },
                "ultimateCreditor": "Schmidt",
                "debtorName": "Müller",
                "debtorAccount": {
                    "iban": "DE89370400440532013000",
                    "bban": "9370400440532013000",
                    "pan": "AEYPM5403H",
                    "currency": "EUR"
                },
                "ultimateDebtor": "Müller",
                "remittanceInformationUnstructured": "",
                "remittanceInformationStructured": "",
                "bankTransactionCode": "",
                "proprietaryBankTransactionCode": ""
            }
        ],
        "pending": [],
        "_links": {}
    }
}

 

Related articles

Powered by Zendesk