Open Banking with Impact

Join us on our mission to change finance so that the banking sector becomes more transparent, diverse and sustainable

Get Started

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 NextGenPSD2NextGenPSD2 - The NextGenPSD2 XS2A Framework is a European standard framework for building PSD2 compliant XS2A (Access to account) APIs. This specification covers payment initiation, account information and confirmation of funds services. Our APIs implement version 1.3 (including Errata) of this specification. "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 PSUPSU - Payment Service User, i.e. The Triodos account holder..

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",
    "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.

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 PSUPSU - Payment Service User, i.e. The Triodos account holder. 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 authorisationauthorisation - Authorisation refers to the authorisation sub-resources of the NextGenPSD2 Xs2a Framework. sub-resource has also been automatically created, at the location specified by the scaStatus link.

Use the scaRedirect link to initiate the SCASCA - Strong Customer Authentication. SCA is defined by the RTS as ‘an authentication based on the use of two or more elements categorised as knowledge (something only the user knows), possession (something only the user possesses) and inherence (something the user is) that are independent’ and that ‘protect[s] the confidentiality of the authentication data’. process.

Once you have obtained an access token from the SCASCA - Strong Customer Authentication. SCA is defined by the RTS as ‘an authentication based on the use of two or more elements categorised as knowledge (something only the user knows), possession (something only the user possesses) and inherence (something the user is) that are independent’ and that ‘protect[s] the confidentiality of the authentication data’. process, use HTTP PUT to update the authorisationauthorisation - Authorisation refers to the authorisation sub-resources of the NextGenPSD2 Xs2a Framework. sub-resource with the access token and complete the consent process.

When the authorisationauthorisation - Authorisation refers to the authorisation sub-resources of the NextGenPSD2 Xs2a Framework. 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 SCASCA - Strong Customer Authentication. SCA is defined by the RTS as ‘an authentication based on the use of two or more elements categorised as knowledge (something only the user knows), possession (something only the user possesses) and inherence (something the user is) that are independent’ and that ‘protect[s] the confidentiality of the authentication data’. 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.

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"
      },
      {
        "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"
      }
    ],
    "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.

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"}

Updated 5 days ago

Account Information Service


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.