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 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 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="SHA256withRSA",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"
  }
}

The consent request body

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 it does not exceed the maximum of 4 times per day.

UK account holders

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 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 authorisation sub-resource has also been automatically created, at the location specified by the scaStatus link.

Use the scaRedirect link to initiate the SCA process.

Once you have obtained an access token from the SCA process, use HTTP PUT 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="SHA256withRSA",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

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="SHA256withRSA",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": "CURRENT",
      "name": "Zaken Doen",
      "status": "enabled",
      "_links": {
        "transactions": "/nl/v1/accounts/43e469f2-0468-4524-8be0-6e61acd34e1a/transactions",
        "balances": "/nl/v1/accounts/43e469f2-0468-4524-8be0-6e61acd34e1a/balances"
      }
    }
  ]
}

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="SHA256withRSA",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 CLOSING_BOOKED and EXPECTED balance information, as defined by the NextGetPSD2 XS2A Framework.

{
  "account": {
    "iban": "...an Iban"
  },
  "balances": [
    {
      "balanceType": "CLOSING_BOOKED",
      "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.

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="SHA256withRSA",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"
      },
      {
        "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"
      }
    ],
    "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/page?edgeToken=tcqjHvUYUe-WjE03ymaXkp74YhyvzeuiBk_nZ8CGjf0fiyzvaC8vwOoZkf-R6LuShSsgws9tfeH3"
    }
  }
}

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.

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="SHA256withRSA",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


Suggested Edits are limited on API Reference Pages

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