Tutorial

Note: This product is in early access (pilot phase). At this moment the Early Access (pilot phase) of the Business Account Notification API is full.

How the Business Account Notification API works

The Business Account Notification API offers methods to create, read, update, and delete subscriptions for notifications. Each subscription contains a target and will enable notifications for the specified bank account. When a transaction occurs, notifications are sent to this target. The notification contains the subscriptionId and the transaction data for the transaction that triggered the subscription.

What is a webhook

A webhook is an HTTP POST request; they are user-defined HTTP callbacks. Once a certain event occurs, instead of receiving an immediate response to a request, the client specifies a URL to which the response is sent. To receive POST requests on the defined URL, the client must create a web service and accept a TLS-MA connection.

Requirements

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

An ABN AMRO business current account number that is registered in The Netherlands.
A contract for Internet Banking Business or Access Online.
A TLS certificate of the type Organisation Validation (OV) or Extended Validation (EV) from Digicert, Quo Vadis, Sectigo or Entrust without wildcard options.
The organisation name issued on the certificate must correspond to the name of the API contract holder.

Sandbox access

The sandbox and production environments are functionally identical. The sandbox is static, which means that you can perform all operations without making any transactions on an account. None of the operations in the sandbox are persisted and fixed calls and responses are provided.

As the sandbox is not connected to the ABN AMRO backend systems, we offer a number of cURL requests you can perform to simulate sending a notification to your web service.

All operations are available in a Postman collection as well as examples for creating your own notification.

To use the Business Account Notification API in a sandbox environment, complete the following steps:

Step 1: Register and create an account:

Click Sign up.
Enter your details, and click Create new account.
Developer Support will send you an activation link by email.
Click the activation link.

Step 2: Create and register application:

Log in to your account.
In the left-side navigation click Apps.
Click Add app.
In the App name field, enter a name for your application.
In the APIs field, Business Account Notification API, and click Add app.
Complete the steps in How to use this API process.

To provide feedback on this API, see Contact.

Sandbox access details

The following accounts are available to create subscriptions.

IBAN	Description
NL62ABNA9999841479	Commercial account able to create subscriptions. will return subscriptionId: '74e8d426-2e11-4166-b66e-9113ba6a9ea6'.
NL12ABNA9999876523	Commercial account able to create subscriptions. will return subscriptionId: '5438d426-2e11-4166-b66e-9113ba6a1gf2'.

Sandbox URL: https://api-sandbox.abnamro.com
Sandbox token URL: https://auth-mtls-sandbox.abnamro.com

Use the following credentials for the sandbox:

Attribute	Value
client_id	test_client
API-Key	API Key for your application on the Developer Portal

Certificates

Certificate files
Download public certificate: Download
Download private key: Download

Note: The sandbox environment handles functional error scenarios only.

Production access

Note: This product is in closed beta. Details on how to register are shared with closed beta clients only. To register, contact us.

To get access to production:

Log in to your account.
In the left-side navigation, click Apps.
Click Request Production Access.
Select the API category that you want to request production access for.
Fill in the form, and click Submit.
You receive a confirmation email and ticket-ID.
ABN AMRO Developer Support validates the form.
When the form is validated and the setup is complete, ABN AMRO Developer Support contacts you and supplies you with a client_id.
A new app is added in Apps. The new app contains your API key.

Production access details

Production URL: https://api.abnamro.com
Production Token URL: https://auth-mtls.abnamro.com/as/token.oauth2

How to use this API

This instruction describes how to connect an application to the Business Account Notification API in the the sandbox environment.

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

Postman collection

API:Business Account Notification Postman collection

For additional information on how to configure Postman and import a collection, see Postman.

Step 1 - Request an access token

In this step, the OAuth 2.0 client credentials flow is used to obtain access to the Business Account Notification API.

Note: The attributes described in this step are valid in the sandbox environment only. In a production environment, the attributes for requesting the access_token are acquired while registering. To register for the beta production environment, contact us.

Attribute	Value
client_id	test_client
API-Key	The API Key for your application on the Developer Portal
scope	businessaccountnotification:subscriptions:all

Certificates

Certificate files
Download public certificate: Download
Download private key: Download

Sample request

Request an access token using the following sample:

    curl -X POST "https://auth-mtls-sandbox.abnamro.com/as/token.oauth2" \
    -v \
    --cert CertificateCommercial.crt \
    --key PrivateKeyCommercial.key \
    -H 'Cache-Control: no-cache' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'grant_type=client_credentials&client_id=test_client&scope=businessaccountnotification:subscriptions:all'

Sample response

    {
      "token_type": "Bearer",
      "access_token": "exampleToken1234",
      "expires_in": 7199
    }

Step 2 - Call the Business Account Notification API

To create a subscription, using the Authorization token from Step 1, execute: POST Subscription.

This operation creates a new subscription as specified by the body of the request, and returns the subscription with a subscriptionId that can be used to access your subscription.

Create a subscription:

    curl --location --request POST 'https://api-sandbox.abnamro.com/v1/business-account-notification/subscriptions' \
    --header 'Content-Type: application/json' \
    --header 'API-key: {{your_api_key}}' \
    --header 'Authorization: Bearer {{access_token}}' \
    --data-raw '{
      "condition": {
        "accountNumber": "NL62ABNA9999841479"
      },
      "target": {
          "type": "WEBHOOK",
          "address": "https://www.client.com/webhook/invoice/received"
        }
    }'

Step 3 - Test your webhook implementation

Using the provided cURL-command simulate an incoming webhook call. Or fill in your server details into the Postman collection and execute.

Send notification to own servers:

    curl --location --request POST '{YourTarget.url}' \
    --header 'Content-Type: application/json' \
    --data-raw '{
    "message": "Your notification subscription matched with a transaction.",
    "subscriptionId": "74e8d426-2e11-4166-b66e-9113ba6a9ea6",
    "accountNumber": "NL62ABNA9999841479",
    "transaction": {
      "transactionId": "9854L3153139691S1BI",
      "mutationCode": "658",
      "descriptionLines": [
            "SEPA Overboeking",
            "IBAN: NL58ABNA9991330577",
            "BIC: ABNANL2A",
            "Naam:  Opdrachtgever 32",
            "Omschrijving: regel 0005/00244"
      ],
      "transactionTimestamp": "2024-11-27-15:42:20",
      "bookDate": "2024-11-27",
      "balanceAfterMutation": 380403.07,
      "counterPartyAccountNumber": "NL58ABNA9991330577",
      "counterPartyName": "Opdrachtgever 32",
      "amount": 557.35,
      "currency": "EUR",
      "status": "EXECUTED",
      "balanceCreditDebitIndicator": "CRDT",                     
      "creditDebitIndicator": "CRDT"
    },
    "timestamp": "Thu Dec 05 13:41:00 GMT 2024",
    "notificationType": "Account transaction",
    "notificationId": "1c26f7e1-55c6-4992-90e7-512819c2d6f8"
    }'

Step 4 - Update a subscription

To update a subscription, execute: PUT Subscription.

This operation overwrites the complete subscription based on a specific subscriptionId.

Update a subscription:

    curl --location --request PUT 'https://api-sandbox.abnamro.com/v1/business-account-notification/subscriptions' \
    --header 'Content-Type: application/json' \
    --header 'API-key: {{your_api_key}}' \
    --header 'Authorization: Bearer {{access_token}}' \
    --data-raw '{
      "condition": {
        "accountNumber": "NL12ABNA9999876523"
      },
      "target": {
          "type": "WEBHOOK",
          "address": "https://www.client.com/webhook/invoice/paid"
        }
    }'

Step 5 - Get subscriptions

To get a single subscription based on subscriptionId, execute: GET Subscription.

Get one subscription:

    curl --location --request GET 'https://api-sandbox.abnamro.com/v1/business-account-notification/subscriptions/74e8d426-2e11-4166-b66e-9113ba6a9ea6' \
    --header 'Content-Type: application/json' \
    --header 'API-key: {{your_api_key}}' \
    --header 'Authorization: Bearer {{access_token}}'

To get all subscriptions for one account, execute: GET Subscriptions.

Get all subscriptions:

    curl --location --request GET 'https://api-sandbox.abnamro.com/v1/business-account-notification/subscriptions' \
    --header 'Content-Type: application/json' \
    --header 'API-key: {{your_api_key}}' \
    --header 'Authorization: Bearer {{access_token}}'

Step 6 - Delete a subscription

To delete a subscription, execute: DELETE Subscription.

Delete a subscription:

    curl --location --request DELETE 'https://api-sandbox.abnamro.com/v1/business-account-notification/subscriptions/74e8d426-2e11-4166-b66e-9113ba6a9ea6' \
    --header 'Content-Type: application/json' \
    --header 'API-key: {{your_api_key}}' \
    --header 'Authorization: Bearer {{access_token}}'

Business Account Notification 1.3.2