Menu Close
Developer Portal Currently viewing the Sandbox environment

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:

Test data

To test scenarios, test data is required. Just like in the production environment, users can only perform actions on particular accounts. For the sandbox testusers exist and can be used when redirecting. The login code is always 123456. Please refer to the table below when composing test cases.

Account number Users Details Balances
NL34BNGT5532530633
(many transactions)		 testuser01
testuser02 		Name: Customer 1 Account A
Product: Betaalrekening
CashAccountType: CACC
Status: enabled
Bic: BNGHNL2G
LinkedAccounts: This field is not supported
Usage: ORGA
Details: Is top account
 Closing booked balance
Balance: 250,00
CreditLimitIncluded: false
LastChangeDateTime: Beginning of current day
ReferenceDate: This field is not supported
LastCommitedTransaction: Bank reference 5532530633

Expected balance
Balance: 100,00
CreditLimitIncluded: false
LastChangeDateTime: Later than beginning of current day
ReferenceDate: This field is not supported
LastCommitedTransaction: Bank reference 5532530633D
NL36BNGT6726067582
(many transactions)		 testuser01
testuser02 		Name: Customer 1 Account B
Product: Betaalrekening
CashAccountType: CACC
Status: deleted
Bic: BNGHNL2G
LinkedAccounts: This field is not supported
Usage: ORGA
Details: Is subsidiary account
 Closing booked balance
Balance: 250,00
CreditLimitIncluded: false
LastChangeDateTime: Beginning of current day
ReferenceDate: This field is not supported
LastCommitedTransaction: Bank reference 6726067582

Expected balance
Balance: 100,00
CreditLimitIncluded: false
LastChangeDateTime: Later than beginning of current day
ReferenceDate: This field is not supported
LastCommitedTransaction: Bank reference 6726067582D
NL77BNGT2034202452 testuser03
testuser04
testuser05 		Name: Customer 2 Account A
Product: Betaalrekening
CashAccountType: CACC
Status: enabled
Bic: BNGHNL2G
LinkedAccounts: This field is not supported
Usage: ORGA
Details: Is top account
 Closing booked balance
Balance: 250,00
CreditLimitIncluded: false
LastChangeDateTime: Beginning of current day
ReferenceDate: This field is not supported
LastCommitedTransaction: Bank reference 2034202452

Expected balance
Balance: 100,00
CreditLimitIncluded: false
LastChangeDateTime: Later than beginning of current day
ReferenceDate: This field is not supported
LastCommitedTransaction: Bank reference 2034202452D
NL57BNGT0377231061 testuser03
testuser04
testuser05 		Name: Customer 2 Account B
Product: Betaalrekening
CashAccountType: CACC
Status: enabled
Bic: BNGHNL2G
LinkedAccounts: This field is not supported
Usage: ORGA
Details: Is subsidiary account
 Closing booked balance
Balance: 250,00
CreditLimitIncluded: false
LastChangeDateTime: Beginning of current day
ReferenceDate: This field is not supported
LastCommitedTransaction: Bank reference 0377231061

Expected balance
Balance: 100,00
CreditLimitIncluded: false
LastChangeDateTime: Later than beginning of current day
ReferenceDate: This field is not supported
LastCommitedTransaction: Bank reference 0377231061D
NL19BNGT0741337541 testuser03 Name: Customer 2 Account C
Product: Betaalrekening
CashAccountType: CACC
Status: enabled
Bic: BNGHNL2G
LinkedAccounts: This field is not supported
Usage: ORGA
Details: Is subsidiary account
 Closing booked balance
Balance: 250,00
CreditLimitIncluded: false
LastChangeDateTime: Beginning of current day
ReferenceDate: This field is not supported
LastCommitedTransaction: Bank reference 0741337541

Expected balance
Balance: 100,00
CreditLimitIncluded: false
LastChangeDateTime: Later than beginning of current day
ReferenceDate: This field is not supported
LastCommitedTransaction: Bank reference 0741337541D
NL26BNGT0500209189 testuser03 Name: Customer 2 Account D
Product: Betaalrekening
CashAccountType: CACC
Status: enabled
Bic: BNGHNL2G
LinkedAccounts: This field is not supported
Usage: ORGA
Details: Is subsidiary account
 Closing booked balance
Balance: 250,00
CreditLimitIncluded: false
LastChangeDateTime: Beginning of current day
ReferenceDate: This field is not supported
LastCommitedTransaction: Bank reference 0500209189

Expected balance
Balance: 100,00
CreditLimitIncluded: false
LastChangeDateTime: Later than beginning of current day
ReferenceDate: This field is not supported
LastCommitedTransaction: Bank reference 0500209189D
NL81BNGT1330425185 testuser06
testuser07 		Name: Customer 3 Account A
Product: Betaalrekening
CashAccountType: CACC
Status: enabled
Bic: BNGHNL2G
LinkedAccounts: This field is not supported
Usage: ORGA
Details: Is top account
 Closing booked balance
Balance: 250,00
CreditLimitIncluded: false
LastChangeDateTime: Beginning of current day
ReferenceDate: This field is not supported
LastCommitedTransaction: Bank reference 1330425185

Expected balance
Balance: 100,00
CreditLimitIncluded: false
LastChangeDateTime: Later than beginning of current day
ReferenceDate: This field is not supported
LastCommitedTransaction: Bank reference 1330425185D

go to top

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-Typeapplication/jsonOnly application/json is supported.
DateFri, 09 Apr 2021 15:12:03 GMTThe date of the request.
X-Request-ID2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329An 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-Address123.12.12.12The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP.
PSU-User-AgentChrome OSThe forwarded Agent header field of the HTTP request between PSU and TPP, if available.
PSU-Geo-Location51.20,4.2The forwarded Geo Location of the corresponding http request between PSU and TPP if available.
TPP-Redirect-URIhttps://tpp.com/some-redirectURI of the TPP, where the transaction flow shall be redirected to after a Redirect. This field is currently optional.
Acceptapplication/jsonThe content type the client is able to understand. Must be application/json.
DigestSHA-256=262LaJygmoifcl5pVlhlUXW1QNUfGhfryy03ud/uxMs=Digest of the body of the request. This field is mandatory, because the ASPSP mandates the use of a signature.
SignatureA signature of the request. The ASPSP mandates the use of a signature.
TPP-Signature-CertificateThe 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://api.xs2a-sandbox.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-Typeapplication/x-www-form-urlencoded
Acceptapplication/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-Typeapplication/json
DateFri, 09 Apr 2021 15:12:03 GMTThe date of the request.
X-Request-ID2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329An identifier chosen by the TPP to identify the request. This id is passed back in the X-Request-ID header of the response
AuthorizationBearer ACCESS_TOKENReplace ACCESS_TOKEN with the access token obtained in a previous step.
Acceptapplication/json
DigestSHA-256=spt...rrIDigest of the body
SignaturekeyId=\"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-Typeapplication/json
DateFri, 09 Apr 2021 15:12:03 GMTThe date of the request.
X-Request-ID2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329An identifier chosen by the TPP to identify the request. This id is passed back in the X-Request-ID header of the response
AuthorizationBearer ACCESS_TOKENReplace ACCESS_TOKEN with the access token obtained in a previous step.
Acceptapplication/json
DigestSHA-256=spt...rrIDigest of the body
SignaturekeyId=\"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-Typeapplication/json
DateFri, 09 Apr 2021 15:12:03 GMTThe date of the request.
X-Request-ID2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329An identifier chosen by the TPP to identify the request. This id is passed back in the X-Request-ID header of the response
AuthorizationBearer ACCESS_TOKENReplace ACCESS_TOKEN with the access token obtained in a previous step.
Acceptapplication/json
DigestSHA-256=spt...rrIDigest of the body
SignaturekeyId=\"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-Typeapplication/json
DateFri, 09 Apr 2021 15:12:03 GMTThe date of the request.
X-Request-ID2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329An identifier chosen by the TPP to identify the request. This id is passed back in the X-Request-ID header of the response
AuthorizationBearer ACCESS_TOKENReplace ACCESS_TOKEN with the access token obtained in a previous step.
Acceptapplication/json
DigestSHA-256=spt...rrIDigest of the body
SignaturekeyId=\"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-Typeapplication/json
DateFri, 09 Apr 2021 15:12:03 GMTThe date of the request.
X-Request-ID2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329An identifier chosen by the TPP to identify the request. This id is passed back in the X-Request-ID header of the response
AuthorizationBearer ACCESS_TOKENReplace ACCESS_TOKEN with the access token obtained in a previous step.
Acceptapplication/json

QueryString

The following query string parameters can be provided

Parameter Example Description Condition
withBalancetrueBoolean 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-Typeapplication/json
DateFri, 09 Apr 2021 15:12:03 GMTThe date of the request.
X-Request-ID2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329An identifier chosen by the TPP to identify the request. This id is passed back in the X-Request-ID header of the response
AuthorizationBearer ACCESS_TOKENReplace ACCESS_TOKEN with the access token obtained in a previous step.
Acceptapplication/json

QueryString

The following query string parameters can be provided

Parameter Example Description Condition
withBalancetrueBoolean 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-Typeapplication/json
DateFri, 09 Apr 2021 15:12:03 GMTThe date of the request.
X-Request-ID2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329An identifier chosen by the TPP to identify the request. This id is passed back in the X-Request-ID header of the response
AuthorizationBearer ACCESS_TOKENReplace ACCESS_TOKEN with the access token obtained in a previous step.
Acceptapplication/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-Typeapplication/json
DateFri, 09 Apr 2021 15:12:03 GMTThe date of the request.
X-Request-ID2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329An identifier chosen by the TPP to identify the request. This id is passed back in the X-Request-ID header of the response
AuthorizationBearer ACCESS_TOKENReplace ACCESS_TOKEN with the access token obtained in a previous step.
Acceptapplication/json

QueryString

The following query string parameters can be provided

Parameter Example Description Condition
dateFrom2019-01-01Starting date (inclusive the date dateFrom) of the transaction listMandatory
dateTo2021-04-09End date (inclusive the data dateTo) of the transaction list, default is "now" if not given.Optional
bookingStatusbothPermitted codes are "booked", "pending" and "both".Mandatory
withBalancetrueIf contained, this function reads the list of transactions including the booking balance.Optional
downloadtrueIf 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-Typeapplication/json
DateFri, 09 Apr 2021 15:12:03 GMTThe date of the request.
X-Request-ID2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329An identifier chosen by the TPP to identify the request. This id is passed back in the X-Request-ID header of the response
AuthorizationBearer ACCESS_TOKENReplace ACCESS_TOKEN with the access token obtained in a previous step.
Acceptapplication/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-Typeapplication/json
DateFri, 09 Apr 2021 15:12:03 GMTThe date of the request.
X-Request-ID2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329An identifier chosen by the TPP to identify the request. This id is passed back in the X-Request-ID header of the response
AuthorizationBearer ACCESS_TOKENReplace ACCESS_TOKEN with the access token obtained in a previous step.
Acceptapplication/octet-stream

QueryString

The following query string parameters can be provided

Parameter Example Description Condition
dateFrom2019-01-01Starting date (inclusive the date dateFrom) of the transaction listMandatory
dateTo2021-04-09End date (inclusive the data dateTo) of the transaction list, default is "now" if not given.Optional
bookingStatusbookedPermitted 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-Typeapplication/json
DateFri, 09 Apr 2021 15:12:03 GMTThe date of the request.
X-Request-ID2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329An identifier chosen by the TPP to identify the request. This id is passed back in the X-Request-ID header of the response
AuthorizationBearer ACCESS_TOKENReplace ACCESS_TOKEN with the access token obtained in a previous step.
Acceptapplication/json
DigestSHA-256=spt...rrIDigest of the body
SignaturekeyId=\"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