accounts
Accounts

BUUT - Account Information (PSD2) 1.0.0

  • Live

Retrieve information from BUUT account, such as: transactions, balance, and name of the account holder.

Tutorial

This API provides Account Information (PSD2) Service and can be used by third-party payment service providers to retrieve information from BUUT.

How it works

How the Account Information (PSD2) API works

  1. Request consent from the BUUT account holder through the consent application.
  2. Retrieve account information.

The consent application

The consent application is used to obtain consent from an BUUT account holder, and grant you with third-party access to execute a registered payment, or to access account information. This a so-called redirect. In the consent application, the BUUT client can review the account number and the type of access granted to you.

The account holder consent process consists of three steps:

  1. Log on.
  2. Check requested access to account.
  3. Authorization.

The BUUT client can either authorize or cancel the requested authorization. All account information consents are valid for up to a maximum of 180 days. Consent can be given using the consent application by users of BUUT Mobile banking app. All previously given consents for 90 days remain unchanged, the new duration only applies to new consents. For testing purposes the validity of the consent in sandbox is set to 7 days. This will allow you to validate the consent expiry scenario as well as testing receiving multiple days of account data.

Accessing consent application

To access the consent application through OAuth server:

  1. Select account for which you need to authorize access. The consent application uses Strong Customer Authentication (SCA).
  2. Click "Finish" button. This completes the consent and will re-direct back to the 3rd party URL.

Authorization Code:

The consent application is visible to the account owner only. It provides you with an access code for the requested authorization using an OAuth 2.0 authorization code process. Authorization is a grant to an account for one or multiple scopes. Scopes in the authorization code process

A scope defines the type of access. For account information there are only read scopes. Here are some rules on how scopes can be combined in the authorization code:

  1. Scopes for different products can be combined; in specific scenario like checking for transaction status after making payments, but the token should have valid scopes.
  2. Write scopes can be combined with read scopes.
  3. Write scopes cannot be combined with other write scopes.
  4. Delete scopes cannot be combined with other scopes.

Scopes are as follows

  • "buut:account:details:read",
  • "buut:account:balance:read",
  • "buut:account:transaction:read",
  • "buut:account:funds:read",
  • "buut:account:all:read",

Requirements

To use this API in a production environment, you must have the following:

PSD2 access:

  1. A PSD2 license for payment initiation.
  2. An EIDAS certificate.

License:

To use this API in a production environment, or if you require TPP access to BUUT accounts, you must have a PSD2 license from a local competent authority. In the Netherlands, this is De Nederlandsche Bank (DNB).

  1. EIDAS certificate
  2. BUUT accepts Qualified Website Authentication Certificates (QWAC) from Qualified Trusted Service Providers (QSTPs) that are on the trusted list with CEF Digital only. This certificate is used for identification, and is also required for OAuth authorization when accessing APIs.

Note: Inline with the PSD2 technical standard, wildcards are not permitted in certificates.

Sandbox access

To use this API in the sandbox environment, complete the following steps: To get access to sandbox:

  1. Register and create an account:
    1. Click Sign up.
    2. Enter your details, and click Create new account.
    3. Developer Support will send you an activation link by email.
    4. Click the activation link.
  2. Create an register application:
    1. Log in to your account.
    2. In the left-side navigation bar, click My Apps.
    3. Click Add app.
    4. In the App name field, enter a name for your application.
    5. In the APIs field, select BUUT - Account Information (PSD2), and click Add app.

Sandbox access details

Use the following credentials for the sandbox:

Attribute Value for Sandbox
client_id TPP_test
API-Key The API Key for your app from the Developer Portal
redirect_uri https://localhost/auth
Certificate files:
Download public certificate: Download
Download private key: Download

Production access

Important: To use this API in a production environment, you must have a license. For more information, see Requirements.

To get access to production:

  1. Log in to your account.
  2. In the left-side navigation, click Apps.
  3. Click Request Production Access.
  4. Select the API category that you want to request production access on.

    Note: It is not possible to request production access for multiple API categories in one request.

  5. Fill in the form, and click Submit.
  6. You receive a confirmation email and ticket-ID.
  7. ABN AMRO Developer Support validates the form, and if necessary contacts you.
  8. When the setup is complete, ABN AMRO Developer Support contacts you and supplies you with a client_id.
  9. A new App is added in Apps. This new app contains your API key.

Note: It is not possible for account holders to get API access on their own accounts.

Production access details

How to use this API

This instruction describes how to connect an application to the API in the sandbox environment, and test API functionality in production-like sandbox environment.

Note: Before you start this process, you must complete the steps described in Sandbox access.

This instruction describes the functionality of Account Information (PSD2) API for BUUT and also how to connect to the sandbox environment.

**Note:**In the production environment, the PSD2 compliant EIDAS QWAC SSL certificate, production redirect-uri, and production API-Key are used. You can get these post onboarding into the ABN AMRO dev-portal.

Step 1 - Obtain consent

The account holder will need to provide the access to the third party through consent flow in the BUUT mobile application.

Prerequisites:

  1. Redirect url from Third Party that wants to obtain user consent for Account Information service
  2. Api-key for accessing the AIS services via the ABN AMRO Developer Portal

Complete steps below to obtain consent:

  1. Use the Ping-Oauth flow (see step 2) to get the redirectUrl to BUUT. This link can be used to get into the app (via deeplink or QR scanning).
    • This QR is valid for 15 mins, once this expires TPP has to regenerate one to continue the flow.
  2. The BUUT account holder can then deeplink or scan QR to open the app.
  3. Log on BUUT mobile banking application using SCA (Strong Customer Authentication)
  4. User grants consent to Account Information Service from Third Party
  5. User can manage consent in mobile banking application (check status or revoke consent at any point in time)

Note: All account information consents are valid for up to a maximum of 180 days. Consent can also be given by users via the BUUT mobile banking app. All previously given consents if not refreshed are revoked for post 180 days.

Scopes are as follows:

Operation Request for scope
Read details of account (such as address) buut:account:details:read
Read the transactions and/or activities on an account buut:account:transaction:read
Read the balance of account buut:account:balance:read
Check availability of funds on an account buut:account:funds:read

Notes:

  • When using the attributes please make sure the total length of the URL will not exceed 256 characters.
  • When registering an redirect URL please note app deep linking requires a browser to be launched on the device. For optimal user experience use a internet URL or a universal links.
  • In the sandbox, a simplified version of the consent application is used. This application replicates the mobile APP authorization in favor of easier development.

Sample request

The following example will start the consent application. In the consent application, the BUUT client reviews and authorizes the requested account access. As a result, you will receive an access code. This is used to get access to the clients account.

    https://security-ifs-test.nl.eu.abnamro.com/as/authorization.oauth2?pfidpadapterid=ad..Pablo&scope=buut:account:all:read buut:account:balance:read buut:account:details:read&response_type=code&client_id=pablo_tpp_client&bank=PABLO

Sample response

In the response headers, you will receive a location to start the create-consent flow in the BUUT app. This header is under the key “Location” which must be exchanged within 60 seconds for an access_token and a refresh_token. This is described in the next step.

Sample url looks like this:

    https://acc.buut.com/psd/ais/qr?resumePath=/as/chOQgvXRB8/resume/as/authorization.ping&allowInteraction=true&reauth=false&connectionId=pablo_tpp_client&REF=29419705D2E980F46E5BB4EB95F5B7A4815A5290F8A2BE4DCDD618983951&pfidpadapterid=ad..Pablo&scope=buut:account:all:read+buut:account:balance:read+buut:account:details:read&response_type=code&client_id=pablo_tpp_client&bank=PABLO

Post following the consent-flow in the BUUT application, the user session resumes with the authorisation code. This can be done by Ping, towards the TPP.

Sample request

In the response headers, you will receive a location to start the create-consent flow in the BUUT app. This header is under the key “Location” which must be exchanged within 60 seconds for an access_token and a refresh_token. This is described in the next step.

Sample url looks like this:

 https://acc.buut.com/psd/ais/qr?resumePath=/as/chOQgvXRB8/resume/as/authorization.ping&allowInteraction=true&reauth=false&connectionId=pablo_tpp_client&REF=29419705D2E980F46E5BB4EB95F5B7A4815A5290F8A2BE4DCDD618983951&pfidpadapterid=ad..Pablo&scope=buut:account:all:read+buut:account:balance:read+buut:account:details:read&response_type=code&client_id=pablo_tpp_client&bank=PABLO

Post following the consent-flow in the BUUT application, the user session resumes with the authorization code. This can be done by Ping, towards the TPP.

Sample request

 https://tpp--host-url/pablo_tpp_client?code=6PREKIdI-3jOsZCaQ-zgRwROCeCUPpXzmsoYmDlR

Step 2 - Exchange the access token

The authorization code obtained in Step 1 must be exchanged within 60 seconds for an access_token and a refresh_token. The access_token is used to access the API, and is valid for 2 hours. When the access_token has expired, the refresh_token can be used to obtain a new access_token and refresh_token. For more information, see Refresh the access token.

Request attributes

Attribute Description
grant_type Indicates which type of authorization is used. It must contain 'Authorization_code'.
code Authorization code from Step 1.
redirect_uri This field is mandatory when redirect_uri is used in Step 1.

Sample request

     curl -X POST -k https://security-ifs-test.connect.abnamro.com/as/token.oauth2/
     -u  pablo_tpp_client:xxx\
     -H 'Cache-Control: no-cache' \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -d 'grant_type=authorization_code&client_id=TPP_test&code=9C6UrsGZ0Z3XJymRAOAgl7hKPLlWKUo9GBfMQQEs&scope=account:balance:read payment:batch:read'

Sample response

      {
        "access_token": "{GPgYglX4sO1WhzfChx4tmjr4y7Qg}",
        "refresh_token": "{UHjIAzBZfLGh4dLm8cvEcH6d8BrOmCZXumOpznQBP1}",
        "token_type": "Bearer",
        "expires_in": 7193
      }

Note: The access_token is needed to access the account.

Step 3 - Check authorization using consent information

To access an account, you must have an access_token, obtained in Step 2 and the accountNumber which you have been authorized to access. By requesting consent information, the IBAN of the account number associated with the access_token received in Step 2 can be requested. Scopes are also returned in the response. The data returned in this step does not change after the initial retrieval. Therefore the amount of times this step can be executed is twice per consent.

Request attributes:

Attribute Description
authorization Use the access_token received in Step 2 and send this as a Bearer token.

Sample request

    curl -X GET -k https://api-sandbox.abnamro.com/buut/accounts/v1
      -H 'Accept: application/json' \
      -H 'API-Key: X1QTWZre0fnW72l263yrhAWB2FDwx3tg' \
      -H 'Tpp-Id: pablo_tpp_client ' \
      -H 'Authorization: Bearer GPgYglX4sO1WhzfChx4tmjr4y7Qg'

Sample response

     
      {  accounts : [
      "accountId " : " tYIAyB884ByctX_PTeYJ9",
          "accountNumber ": "NL12ABNA9999876523",
      ] }

Use the accountId with the access_token and refresh_token to retrieve account information (details, balances.transactions) in the next step.

Step 4 - Call the Account Information (PSD2) API

In this step we interact with the Account Information API (PSD2) and its functionality.

  • Get consent information: Provides authorization information on a resource.
  • Get account details: Retrieves the details of the account, such as: Currency and account holder name.
  • Get balance: Retrieves Book balance of the account and currency.
  • Get transactions: Lists transactions for all transactions.
  • Get funds: Verifies if the amount specified in the request is available in the account. This includes any credit line.
  • Refresh the access token: The access token is valid for 2 hours.

TelephoneNeed help?

Check the frequently asked questions or contact us. We are happy to help.
 

Get support Learn the basics