Account information service

In order to retrieve account information a consent is required. The information on this page describes the steps required to obtain a consent and the way a consent can be used to retrieve account information.

NOTE: To use these APIs, a valid TLS certificate is required.

The following methods are supported:

Create consent
Approve consent
Retrieve access token
Retrieve consent status
Retrieve consent details
Retrieve consent authorisations
Retrieve consent authorisation details
Read available accounts
Read account information
Read balance information
Read transaction list
Read transaction details
Read account statements
Delete consent

Create consent

In order to access account information, a consent is required. This chapter describes the steps required to create such a consent. The created consent has to be approved in the next step before it can be used.

Create JSON body
Generate signature and set headers
Perform request

Create JSON body

{
	"access": {
	  "accounts": null,
	  "balances": null,
	  "transactions": null,
	  "availableAccounts": null,
	  "availableAccountsWithBalances": null,
	  "allPsd2": "allAccounts"
	},
	"combinedServiceIndicator": false,
	"recurringIndicator": true,
	"validUntil": "2019-06-19",
	"frequencyPerDay": 4
}

field	description
access	Specifies the content of the consent, either global or account specific. The following properties are used for account specific consents and can contain arrays of account numbers. More than one property may be provided. Different arrays can contain different account numbers. These properties may not be combined with non-account specific properties. accounts balances transactions The following properties are for global (non-account specific) consents. Only one of these may have the value "allAccounts". All others should be null availableAccounts availableAccountsWithBalances allPsd2
access.accounts	A list of accounts to grant account information access to. When approved, this consent can be used to retrieve account information for the specified accounts. Example: [{ "iban": "NL34BNGT5532530633", "currency": "EUR" }]
access.balances	A list of accounts to grant account balance access to. When approved, this consent can be used to retrieve balance information for the specified accounts. Example: [{ "iban": "NL34BNGT5532530633", "currency": "EUR" }]
access.transactions	A list of accounts to grant account transaction access to. When approved, this consent can be used to retrieve transactions for the specified accounts. Example: [{ "iban": "NL34BNGT5532530633", "currency": "EUR" }]
access.availableAccounts	Grants access to the following information about all accounts the user has access to Details of the account (iban, name and currency of the accounts) Possible values "allAccounts" or null. This property may not be combined with access.availableAccountsWithBalances, access.allPsd2, access.accounts, access.balances, access.balances and access.transactions.
access.availableAccountsWithBalances	Grants access to the following information about all accounts the user has access to Details of the account (iban, name and currency of the accounts) Booking balance of account Possible values "allAccounts" or null. This property may not be combined with access.availableAccounts, access.allPsd2, access.accounts, access.balances, access.balances and access.transactions.
access.allPsd2	Grants access to the following information about all accounts the user has access to Details of the account (iban, name and currency of the accounts) Booking balance of account Transactions of the account Account statements of the account Possible values "allAccounts" or null. This property may not be combined with access.availableAccounts, access.availableAccountsWithBalances, access.accounts, access.balances, access.balances and access.transactions.
combinedServiceIndicator	Boolean value. If “true” indicates that a payment initiation service will be addressed in the same "session".
recurringIndicator	Boolean value. "true", if the consent is for recurring access to the account data. "false", if the consent is for one-off access to the account data.
validUntil	This parameter is defining a valid until date for the requested consent in ISODate Format, e.g. 2017-10-30. The maximum number of days a consent can be valid for is 180 days. If a maximal available date is requested, a date in the far future is to be used: "9999-12-31", the date is modified to 180 days in advance from the moment the consent is approved by the PSU. Note that any date further than 180 days will be modified to the maximum of 180 days. The consent object to be retrieved by the GET Consent Request will contain the adjusted date.
frequencyPerDay	Integer value of ranging from 1 to 4. Determines the number of times a recurring consent can be used per day.

Generate signature and set headers

The generate a signature, see Signature setup

The following headers must be provided

Header	Example	Description
Content-Type	application/json	Only application/json is supported.
Date	Fri, 09 Apr 2021 15:12:03 GMT	The date of the request.
X-Request-ID	2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329	An identifier chosen by the TPP to identify the request. This id is passed back in the X-Request-ID header of the response
PSU-IP-Address	123.12.12.12	The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP.
PSU-User-Agent	Chrome OS	The forwarded Agent header field of the HTTP request between PSU and TPP, if available.
PSU-Geo-Location	51.20,4.2	The forwarded Geo Location of the corresponding http request between PSU and TPP if available.
TPP-Redirect-URI	https://tpp.com/some-redirect	URI of the TPP, where the transaction flow shall be redirected to after a Redirect. This field is currently optional.
Accept	application/json	The content type the client is able to understand. Must be application/json.
Digest	SHA-256=262LaJygmoifcl5pVlhlUXW1QNUfGhfryy03ud/uxMs=	Digest of the body of the request. This field is mandatory, because the ASPSP mandates the use of a signature.
Signature		A signature of the request. The ASPSP mandates the use of a signature.
TPP-Signature-Certificate		The certificate used for signing the request, in base64 encoding. This field is mandatory, because the ASPSP mandates the use of a signature.

Perform request

Endpoint	https://api.xs2a.bngbank.nl/api/v1/consents
Method	POST

After a successful consent creation, status code 201 is returned along with the create consent response.

{
	"consentStatus": "received",
	"consentId": "2d976b8b-2596-4e4a-930f-9cafa12c9b57",
	"_links": {
	  "scaOAuth": {
		"href": "https://w2.web.xs2a.bngbank.nl/well-known/oauth-configuration"
	  },
	  "self": {
		"href": "/api/v1/consents/2d976b8b-2596-4e4a-930f-9cafa12c9b57"
	  },
	  "status": {
		"href": "/api/v1/consents/2d976b8b-2596-4e4a-930f-9cafa12c9b57/status"
	 }
}

Please store consent-id somewhere, for example in Notepad, as it is required in later steps.

go to top

Approve consent

After a consent has been created, it has to be approved by the PSU. To do so, the following steps have to be taken:

Redirect to OAuth2.0 endpoint
Login
Review consent
Approve consent

Redirect to OAuth2.0 endpoint

To create an OAuth2.0 redirect URL, please refer to the Oauth2.0 page.

When creating an OAuth2.0 redirect, a scope is required. This scope should look like: "AIS:[consent-id]". Where consent-id is the id returned in the previous step. For example: "AIS:dea36cf3-63fa-48b3-b203-2136f5453751".

NOTE: when testing multiple scenarios in quick succession, it is advised to use an incognito browser when navigating to the OAuth2.0 redirect URL. This is because after logging in, the user remains signed in for a period of time.

Login

After navigating to the OAuth2.0 redirect URL, a login page is displayed. The login page will only appear if the user is not authenticated.

Review consent

After successfully signing in, the consent details will be displayed. Depending on the type of consent being approved, permissions for specific accounts are displayed (account specific consent), or permissions for all accounts (global consent).

Approve consent

If the user has sufficient authorisation to approve the consent, the consent can be approved. To approve a consent, click "Approve". To decline a consent, click "Back" to return to redirect_url without approving. No access code will be returned.

Redirect

After the consent has been approved, the user is redirected back to the redirect_uri that has been passed on the query string. This redirect_uri will contain an additional query string parameter "Code". This code can be used to obtain an access token. With this access token, data regarding this consent can be retrieved.

go to top

Retrieve access token

An access code from the previous step can be exchanged for an access token by the following API

Body

Example of request body. Note: line breaks are for clarifying the example.

client_id=PSDNL-AUT-SANDBOX&
grant_type=authorization_code&
code=f1084fea123e4bc3bcca0a1e5a0a54e5b70e91811dce483aa2168dc539c5f70f&
code_verifier=someverifierdata1234&
state=438b3d36666341019366cf190b57a349&
redirect_uri=redirect_uri

Field	Example value	Description
client_id	PSDNL-AUT-SANDBOX	The same client id as present in the TLS certificate.
grant_type	authorization_code	The grant type requested
code	f10...70f	The access code as returned by the confirmation site.
code_verifier	someverifierdata1234	The code_verifier as passed to the OAuth2.0 authorisation request.
state	438b3d36666341019366cf190b57a349	The state
redirect_uri	https://tpp.com/access_token	The redirect_uri as passed to the OAuth2.0 authorisation request.

Headers

The following headers are required for the request

Header	Example value	Description
Content-Type	application/x-www-form-urlencoded
Accept	application/json

Perform request

Endpoint	https://api.xs2a.bngbank.nl/token
Method	POST

If the call was successful, a 201 status is returned along with the response body. See below an example of a response.

{
	"access_token": "eyJh...R49Q",
	"token_type": "Bearer",
	"expires_in": "604782",
	"refresh_token": "91f557fe-e01d-4498-bcb9-46dba668de08",
	"scope": "AIS:ec1bff9e-79d2-4588-9112-2ae65ae2a14b"
}

For other possible return codes, see the API DOCUMENTATION page.

Please store access_token somewhere, for example in Notepad, as it is required in later steps. Note that the access token gives access to all API methods for the corresponding paymentInitiationId. In case a paymentInitiationBatchGroupId was used in a redirect, the access token will give access to all paymentInitiationIds that were generated from the bulk payment file, e.g. in a bulk payment file containing multiple bulk-payments/batches.

go to top

Retrieve consent status

To retrieve the status of a consent, a consent-id as well as an access_token is required, please see previous steps for directions on how to obtain those.

Headers

The following headers must be provided

Header	Example	Description
Content-Type	application/json
Date	Fri, 09 Apr 2021 15:12:03 GMT	The date of the request.
X-Request-ID	2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329	An identifier chosen by the TPP to identify the request. This id is passed back in the X-Request-ID header of the response
Authorization	Bearer ACCESS_TOKEN	Replace ACCESS_TOKEN with the access token obtained in a previous step.
Accept	application/json
Digest	SHA-256=spt...rrI	Digest of the body
Signature	keyId=\"SN=...Yiow==\	The signature of the request, see Signature setup
TPP-Signature-Certificate	-----BEGIN CERTIFICATE-----MII...UjY=-----END CERTIFICATE-----	The certificate used to sign the request.

Perform request

Endpoint	https://api.xs2a.bngbank.nl/api/v1/consents/CONSENT_ID/status	Replace CONSENT_ID with the id of a consent, for example: 2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329
Method	GET

If the call was successful, a 200 status is returned along with the response body. See below an example of a response.

{
	"consentStatus": "valid"
}

For other possible return codes, see the API DOCUMENTATION page.

go to top

Retrieve consent details

To retrieve details of a consent, a consent-id as well as an access_token is required, please see previous steps for directions on how to obtain those.

Headers

The following headers must be provided

Header	Example	Description
Content-Type	application/json
Date	Fri, 09 Apr 2021 15:12:03 GMT	The date of the request.
X-Request-ID	2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329	An identifier chosen by the TPP to identify the request. This id is passed back in the X-Request-ID header of the response
Authorization	Bearer ACCESS_TOKEN	Replace ACCESS_TOKEN with the access token obtained in a previous step.
Accept	application/json
Digest	SHA-256=spt...rrI	Digest of the body
Signature	keyId=\"SN=...Yiow==\	The signature of the request, see Signature setup
TPP-Signature-Certificate	-----BEGIN CERTIFICATE-----MII...UjY=-----END CERTIFICATE-----	The certificate used to sign the request.

Perform request

Endpoint	https://api.xs2a.bngbank.nl/api/v1/consents/CONSENT_ID	Replace CONSENT_ID with the id of a consent, for example: 2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329
Method	GET

If the call was successful, a 200 status is returned along with the response body. See below an example of a response.

{
	"lastActionDate": "2019-03-21T13:50:44.18+01:00",
	"consentStatus": "valid",
	"access": {
	  "allPsd2": "allAccounts"
	},
	"combinedServiceIndicator": false,
	"recurringIndicator": true,
	"validUntil": "2019-06-19",
	"frequencyPerDay": 4
}

For other possible return codes, see the API DOCUMENTATION page.

go to top

Retrieve consent authorisations

To retrieve authorisations (confirmations) of a consent, a consent-id as well as an access_token is required, please see previous steps for directions on how to obtain those.

Headers

The following headers must be provided

Header	Example	Description
Content-Type	application/json
Date	Fri, 09 Apr 2021 15:12:03 GMT	The date of the request.
X-Request-ID	2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329	An identifier chosen by the TPP to identify the request. This id is passed back in the X-Request-ID header of the response
Authorization	Bearer ACCESS_TOKEN	Replace ACCESS_TOKEN with the access token obtained in a previous step.
Accept	application/json
Digest	SHA-256=spt...rrI	Digest of the body
Signature	keyId=\"SN=...Yiow==\	The signature of the request, see Signature setup
TPP-Signature-Certificate	-----BEGIN CERTIFICATE-----MII...UjY=-----END CERTIFICATE-----	The certificate used to sign the request.

Perform request

Endpoint	https://api.xs2a.bngbank.nl/api/v1/consents/CONSENT_ID/authorisations	Replace CONSENT_ID with the id of a consent, for example: 2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329
Method	GET

If the call was successful, a 200 status is returned along with the response body. See below an example of a response.

{
	"authorisationIds": [
	  "19e54cc4-400e-4ba5-a9cd-0bfd39753f64"
	]
}

Store an authorisation-id somewhere, for example in Notepad, as it is required for the next step.

For other possible return codes, see the API DOCUMENTATION page.

go to top

Retrieve consent authorisation details

To retrieve the details of an authorisation (confirmation) of a consent, a consent-id as well as an access_token and an authorisation-id is required, please see previous steps for directions on how to obtain those.

Headers

The following headers must be provided

Header	Example	Description
Content-Type	application/json
Date	Fri, 09 Apr 2021 15:12:03 GMT	The date of the request.
X-Request-ID	2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329	An identifier chosen by the TPP to identify the request. This id is passed back in the X-Request-ID header of the response
Authorization	Bearer ACCESS_TOKEN	Replace ACCESS_TOKEN with the access token obtained in a previous step.
Accept	application/json
Digest	SHA-256=spt...rrI	Digest of the body
Signature	keyId=\"SN=...Yiow==\	The signature of the request, see Signature setup
TPP-Signature-Certificate	-----BEGIN CERTIFICATE-----MII...UjY=-----END CERTIFICATE-----	The certificate used to sign the request.

Perform request

Endpoint	https://api.xs2a.bngbank.nl/api/v1/consents/CONSENT_ID/authorisations/AUTHORISATION_ID	Replace CONSENT_ID with the id of a consent, for example: 2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329. Also replace AUTHORISATION_ID for the id of the authorisation (confirmation), for example: fb74e2f0-6807-4c2a-8662-8d519d87e0a4
Method	GET

If the call was successful, a 200 status is returned along with the response body. See below an example of a response.

{
	"scaStatus": "finalised"
}

For other possible return codes, see the API DOCUMENTATION page.

go to top

Read available accounts

To read a list of available accounts, a consent is required. Please refer to previous steps for instructions on how to obtain a consent.

Headers

The following headers must be provided

Header	Example	Description
Content-Type	application/json
Date	Fri, 09 Apr 2021 15:12:03 GMT	The date of the request.
X-Request-ID	2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329	An identifier chosen by the TPP to identify the request. This id is passed back in the X-Request-ID header of the response
Authorization	Bearer ACCESS_TOKEN	Replace ACCESS_TOKEN with the access token obtained in a previous step.
Accept	application/json

QueryString

The following query string parameters can be provided

Parameter	Example	Description	Condition
withBalance	true	Boolean value. If contained, this function reads the list of accessible payment accounts including the booking balance, if granted by the PSU in the related consent.	Optional

Perform request

Endpoint	https://api.xs2a.bngbank.nl/api/v1/accounts?withBalance=true
Method	GET

If the call was successful, a 200 status is returned along with the response body. See below an example of a response.

Links: Each account details contains a list of links to retrieve additional information. These are the following links

balances, will only be included if the corresponding account was provided specifically in the balances array or AllPsd2 was specified.
transactions, will only be included if the corresponding account was provided specifically in the transactions array or AllPsd2 was specified.

{
	"accounts": [
	  {
		"resourceId": "f2d27b73-4494-83fb-1664-3b34b4484584",
		"iban": "NL34BNGT5532530633",
		"currency": "EUR",
		"name": "Mr. Test",
		"product": "",
		"cashAccountType": "CACC",
		"status": "enabled",
		"bic": "",
		"linkedAccounts": "",
		"usage": "ORGA",
		"details": "Betaalrekening",
		"balances": [
		  {
			"balanceAmount": {
			  "currency": "EUR",
			  "amount": "13000.00"
			},
			"balanceType": "ClosingBooked",
			"creditLimitIncluded": false,
			"lastChangeDateTime": "Fri, 22 Mar 2019 00:00:00 GMT",
			"referenceDate": "Tue, 12 Mar 2019 00:00:00 GMT"
		  }
		],
		"_links": {
		  "balances": {
			"href": "/api/v1/accounts/f2d27b73-4494-83fb-1664-3b34b4484584/balances"
		  },
		  "transactions": {
			"href": "/api/v1/accounts/f2d27b73-4494-83fb-1664-3b34b4484584/transactions"
		  }
		}
	  },
	  {
		"resourceId": "d494f75b-73f4-6763-8372-e24212284568",
		"iban": "NL77BNGT2034202452",
		"currency": "EUR",
		"name": "Ms. Test",
		"product": "",
		"cashAccountType": "CACC",
		"status": "enabled",
		"bic": "",
		"linkedAccounts": "",
		"usage": "ORGA",
		"details": "Betaalrekening",
		"balances": [
		  {
			"balanceAmount": {
			  "currency": "EUR",
			  "amount": "11000.00"
			},
			"balanceType": "ClosingBooked",
			"creditLimitIncluded": false,
			"lastChangeDateTime": "Fri, 22 Mar 2019 00:00:00 GMT",
			"referenceDate": "Tue, 12 Mar 2019 00:00:00 GMT"
		  }
		],
		"_links": {
		  "balances": {
			"href": "/api/v1/accounts/d494f75b-73f4-6763-8372-e24212284568/balances"
		  },
		  "transactions": {
			"href": "/api/v1/accounts/d494f75b-73f4-6763-8372-e24212284568/transactions"
		  }
		}
	  }
	]
}

For other possible return codes, see the API DOCUMENTATION page.

Please store account-id's somewhere, for example in Notepad, as the are required in later steps.

go to top

Read account information

This method can only be accessed with a specific consent or a consent where AllPsd2 is included. Please refer to previous steps for instructions on how to obtain a consent.

Headers

The following headers must be provided

Header	Example	Description
Content-Type	application/json
Date	Fri, 09 Apr 2021 15:12:03 GMT	The date of the request.
X-Request-ID	2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329	An identifier chosen by the TPP to identify the request. This id is passed back in the X-Request-ID header of the response
Authorization	Bearer ACCESS_TOKEN	Replace ACCESS_TOKEN with the access token obtained in a previous step.
Accept	application/json

QueryString

The following query string parameters can be provided

Parameter	Example	Description	Condition
withBalance	true	Boolean value. If contained, this function reads the details of the account including the booking balance, if granted by the PSU in the related consent.	Optional

Perform request

Endpoint	https://api.xs2a.bngbank.nl/api/v1/accounts/ACCOUNT_ID?withBalance=true	Replace ACCOUNT_ID with the id of an account, for example: 057db59e-61d0-9d37-d28a-cebc79c215ca. Please note that this is not the IBAN of the account but the resourceId as returned by the read account list API. This accountId is specific to the consent being used. This means that for another consent, the account has to be addressed by another acountId.
Method	GET

If the call was successful, a 200 status is returned along with the response body. See below an example of a response.

Links: The details contain a list of links to retrieve additional information. These are the following links

balances, will only be included if the corresponding account was provided specifically in the balances array or AllPsd2 was specified.
transactions, will only be included if the corresponding account was provided specifically in the transactions array or AllPsd2 was specified.

{
	"account": {
	  "resourceId": "057db59e-61d0-9d37-d28a-cebc79c215ca",
	  "iban": "NL34BNGT5532530633",
	  "currency": "EUR",
	  "name": "K. Dekker",
	  "product": "",
	  "cashAccountType": "CACC",
	  "status": "enabled",
	  "bic": "",
	  "linkedAccounts": "",
	  "usage": "ORGA",
	  "details": "Betaalrekening",
	  "balances": [
		{
		  "balanceAmount": {
			"currency": "EUR",
			"amount": "13000.00"
		  },
		  "balanceType": "ClosingBooked",
		  "creditLimitIncluded": false,
		  "lastChangeDateTime": "Fri, 22 Mar 2019 00:00:00 GMT",
		  "referenceDate": "Tue, 12 Mar 2019 00:00:00 GMT"
		}
	  ],
	  "_links": {
		"balances": {
		  "href": "/api/v1/accounts/057db59e-61d0-9d37-d28a-cebc79c215ca/balances"
		},
		"transactions": {
		  "href": "/api/v1/accounts/057db59e-61d0-9d37-d28a-cebc79c215ca/transactions"
		}
	  }
	}
}

For other possible return codes, see the API DOCUMENTATION page.

go to top

Read balance information

This method can only be accessed with a specific consent, where the corresponding account was provided specifically in the balances array or AllPsd2 was specified.

Headers

The following headers must be provided

Header	Example	Description
Content-Type	application/json
Date	Fri, 09 Apr 2021 15:12:03 GMT	The date of the request.
X-Request-ID	2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329	An identifier chosen by the TPP to identify the request. This id is passed back in the X-Request-ID header of the response
Authorization	Bearer ACCESS_TOKEN	Replace ACCESS_TOKEN with the access token obtained in a previous step.
Accept	application/json

Perform request

Endpoint	https://api.xs2a.bngbank.nl/api/v1/accounts/ACCOUNT_ID/balances	Replace ACCOUNT_ID with the id of an account, for example: 057db59e-61d0-9d37-d28a-cebc79c215ca. Please note that this is not the IBAN of the account but the resourceId as returned by the read account list API. This accountId is specific to the consent being used. This means that for another consent, the account has to be addressed by another acountId.
Method	GET

If the call was successful, a 200 status is returned along with the response body. See below an example of a response.

{
	"account": {
	  "iban": "NL34BNGT5532530633",
	  "currency": "EUR"
	},
	"balances": [
	  {
		"balanceAmount": {
		  "currency": "EUR",
		  "amount": "13000.00"
		},
		"balanceType": "Expected",
		"creditLimitIncluded": false,
		"lastChangeDateTime": "Fri, 22 Mar 2019 13:38:21 GMT",
		"referenceDate": "Thu, 21 Mar 2019 00:00:00 GMT"
	  },
	  {
		"balanceAmount": {
		  "currency": "EUR",
		  "amount": "13000.00"
		},
		"balanceType": "ClosingBooked",
		"creditLimitIncluded": false,
		"lastChangeDateTime": "Fri, 22 Mar 2019 00:00:00 GMT",
		"referenceDate": "Tue, 12 Mar 2019 00:00:00 GMT"
	  }
	]
}

For other possible return codes, see the API DOCUMENTATION page.

go to top

Read transaction list

This method can only be accessed with a specific consent, where the corresponding account was provided specifically in the transactions array or AllPsd2 was specified.

Headers

The following headers must be provided

Header	Example	Description
Content-Type	application/json
Date	Fri, 09 Apr 2021 15:12:03 GMT	The date of the request.
X-Request-ID	2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329	An identifier chosen by the TPP to identify the request. This id is passed back in the X-Request-ID header of the response
Authorization	Bearer ACCESS_TOKEN	Replace ACCESS_TOKEN with the access token obtained in a previous step.
Accept	application/json

QueryString

The following query string parameters can be provided

Parameter	Example	Description	Condition
dateFrom	2019-01-01	Starting date (inclusive the date dateFrom) of the transaction list	Mandatory
dateTo	2021-04-09	End date (inclusive the data dateTo) of the transaction list, default is "now" if not given.	Optional
bookingStatus	both	Permitted codes are "booked", "pending" and "both".	Mandatory
withBalance	true	If contained, this function reads the list of transactions including the booking balance.	Optional
download	true	If contained and has the value "true", this function will return a application/octet stream containing a ZIP-file with a JSON-file included that contains the transactions.	Optional

Perform request

Endpoint	https://api.xs2a.bngbank.nl/api/v1/accounts/ACCOUNT_ID/transactions?dateFrom=DATE_FROM&bookingStatus=BOOKING_STATUS	Replace ACCOUNT_ID with the id of an account, for example: 057db59e-61d0-9d37-d28a-cebc79c215ca. Please note that this is not the IBAN of the account but the resourceId as returned by the read account list API. This accountId is specific to the consent being used. This means that for another consent, the account has to be addressed by another acountId. Replace DATE_FROM and BOOKING_STATUS with there respective values. Additional query string parameters can be provided.
Method	GET

If the call was successful, a 200 status is returned along with the response body. Note that the response will be paginated if many results are returned. Links to other pages will be provided. Depending if the query parameter "download=true"was given, the response will be a application/octet file stream containing a .zip file containing a .json file. See below an example of a response else application/json as below.

{
	"account": {
	  "iban": "NL34BNGT5532530633"
	},
	"transactions": {
	  "booked": [
		{
		  "transactionId": "d356aa7b-0d1b-4a07-b255-5eb2a6da205d",
		  "entryReference": "229c5baad7f142a7b7a3450934477fee",
		  "endToEndId": "88a34968a6b74874b7bb5e58c89f07ce",
		  "mandateId": "",
		  "checkId": "",
		  "creditorId": "",
		  "bookingDate": "2019-03-26",
		  "valueDate": "1900-01-01",
		  "transactionAmount": "-281.49",
		  "exchangeRate": "",
		  "creditorName": "Accountname 134",
		  "creditorAccount": {
			"iban": "NL11BNGT94126519629979",
			"currency": "EUR"
		  },
		  "ultimateCreditor": "",
		  "debtorName": "",
		  "remittanceInformationUnstructured": "Description 134",
		  "remittanceInformationStructured": "/TRTP/Vertaling Bookcode/REMI/Additionele gegevens",
		  "purposeCode": "",
		  "bankTransactionCode": "",
		  "proprietaryBankTransactionCode": "",
		  "_links": {
			"transactionDetails": {
			  "href": "/api/v1/accounts/4df6fce0-6ef6-8d16-7a72-31b7e854b2fd/transactions/d356aa7b-0d1b-4a07-b255-5eb2a6da205d"
			}
		  }
		},
		{
		  "transactionId": "3116faa7-1d90-4be4-800d-b8171f49f318",
		  "entryReference": "e0c6da1ba8fd4312ad1bd66413120b26",
		  "endToEndId": "65724c3af9fc42d591bfba0d0eef8e50",
		  "mandateId": "",
		  "checkId": "",
		  "creditorId": "",
		  "bookingDate": "2019-03-25",
		  "valueDate": "1900-01-01",
		  "transactionAmount": "-4075.44",
		  "exchangeRate": "",
		  "creditorName": "Accountname 157",
		  "creditorAccount": {
			"iban": "NL92BNGT94126584454106",
			"currency": "EUR"
		  },
		  "ultimateCreditor": "",
		  "debtorName": "",
		  "remittanceInformationUnstructured": "Description 157",
		  "remittanceInformationStructured": "/TRTP/Vertaling Bookcode/REMI/Additionele gegevens",
		  "purposeCode": "",
		  "bankTransactionCode": "",
		  "proprietaryBankTransactionCode": "",
		  "_links": {
			"transactionDetails": {
			  "href": "/api/v1/accounts/4df6fce0-6ef6-8d16-7a72-31b7e854b2fd/transactions/3116faa7-1d90-4be4-800d-b8171f49f318"
			}
		  }
		}
	  ],
	  "pending": [
		{
		  "transactionId": "6590856b-9ea5-42ee-b5df-a32e1b14d13a",
		  "entryReference": "b434d5902ccd4dd998d17b8c67e5b73f",
		  "endToEndId": "04cba0935fe34917bd7b361832c13a2d",
		  "mandateId": "",
		  "checkId": "",
		  "creditorId": "",
		  "bookingDate": "2019-04-04",
		  "valueDate": "1900-01-01",
		  "transactionAmount": "-5639.74",
		  "exchangeRate": "",
		  "creditorName": "Accountname 181",
		  "creditorAccount": {
			"iban": "NL96BNGT94126599189983",
			"currency": "EUR"
		  },
		  "ultimateCreditor": "",
		  "debtorName": "",
		  "remittanceInformationUnstructured": "Description 181",
		  "remittanceInformationStructured": "/TRTP/Vertaling Bookcode/REMI/Additionele gegevens",
		  "purposeCode": "",
		  "bankTransactionCode": "",
		  "proprietaryBankTransactionCode": "",
		  "_links": {
			"transactionDetails": {
			  "href": "/api/v1/accounts/4df6fce0-6ef6-8d16-7a72-31b7e854b2fd/transactions/6590856b-9ea5-42ee-b5df-a32e1b14d13a"
			}
		  }
		},
		{
		  "transactionId": "a8576939-e43b-4036-85f0-1b1f51434e91",
		  "entryReference": "c73fcb1ab563458ab810fefb197e1558",
		  "endToEndId": "05173b678ef24e9190759241b375e67c",
		  "mandateId": "",
		  "checkId": "",
		  "creditorId": "",
		  "bookingDate": "2019-04-03",
		  "valueDate": "1900-01-01",
		  "transactionAmount": "-6982.53",
		  "exchangeRate": "",
		  "creditorName": "Accountname 101",
		  "creditorAccount": {
			"iban": "NL40BNGT94126514902841",
			"currency": "EUR"
		  },
		  "ultimateCreditor": "",
		  "debtorName": "",
		  "remittanceInformationUnstructured": "Description 101",
		  "remittanceInformationStructured": "/TRTP/Vertaling Bookcode/REMI/Additionele gegevens",
		  "purposeCode": "",
		  "bankTransactionCode": "",
		  "proprietaryBankTransactionCode": "",
		  "_links": {
			"transactionDetails": {
			  "href": "/api/v1/accounts/4df6fce0-6ef6-8d16-7a72-31b7e854b2fd/transactions/a8576939-e43b-4036-85f0-1b1f51434e91"
			}
		  }
		}
	  ],
	  "_links": {
		"account": {
		  "href": "/api/v1/accounts/4df6fce0-6ef6-8d16-7a72-31b7e854b2fd"
		},
		"first": {
		  "href": "/api/v1/accounts/4df6fce0-6ef6-8d16-7a72-31b7e854b2fd/transactions?dateFrom=2019-01-01&dateTo=&bookingStatus=Both&withBalance=true&page=1"
		},
		"next": {
		  "href": "/api/v1/accounts/4df6fce0-6ef6-8d16-7a72-31b7e854b2fd/transactions?dateFrom=2019-01-01&dateTo=&bookingStatus=Both&withBalance=true&page=2"
		},
		"last": {
		  "href": "/api/v1/accounts/4df6fce0-6ef6-8d16-7a72-31b7e854b2fd/transactions?dateFrom=2019-01-01&dateTo=&bookingStatus=Both&withBalance=true&page=21"
		}
	  }
	},
	"balances": [
	  {
		"balanceAmount": {
		  "currency": "EUR",
		  "amount": "13000.00"
		},
		"balanceType": "Expected",
		"creditLimitIncluded": false,
		"lastChangeDateTime": "Fri, 05 Apr 2019 10:53:43 GMT"
	  },
	  {
		"balanceAmount": {
		  "currency": "EUR",
		  "amount": "13000.00"
		},
		"balanceType": "ClosingBooked",
		"creditLimitIncluded": false,
		"lastChangeDateTime": "Fri, 05 Apr 2019 00:00:00 GMT"
	  }
	],
	"_links": {}
	}
}

For other possible return codes, see the API DOCUMENTATION page.

go to top

Read transaction details

This method can only be accessed with a specific consent, where the corresponding account was provided specifically in the transactions array or AllPsd2 was specified.

Headers

The following headers must be provided

Header	Example	Description
Content-Type	application/json
Date	Fri, 09 Apr 2021 15:12:03 GMT	The date of the request.
X-Request-ID	2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329	An identifier chosen by the TPP to identify the request. This id is passed back in the X-Request-ID header of the response
Authorization	Bearer ACCESS_TOKEN	Replace ACCESS_TOKEN with the access token obtained in a previous step.
Accept	application/json

Perform request

Endpoint	https://api.xs2a.bngbank.nl/api/v1/accounts/ACCOUNT_ID/transactions/TRANSACTION_ID	Replace ACCOUNT_ID with the id of an account, for example: 057db59e-61d0-9d37-d28a-cebc79c215ca. Please note that this is not the IBAN of the account but the resourceId as returned by the read account list API. This accountId is specific to the consent being used. This means that for another consent, the account has to be addressed by another acountId. Replace TRANSACTION_ID with the transactionId from the read transaction list response of the transaction to retrieve the details for.
Method	GET

If the call was successful, a 200 status is returned along with the response body. See below an example of a response.

{
	"transactionDetails": {
	  "transactionId": "6590856b-9ea5-42ee-b5df-a32e1b14d13a",
	  "entryReference": "b434d5902ccd4dd998d17b8c67e5b73f",
	  "endToEndId": "04cba0935fe34917bd7b361832c13a2d",
	  "mandateId": "",
	  "checkId": "",
	  "creditorId": "",
	  "bookingDate": "2019-04-04",
	  "valueDate": "1900-01-01",
	  "transactionAmount": "-5639.74",
	  "exchangeRate": "",
	  "creditorName": "Accountname 181",
	  "creditorAccount": {
		"iban": "NL96BNGT94126599189983",
		"currency": "EUR"
	  },
	  "ultimateCreditor": "",
	  "debtorName": "",
	  "remittanceInformationUnstructured": "Description 181",
	  "remittanceInformationStructured": "/TRTP/Vertaling Bookcode/REMI/Additionele gegevens",
	  "purposeCode": "",
	  "bankTransactionCode": "",
	  "proprietaryBankTransactionCode": ""
	}
}

For other possible return codes, see the API DOCUMENTATION page.

go to top

Read account statements

With this method account statements in camt.053 format can be downloaded. Note that only booked and statements of periods before today can be downloaded.

This method can only be accessed with a specific consent, where the corresponding account was provided specifically in the transactions array or AllPsd2 was specified.

Headers

The following headers must be provided

Header	Example	Description
Content-Type	application/json
Date	Fri, 09 Apr 2021 15:12:03 GMT	The date of the request.
X-Request-ID	2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329	An identifier chosen by the TPP to identify the request. This id is passed back in the X-Request-ID header of the response
Authorization	Bearer ACCESS_TOKEN	Replace ACCESS_TOKEN with the access token obtained in a previous step.
Accept	application/octet-stream

QueryString

The following query string parameters can be provided

Parameter	Example	Description	Condition
dateFrom	2019-01-01	Starting date (inclusive the date dateFrom) of the transaction list	Mandatory
dateTo	2021-04-09	End date (inclusive the data dateTo) of the transaction list, default is "now" if not given.	Optional
bookingStatus	booked	Permitted codes are "booked".	Mandatory

Perform request

Endpoint	https://api.xs2a.bngbank.nl/api/v1/accounts/ACCOUNT_ID/statements	Replace ACCOUNT_ID with the id of an account, for example: 057db59e-61d0-9d37-d28a-cebc79c215ca. Please note that this is not the IBAN of the account but the resourceId as returned by the read account list API. This accountId is specific to the consent being used. This means that for another consent, the account has to be addressed by another acountId.
Method	GET

If the call was successful, a 200 status is returned along with a application/octet file stream. The resulting file will be a .zip file containing camt.053 XML statements for each day in the given period.

For other possible return codes, see the API DOCUMENTATION page.

go to top

Delete consent

To delete a consent, a consent-id as well as an access_token is required, please see previous steps for directions on how to obtain those.

After calling this API, the status of the consent will be set to "terminatedByTpp", the consent can no longer be used.

Headers

The following headers must be provided

Header	Example	Description
Content-Type	application/json
Date	Fri, 09 Apr 2021 15:12:03 GMT	The date of the request.
X-Request-ID	2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329	An identifier chosen by the TPP to identify the request. This id is passed back in the X-Request-ID header of the response
Authorization	Bearer ACCESS_TOKEN	Replace ACCESS_TOKEN with the access token obtained in a previous step.
Accept	application/json
Digest	SHA-256=spt...rrI	Digest of the body
Signature	keyId=\"SN=...Yiow==\	The signature of the request, see Signature setup
TPP-Signature-Certificate	-----BEGIN CERTIFICATE-----MII...UjY=-----END CERTIFICATE-----	The certificate used to sign the request.

Perform request

Endpoint	https://api.xs2a.bngbank.nl/api/v1/consents/CONSENT_ID	Replace CONSENT_ID with the id of a consent, for example: 2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329
Method	DELETE

If the call was successful, an emtpy body and status 204 is returned.

For other possible return codes, see the API DOCUMENTATION page.

go to top