Skip to main content

05. How to Access Account Balances and Transactions

  • Updated

Account Information Services

XS2A Account Information Service offers the access to list of accounts of a PSU, account details, transactions and balances.

A bank defines which accounts are accessible through XS2A.

Prerequisites

  1. Your certificate must contain the PSP role = PSP_AI.
  2. You must have PSU consent on accessing requested account information. Learn more about consents access rights 10. XS2A Consent Models and Access Rights.
  3. Consent must have status = "valid" in XS2A.
  4. Consent frequencyPerDay must not be exceeded in XS2A. Learn more about access frequency validation in 16. Consent frequency validation.

Read account list

Using the /accounts endpoint you can obtain the list of accounts of a particular PSU.

Important: these will be only those accounts that are accessible through XS2A according to internal bank rules.

Response contains an array of account details supported by a bank.

XS2A interface support all account details attributes defined by the Berlin Group standard although not all of them might be available in a bank.

Request

  1. Go to /v1/accounts.
  2. Fill in mandatory data
  3. Execute the request.

Response

HTTP status code: 200 Ok

Example
{
    "accounts": [
        {
            "resourceId": "42fb4cc3-91cb-45ba-9159-b87acf6d8add",
            "iban": "DE52500105173911841934",
            "bban": "2500105173911841934",
            "currency": "EUR",
            "name": "Main Account",
            "ownerName": "Mary Müller",
            "product": "GIRO",
            "_links": {}
        },
        {
            "resourceId": "66666-999999999",
            "iban": "DE89370400440532013005",
            "bban": "370400440532013005",
            "currency": "USD",
            "name": "Company AG,
            "product": "SCT",
            "_links": {}
        }
    ]
}
 

Read account details

Using the /accounts/{account-id} endpoint you can obtain the details of a particular account.

Important: you must use "resourceId" of an account as the path parameter {account-id}. "resourceId" is a part of the response on the Read account list call.

Response contains account details supported by a bank.

XS2A interface support all account details attributes defined by the Berlin Group standard although not all of them might be available in a bank.

Request

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

Response

HTTP status code: 200 Ok

Example
{
    "resourceId": "33333-999999999",
    "iban": "LU280019400644750000",
    "bban": "80019400644750000",
    "currency": "EUR",
    "name": "Main Account",
    "ownerName": "Mary Müller",
    "product": "SCT",
    "bic": "DEUTDE8EXXX",
    "_links": {}
}
 

Read account balance

Using the /accounts/{account-id}/balances endpoint you can obtain the information about balances of a particular account.

Important: you must use "resourceId" of an account as the path parameter {account-id}. "resourceId" is a part of the response on the Read account list call.

Response contains account reference and array of balances available for a particular account.

XS2A interface support all attributes of account reference and balances defined by the Berlin Group standard although not all of them will be available in a bank.

Request

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

Response

HTTP status code: 200 Ok

Example
{
    "account": {
        "iban": "LU280019400644750000",
        "bban": "80019400644750000",
        "pan": "EWQPS8534R",
        "maskedPan": "PS8534R****",
        "currency": "EUR"
    },
    "balances": [
        {
            "balanceAmount": {
                "currency": "EUR",
                "amount": 3000
            },
            "balanceType": "interimAvailable",
            "lastChangeDateTime": "2018-11-08T10:09:54.000+0000",
            "referenceDate": "2018-11-08",
            "lastCommittedTransaction": "abcd",
            "creditLimitIncluded": true
        }
    ]
}
 

Read transaction list of an account: transactions younger than 90 days from current date

Using the /accounts/{account-id}/transactions endpoint you can obtain the information about transactions of a particular account.

Access to transactions that are older than 90 days (from current date) will require authorisation from PSU - similar to payment or consent authorisation. Learn more at 13. How to access transactions older than 90 days (from current date).
Access to transactions that are younger than 90 days doesn't require any SCA: the description of the relevant calls is given below.

Important: you must use "resourceId" of an account as the path parameter {account-id}. "resourceId" is a part of the response on the Read account list call.

Response contains account reference and array of transaction details available for a particular account.

XS2A interface support all attributes of account reference and transaction details defined by the Berlin Group standard although not all of them will be available in a bank.

Request

  1. Go to /v1/accounts/{account-id}/transactions.
  2. Fill in mandatory data
    • Method = GET
    • X-Request-ID = valid UUID
    • Consent-ID = {consentId}. Learn how to create and authorise consents in XS2A 04. How to Create and Authorise an AIS Consent.
    • account-id = {resourceId}
    • bookingStatus = both. One of [booked, pending, both] must be used.
  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": {}
    }
}
 

Read transaction details

Using the /accounts/{account-id}/transactions/{resourceId} endpoint you can obtain the information about transactions of a particular account.

Important:

you must use "resourceId" of an account as the path parameter {account-id}. "resourceId" is a part of the response on the Read account list call.

you must use "transactionId" of an transaction as the path parameter {resourceId}. "transactionId" is a part of the response on the Read transaction list of an account call.

Response contains transaction details available for a particular transaction.

XS2A interface support all attributes of transaction details defined by the Berlin Group standard although not all of them will be available in a bank.

Request

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

Response

HTTP status code: 200 Ok

Example
{
    "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": ""
}

Read list of standing orders of an account

Using the /accounts/{account-id}/transactions endpoint you can also obtain the information about standing orders of a particular account.

It can be done by passing the query parameter "bookingStatus" = information.

Important: you must use "resourceId" of an account as the path parameter {account-id}. "resourceId" is a part of the response on the Read account list call.

Response contains account reference and array of transaction details available for a particular account.

XS2A interface support most of the attributes of account reference and transaction details defined by the Berlin Group standard although not all of them will be available in a bank.

Request

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

Response

HTTP status code: 200 Ok

Example

{
  "account": {
    "iban": "DE52500105173911841934"
  },
  "transactions": {
    "information": [
      {
        "additionalInformationStructured": {
          "dayOfExecution": 1,
          "endDate": "2020-03-13",
          "executionRule": "following",
          "frequency": "monthly",
          "startDate": "2021-03-13"
        },
        "bankTransactionCode": "PMNT-ICDT-STDO",
        "creditorAccount": {
          "iban": "CZ0227000000003109414008"
        },
        "creditorName": "Name",
        "remittanceInformationUnstructured": "Test",
        "transactionAmount": {
          "amount": 10,
          "currency": "EUR"
        }
      }
    ]
  }
}

 

Related articles

Powered by Zendesk