Account Information Service

The Account Information Service is implemented according to the NextGenPSD2 XS2A Framework.

👍
Do it now!
The Account Information Service is fully supported by the API Test Client

Flow

This Account Information Service flow implements the NextGenPSD2 "OAuth2 SCA Approach: Implicit Start of the Authorisation Process" for authorisation of the consent request.

Refer to Authorisation for more details.

Request consent

In order to access account information it is required to first obtain the consent of the PSU.

Multiple consent models are specified by the NextGetPSD2 XS2A Framework. The Account Information Service uses the Bank Offered Consent model.

This process is initiated by posting a consent request which will result in creation of a consent resource together with a corresponding authorisation sub-resource.

Example consent request

This example demonstrates a recurring consent request for account information, balances and transactions.

curl 'https://xs2a-sandbox.triodos.com/xs2a-bg/nl/v1/consents' 
-H 'Digest: ...' 
-H 'PSU-IP-Address: 192.18.13.22' 
-H 'Signature: keyId="...",algorithm="rsa-sha256",headers="digest x-request-id",signature="..."' 
-H 'X-Request-ID: 11111111-2222-3333-4444-347991a0126' 
-H 'TPP-Redirect-URI: https://xs2a-sandbox.triodos.com/xs2a-bg/internalonly/consentFlowPage2.html' 
-H 'Content-Type: application/json' 
-H 'Accept: application/json' 
-H 'TPP-Signature-Certificate: ...' 
--data-binary '{"access":{"accounts":[{"iban":"...an IBAN"}],"balances":[{"iban":"...an IBAN"}],"transactions":[{"iban":"...an IBAN"}]},"recurringIndicator":true,"validUntil":"2019-05-30","frequencyPerDay":"4", "combinedServiceIndicator":"false"}'

The response contains consentStatus: received together with the consentId, authorisationId and various links.

The location of the consent resource is provided in the self link.

{
  "access": {
    "accounts": [
      { "iban": "...an IBAN", }
    ],
    "balances": [
      { "iban": "...an IBAN", }
    ],
    "transactions": [
      { "iban": "...an IBAN", }
    ]
  },
  "recurringIndicator": true,
  "validUntil": "2019-05-30",
  "frequencyPerDay": 4,
  "lastActionDate": "2019-02-28",
  "consentStatus": "received",
  "consentId": "c5bcbf1b-5a3a-45d4-86aa-ed17988e3a63",
  "authorisationId": "b6fafab4-0ae4-48a9-b192-28f8b1fdc0f9",
  "_links": {
    "scaOAuth": "https://xs2a-sandbox.triodos.com/auth/nl/.well-known/openid-configuration",
    "scaRedirect": "https://xs2a-sandbox.triodos.com/auth/nl/v1/auth?response_type=code&scope=openid+offline_access+AIS%3Ac5bcbf1b-5a3a-45d4-86aa-ed17988e3a63&client_id=...&redirect_uri=...",
    "scaStatus": "/nl/v1/consents/c5bcbf1b-5a3a-45d4-86aa-ed17988e3a63/authorisations/b6fafab4-0ae4-48a9-b192-28f8b1fdc0f9",
    "confirmation": "/nl/v1/consents/c5bcbf1b-5a3a-45d4-86aa-ed17988e3a63/authorisations/b6fafab4-0ae4-48a9-b192-28f8b1fdc0f9",
    "self": "/nl/v1/consents/c5bcbf1b-5a3a-45d4-86aa-ed17988e3a63",
    "status": "/nl/v1/consents/c5bcbf1b-5a3a-45d4-86aa-ed17988e3a63/status"
  }
}

Detailed Consent Model consent request

Let's look at the consent request body in a little more detail.

The access field contains optional accounts, balances and transactions entries, each of which must contain one or more account references.

Note that the balances and transactions fields both imply accounts access, so the accounts field is actually redundant in this example.

{
  "access": {
    "accounts": [
      {"iban": "...an IBAN"}
    ],
    "balances": [
      {"iban": "...an IBAN"}
    ],
    "transactions": [
      {"iban": "...an IBAN"}
    ]
  },
  "recurringIndicator": true,
  "validUntil": "2019-05-30",
  "frequencyPerDay": "4",
  "combinedServiceIndicator": "false"
}

An account reference must contain an account identifier in the form of either a valid IBAN or an Account Number and Sort Code (for UK customers only).

The combinedServiceIndicator must always be false.

The validUntil field is verified to ensure that it does not exceed the maximum of 90 days. For non-UK the validity of the consent is 180 days.

The frequencyPerDay field is verified to ensure that the number of unattended requests does not exceed the maximum of 4 times per day.

Bank Offered Consent model consent request

With this model the PSU selects their account during the Triodos SCA flow, therefore the account number is not provided in the consent request and the accounts field contains an empty list.

The TPP still needs to indicate if access to balances and/or transactions should be included in the consent, that is done by providing an empty list if the access is required. If the access is not required, the corresponding field can be omitted.

All other fields are the same as for the Detailed Consent Model.

{
  "access": {
    "accounts": [],
    "balances": [],
    "transactions": []
  },
  "recurringIndicator": true,
  "validUntil": "2019-05-30",
  "frequencyPerDay": "4",
  "combinedServiceIndicator": "false"
}

Once authorized by the PSU the selected account details are available via the consent details endpoint (provided in the self link in the consent request response), e.g. /nl/v1/consents/c5bcbf1b-5a3a-45d4-86aa-ed17988e3a63 in the example above.

UK PSUs

It is not industry standard in the UK to use IBANs to represent domestic accounts, therefore the Account Reference element has been extended to include the 6 digit ukSortCode and 8 digit ukAccountNumber fields.

This example shows the equivalent consent request body for a UK PSU with Account Number and Sort Code.

{
  "access": {
    "accounts": [
      {"ukSortCode": "...the sortCode", "ukAccountNumber": "...the accountNumber"}
    ],
    "balances": [
      {"ukSortCode": "...the sortCode", "ukAccountNumber": "...the accountNumber"}
    ],
    "transactions": [
      {"ukSortCode": "...the sortCode", "ukAccountNumber": "...the accountNumber"}
    ]
  },
  "recurringIndicator": true,
  "validUntil": "2019-05-30",
  "frequencyPerDay": "4",
  "combinedServiceIndicator": "false"
}

📘
NextGenPSD2 AccountReference extension
The ukSortCode and ukAccountNumber fields are not defined by the NextGetPSD2 XS2A Framework

Authorisation

An authorisation sub-resource has also been automatically created, at the location specified by the confirmation link.

Use the scaRedirect link to initiate the SCA process.

Once you have obtained an access token from the SCA process, use HTTP PUT on the confirmation link to update the authorisation sub-resource with the access token and complete the consent process.

When the authorisation sub-resource has been successfully authorised, it will contain scaStatus: finalised.

This process is described in more detail in the Authorisation section.

When the consent has sufficient authorisations to allow account access, the status of the consent resource changes from received to valid

curl 'https://xs2a-sandbox.triodos.com/xs2a-bg/nl/v1/consents/c5bcbf1b-5a3a-45d4-86aa-ed17988e3a63/status'
-H 'Digest: ...' 
-H 'Signature: keyId="...",algorithm="rsa-sha256",headers="digest x-request-id",signature="..."' 
-H 'X-Request-ID: 11111111-2222-3333-4444-347991a0126' 
-H 'Content-Type: application/json' 
-H 'Accept: application/json' 
-H 'TPP-Signature-Certificate: ...'

{"consentStatus":"valid"}

Now you have everything you need to access account information.

Account access

All account access APIs require these headers in addition to the standard Signing headers:

consent-id header with the consent id of the consent resource
authorization header with the access token that was obtained in the SCA process

Attended requests

When the PSU is directly requesting the account information, this is referred to as an attended request.

Attended requests do not count towards the daily limit of unattended requests. The TPP indicates that the request is an attended request by providing the IP Address of the PSU in the PSU-IP-Address header.

Recurring account access

With a recurring consent you can access both balances and the transaction history up to four times a day each in unattended mode (PSU-IP-Address header is not present). The full transaction history is available on the first get transactions request only.

One-off account access

You can access both balances and the full transaction history with a one-off consent (assuming that they are both included in the consent request).

Get Account Information

The accounts endpoint gives information and links related to the account for which consent has been obtained

curl 'https://xs2a-sandbox.triodos.com/xs2a-bg/nl/v1/accounts/' 
-H 'Digest: ...' 
-H 'authorization: Bearer ...the access token' 
-H 'Signature: keyId="...",algorithm="rsa-sha256",headers="digest x-request-id",signature="..."' 
-H 'X-Request-ID: 11111111-2222-3333-4444-5a393a3151b' 
-H 'consent-id: da296f9b-1099-4287-a268-87cd0a8ffcdf' 
-H 'Content-type: application/json' 
-H 'Accept: application/json' 
-H 'TPP-Signature-Certificate: ...'

The response contains some basic information about the account, together with links that can be used to request transaction and balance information, if included in the initial consent request.

{
  "accounts": [
    {
      "iban": "...an Iban",
      "currency": "EUR",
      "resourceId": "43e469f2-0468-4524-8be0-6e61acd34e1a",
      "cashAccountType": "CACC",
      "name": "The Fly Shop",
      "status": "enabled",
      "_links": {
        "transactions": "/nl/v1/accounts/43e469f2-0468-4524-8be0-6e61acd34e1a/transactions",
        "balances": "/nl/v1/accounts/43e469f2-0468-4524-8be0-6e61acd34e1a/balances"
      }
    }
  ]
}

Note: the name field contains the official registered name of the account and is suitable for use in your customer due diligence process. In the case of personal accounts it will contain the names of one or both account holders. In the case of a business account it will contain the registered name of the business.

Get Account Balances

Use the balances link provided in the account information response to get account balance information.

curl 'https://xs2a-sandbox.triodos.com/xs2a-bg/nl/v1/accounts/43e469f2-0468-4524-8be0-6e61acd34e1a/balances' 
-H 'Digest: ...' 
-H 'authorization: Bearer ...the access token' 
-H 'Signature: keyId="...",algorithm="rsa-sha256",headers="digest x-request-id",signature="..."' 
-H 'consent-id: da296f9b-1099-4287-a268-87cd0a8ffcdf' 
-H 'Content-type: application/json' 
-H 'Accept: application/json' 
-H 'TPP-Signature-Certificate:...'

The response includes both closingBooked and expected balance information, as defined by the NextGetPSD2 XS2A Framework.

{
  "account": {
    "iban": "...an Iban"
  },
  "balances": [
    {
      "balanceType": "closingBooked",
      "balanceAmount": {
        "currency": "EUR",
        "amount": "1000000.00"
      },
      "referenceDate": "2019-02-28",
      "creditLimitIncluded": false
    },
    {
      "balanceType": "expected",
      "balanceAmount": {
        "currency": "EUR",
        "amount": "1004000.00"
      },
      "referenceDate": "2019-02-28",
      "creditLimitIncluded": true
    }
  ]
}

Get Account Transactions

Use the transactions link provided in the account information response to get account transaction information.

Append the bookingStatus, dateFrom and optionally the dateTo parameter to the request in order to obtain the most recent (i.e. first page of) transactions.

Note that the optional entryReferenceFrom and deltaList parameters from the NextGetPSD2 XS2A Framework are not supported.

curl 'https://xs2a-sandbox.triodos.com/xs2a-bg/nl/v1/accounts/43e469f2-0468-4524-8be0-6e61acd34e1a/transactions?bookingStatus=both&dateFrom=2017-01-01&dateTo=2019-02-28' 
-H 'Accept-Encoding: gzip, deflate, br' 
-H 'Digest: ...'
-H 'authorization: Bearer ...an access token' 
-H 'Signature: keyId="...",algorithm="rsa-sha256",headers="digest x-request-id",signature="..."' 
-H 'X-Request-ID: 11111111-2222-3333-4444-aab058ba67a' 
-H 'consent-id: da296f9b-1099-4287-a268-87cd0a8ffcdf' 
-H 'Content-type: application/json' 
-H 'Accept: application/json' 
-H 'TPP-Signature-Certificate: ...'

The JSON response conforms to the NextGetPSD2 XS2A Framework.

{
  "account": {
    "iban": "...an Iban"
  },
  "transactions": {
    "booked": [
      {
        "transactionId": "da23ed38-5319-4dbc-a522-a0e173539b4e",
        "bookingDate": "2019-02-26",
        "valueDate": "2019-02-26",
        "transactionAmount": {
          "currency": "EUR",
          "amount": "31.07"
        },
        "debtorName": "Mr Tester",
        "debtorAccount": {
          "iban": "...an Iban"
        },
        "remittanceInformationUnstructured": "remitInfo",
        "proprietaryBankTransactionCode": "OV",
        "endToEndId": "E2EID",
        "batchIndicator": false
      },
      {
        "transactionId": "24dcc575-d1e2-4e18-a4ad-e0d90c4b5e9c",
        "bookingDate": "2019-02-26",
        "valueDate": "2019-02-26",
        "transactionAmount": {
          "currency": "EUR",
          "amount": "9.18"
        },
        "creditorName": "Ms Testee",
        "creditorAccount": {
          "iban": "...an Iban"
        },
        "remittanceInformationUnstructured": "moreRemitInfo",
        "proprietaryBankTransactionCode": "OV",
        "endToEndId": "PMTINFID",
        "batchIndicator": true,
        "batchNumberOfTransactions": 42
      }
    ],
    "pending": [],
    "_links": {
      "account": "/nl/v1/accounts/43e469f2-0468-4524-8be0-6e61acd34e1a",
      "first": "/nl/v1/accounts/43e469f2-0468-4524-8be0-6e61acd34e1a/transactions?bookingStatus=both&dateFrom=2018-11-30&dateTo=2019-02-28",
      "next": "/nl/v1/accounts/43e469f2-0468-4524-8be0-6e61acd34e1a/transactions?edgeToken=tcqjHvUYUe-WjE03ymaXkp74YhyvzeuiBk_nZ8CGjf0fiyzvaC8vwOoZkf-R6LuShSsgws9tfeH3"
    }
  }
}

Note that amounts in the transaction report are not signed. The direction of the transaction can be determined from the presence of the debtorAccount (received) or creditorAccount (payed) fields.

The full transaction history is only available on the first call to the transactions endpoint for any given consent. Use the next link to page through the transactions to the end. On subsequent calls to the transactions endpoint up to 90 days of transactions can be retrieved. This is in order to prevent unnecessary load being placed on our servers.

For batch payments with btchBookg = false, the API returns as the

endToEndId: the endToEndId of the individual transaction as in the original PAIN file
batchIndicator: false

For batch payments with btchBookg = true, the API returns as the

endToEndId: the PMTINFID from the original PAIN file
batchIndicator: true
batchNumberOfTransactions: the total number of transactions in the batch transaction

Pagination

A limited number of transactions is returned with each request in order to optimise service performance. Use the next link to scroll through the transactions one page at a time.

Transaction paging requests do not count towards the daily limit of unattended account requests.

Withdrawal of consent

Withdrawal of consent is illustrated by this flow

Use HTTP DELETE on the consent resource to cancel the consent at any time. For instance, if the account holder indicates that they wish to withdraw their consent or it is no longer required.

curl 'https://xs2a-sandbox.triodos.com/xs2a-bg/nl/v1/consents/c5bcbf1b-5a3a-45d4-86aa-ed17988e3a63'
-X DELETE
-H 'Digest: ...' 
-H 'Signature: keyId="...",algorithm="rsa-sha256",headers="digest x-request-id",signature="..."' 
-H 'X-Request-ID: 11111111-2222-3333-4444-347991a0126' 
-H 'Content-Type: application/json' 
-H 'Accept: application/json' 
-H 'TPP-Signature-Certificate: ...'

HTTP return code 204 indicates that the consent has been successfully withdrawn.

Subsequent consent resource status requests will indicate that the consent is no longer valid.

{"consentStatus":"terminatedByTpp"}

Account Information Service

👍
Do it now!

Flow

Request consent

Example consent request

Detailed Consent Model consent request

Bank Offered Consent model consent request

UK PSUs

📘
NextGenPSD2 AccountReference extension

Authorisation

Account access

Attended requests

Recurring account access

One-off account access

Get Account Information

Get Account Balances

Get Account Transactions

Pagination

Withdrawal of consent

👍Do it now!

Flow

Request consent

Example consent request

Detailed Consent Model consent request

Bank Offered Consent model consent request

UK PSUs

📘NextGenPSD2 AccountReference extension

Authorisation

Account access

Attended requests

Recurring account access

One-off account access

Get Account Information

Get Account Balances

Get Account Transactions

Pagination

Withdrawal of consent

👍
Do it now!

📘
NextGenPSD2 AccountReference extension