How to get started with our APIs

Get started

 

This topic describes how to get started with ABN AMRO API products.

 

Step 1 - Create an account

To use an ABN AMRO API product, you must have an account on ABN AMRO Developer Portal.

To create an account:

  1. Click Sign up.
  2. Enter your details, and click Create an account.
  3. The ABN AMRO Service Team will send you activation link by email.
  4. Click the activation link.

 

Step 2 - Explore API products

To view all available APIs, go to the API products page.

You can filter APIs by product type and view all relating information, such as business content and technical documentation.

The ABN AMRO Developer Portal provides fully usable, live API Products, along with early access to APIs that are in development, and experimental APIs.

The current status of an API is displayed using the following labels:

  • Live (no banner): complete API product that is live and available to use.
  • Idea: experimental API idea that may become a complete and live product in the future.
  • Prototype: simulated environment which can be used for development but not in a live digital product.
  • Upcoming: API that is in development and due to be released as a live product shortly, but not currently not available for testing.
  • Closed Beta: beta version of an API product that is available for testing for a limited amount of participants.

 

Step 3 - Create an application

To create an application:

  1. Login to your account.
  2. In the top navigation bar, click My Apps.
  3. Click + Add a new App.
  4. Enter a name of your application, select the API products that you want to use, and click Submit.

To view the status of your applications, go to the My Apps page. You can also view relating information such as the applications API key and secret key. The API key is to access products associated with your App.

 

Step 4 - Develop and test your application

Use the ABN AMRO Developer Sandbox to access dummy data, and safely try out all functionality of an API. For most products, the sandbox environment is identical to production, however, this may vary between API products.

For information on using a specific API in the sandbox, go to the relating API product documentation, and view the Sandbox and Tutorial topics.

 

Step 5 - Go live

When you are ready to go live with your application, complete the following steps:

Note: To go live with your application, you must create a new application in the developer portal. A different API key is required for your production environment.

  1. Login to your account.
  2. In the top navigation bar, click My Apps.
  3. Click + Add a new App.
  4. Enter a name for your application, select the API products that you want to use, and click Submit.
  5. Go to the Contact form.
  6. In the API Product field, select the relating product.
  7. In the Support Category field, select Access to production.
  8. In the Subject field, enter Request production access.
  9. In the Message field, enter Request production access.
  10. Click Send.

Depending on the API product, the ABN AMRO Service Team might contact you to discuss the details of your request. Once approved, you are ready to use this API in a live environment.

 

 

 

 

Authentication

 

The authentication for ABN AMRO APIs is based on a access token. To obtain an access token, you must call the OAuth API.

Note: Authentication methods vary per API as each of them require different levels of security. To learn how it works for the API you want to use, read the documentation of the specific API.

 

Environments

These are the URLs for the endpoints to get the tokens.

Sandbox: https://auth-sandbox.connect.abnamro.com
Production: https://auth.connect.abnamro.com

 

OAuth flows

Our APIs are secured using OAuth 2.0. This means you will need to pass an access token when making your request to the APIs. This page will explain how to obtain an access token. We use the following three flows for getting an access token: Client credentials, Authorization code flow and Refresh token.

If you want to go more in depth on some of the OAuth protocol, have a look at the OAuth RFC.

POST /as/token.oauth2

Client credentials are used in scenarios where no ABN AMRO client consent is required. A Third Party Payment Service Provider (TPP) will be authorized for resources purely based on their identity. For this flow the TPP will have to provide their credentials to the OAuth server to obtain a token. This token is then used for authorization at the API gateway.

 

Generate token

 

Request Attributes
Name Type In Required Description
grant_type String Body true The indicator of the type of flow being used, it should contain 'client_credentials'
client_id String Body true The ID that identifies you as an client / TPP
scope String Body true Scope(s) for which the access token is to be created. Multiple scopes can be requested at once by separating them using a space

 

Sample request

curl -X POST \
{base_url}/as/token.oauth2 \
--cert {location_of_your_certificate} \
--key {location_of_your_private_key} \
--cacert {location_of_your_ca_certificate_chain} \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id={your_id}&scope={the_scopes_you_want}&grant_type=client_credentials'
	

 

Response attributes
Name Type In Required Description
access_token String Body true The access token which is used to access an API
token_type String Body true The type of token provided
expires_in Number Body false Expiry time of the access token, in seconds

 

Sample response
		
{
	"access_token": "{your_new_access_token}",
	"token_type": "Bearer",
	"expires_in" : 3599
}
	

The Authorization Code is used when consent by the ABN AMRO client is required to provide the Third Party Payment Service Provider (TPP) access to a resource.

The TPP redirects the ABN AMRO client to the OAuth server, so that the ABN AMRO client can provide his consent. The ABN AMRO client is then returned to the TPP with an access code. This access code can be exchanged by the TPP for an access token and (if applicable) a refresh token. This access token can then be used to gain access to an API.

Access tokens are valid for a limited time, depending on the context. A refresh token is also provided, enabling the TPP to obtain new access token at a later time. Refresh tokens can also expire. When this occurs, the ABN AMRO client is requested to provide consent again, thus repeating the earlier process. The refresh token reflects the time for which the ABN AMRO client has provided consent, when the refresh token has expired, so has the consent.

 

Request consent

GET /as/authorization.oauth2

This operation asks the ABN AMRO client to give consent on requested resources or a specific transaction. The scopes determine which resources are being requested.

 

Request attributes
Name Type In Required Description
scope String Query true Scope(s) for which the access token is to be created. Multiple scopes can be requested at once by separating them using the + character
client_id String Query true The ID that identifies you as an client / TPP
flow String Query true The type of OAuth flow that is started. Should contain the value 'code' for the OAuth/consent API
redirect_uri String Query false Mandatory if multiple redirect url's or wildcard url's are registered at ABN AMRO for the client / TPP
state String Query false A parameter that is returned to the calling party which can be used for session management
transactionId String Query false Unique id generated during the registration of a payment that needs to be authorized by the ABN AMRO client
bank String Query false ID of the bank of the ABN AMRO client, see table Bank Parameter Values. Defaults to NLAA01, unless otherwise specified
response_type String Query true For the authorization code the value should be 'code'

 

Bank parameter values
Value Associated bank
BEPB01 Belgium private banking
BEPB02 Belgium independant asset management
NLAA01 ABN AMRO NL

 

Sample request

curl -X GET \
'{base_url}/as/authorization.oauth2?scope={the_scope(s)_you_want}&client_id={your_client_id}&response_type=code&flow=code' \
-H 'Cache-Control: no-cache'
		

 

Response attributes

The result of this request is not an response but a redirect to the specified redirect_uri.

Name Type In Required Description
code String Query true A unique authorization code representing the given consent
state String Query false If the state was provided in the original request, the same value will be present in the redirect request

 

Sample response
https://{your_chosen_location.org}?code={authorization_code}
	

 

Exchange authorization code for an access token

POST /as/token.oauth2

This operation will exchange the authorization code for an access token. The authorization code is only valid for 60 seconds, during which it needs to be exchanged for an access token.

 

Request attributes
Name Type In Required Description
grant_type String Body true The indicator of the type of flow being used, it should contain 'authorization_code'
client_id String Body true The ID that identifies you as an client / TPP
code String Body true The authorization code
redirect_uri String Body false If the Request Consent request contained a redirect_uri the same parameter should be passed in the request

 

Sample request

curl -X POST {base_url}/as/token.oauth2 \
-v \
--cert {location_of_your_certificate} \
--key {location_of_your_private_key} \
--cacert {location_of_your_ca_certificate_chain} \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=authorization_code&client_id={your_id}&code={short_lived_authorization_code}'
	

 

Response attributes
Name Type In Required Description
access_token String Body true The access token which is used to access an API
refresh_token String Body false Long validity token
scope String Body false Scope(s) for which the access token is created.
token_type String Body true The type of the access token generated
expires_in Number Body false Expiry time of the access token, in seconds

 

Sample response
		
{
	"access_token": "{your_access_token}",
	"refresh_token": "{your_refresh_token}",
	"token_type": "Bearer",
	"expires_in" : 7193
}
	

POST /as/token.oauth2

This operation will generate an access token and a new refresh token for an existing consent.

 

Request attributes
Name Type In Required Description
grant_type String Body true The indicator of the type of flow being used, it should contain 'refresh_token'
client_id String Body true The ID that identifies you as an client / TPP
refresh_token String Body true The refresh token obtained during the exchange of authorization code or a previous refresh request

 

Sample request

curl -X POST {base_url}/as/token.oauth2  \
-v \
--cert {location_of_your_certificate} \
--key {location_of_your_private_key} \
--cacert {location_of_your_ca_certificate_chain} \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=refresh_token&client_id={your_client_id}&refresh_token={your_refresh_token}'

 

Response attributes
Name Type In Required Description
access_token String Body true The access token which is used to access an API
refresh_token String Body false Long validity token
token_type String Body true The type of the access token generated
expires_in Number Body false Expiry time of the access token, in seconds

 

Sample response
		
{
	"access_token": "{your_new_access_token}",
	"refresh_token": "{your_new_refresh_token}",
	"token_type": "Bearer",
	"expires_in" : 7193
}
	

 

Authentication methods

During the OAuth flows, you are required to authenticate using your OAuth client. There are several methods available for authentication. The API you want to use determines which method has to be used.

TLS-MA is a form of mutual authentication and is also known as Mutual TLS or 2way SSL. It is similar to the normal TLS used by most websites where the server authenticates itself using a server certificate. TLS-MA has the extra step of having the client send it's certificate as proof of it's identity too. The OAuth client is configured to accept one certificate for authentication, this is certificate has to be used to set up TLS-MA. There is no certificate pinning involved, a check is done of the certificates validity, issuer DN, and the subject DN. This allows expired certificates to be renewed without having to update the configuration of your client.

 

Authorization Server's Certificate

Our certificate has been signed by Quovadis. subject DN:

/C=NL/ST=NH/L=Amsterdam/O=ABN AMRO Bank N.V./OU=Identity Federation/ CN=auth.connect.abnamro.com

 

issuer DN:

/C=BM/O=QuoVadis Limited/CN=QuoVadis Global SSL ICA G2

 

How to do TLS-MA

Most of the work will be taken care of by using the appropriate libraries. As it depends on the language and library used, it is best to search the web which libraries are available and how they work.

An example in curl:


curl -X GET \
{base_url} \
--cert {location_of_your_certificate} \
--key {location_of_your_private_key} \
--cacert {location_of_your_ca_certificate_chain}

 

Which Certificate Authorities (CA) does ABN AMRO support?

For PSD2 we support QWAC Eidas certificates. If you want to see the list of currently suported CA, you can issue the following command to find out which CA ABN AMRO trusts.


openssl s_client -connect {host}:8443

This will prompt the server to tell you which Certificate Authorities it accepts under the header "Acceptable client certificate CA names".

 

Can I use a different Certificate Authority (CA) than specified in the list of accepted CAs?

Yes, it is possible to use a different CA. Let us know which CA you would like to use. We will check if this CA is acceptable. If it is, we will add it to the list. Please be aware that this process may take up to several weeks.

Using this method, you will create and sign a JSON Web Token (JWT) using your private key. The client is configured with a public key to validate the signing. The private and public key need to be part of the same key pair for the authentication to be successfull. Please, note that with the signed JWT method no certificates are involved in the authentication.

 

API endpoint

This OAuth API has one endpoint. By making a post request to this endpoint, you can obtain an access token for the other APIs.

To make the request to this endpoint, you need the following settings:

Request attrtibutes Value
Method POST
Path https//api-sandbox.abnamro.com/v1/oauth/token
Headers Content-Type: application/x-www-form-urlencoded
API-Key: (your API key)
Form-data client_assertion: (JSON Web token required to authenticate client)
client_assertion_type: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
grant_type: client_credentials
scope: (the desired scope)(Optional)

The request body will contain a json payload with an attribute named "client_assertion". This attribute will contain the JSON Web token. The token will be used to authenticate the consumer and send back an access token in response.

A JSON web token is a string which consists of three parts where is part is separated by a dot: header.payload.signature. The API consumer needs to generate the JSON web token. Please refer the following steps to create the JSON web token.

 

1. Create public/private key pair

The above OAuth API to be used for authentication requires a JSON web token, which requires signing by a private key from at least a 2048 bit size public/private key pair. The public key of the key pair needs to be shared with ABN AMRO. Following are sample commands to generate a 2048 bit size key pair:


#generates RSA private key of 2048 bit size
openssl genrsa -out private_rsa.pem 2048

#generates public key from the private key
openssl rsa -in private_rsa.pem -outform PEM -pubout -out public_rsa.pem

The keys need to be in PEM format.

Note: Please share your public key along with your app name and developer email id at api.support@nl.abnamro.com. Token generation will not work unless public key is associated with your app.

 

2. Create the header

The header describes how the signature should be generated. It is a JSON object of the following format:


{
	"typ": "JWT",
	"alg": "RS256"
}

In the above json the value of "typ" specifies that this is a JSON web token (JWT), and the value of "alg" specifies the hashing algorithm used to generate the signature component of the JSON web token. Following is the list of alogrithms supported by our OAuth API.

  • RS256
  • RS384
  • RS512

 

3. Create the payload

The payload component of the JSON web token stores the data to be passed in the web token. This data is referred to as "claims" of the JSON web token. The required claims are "exp", "nbf", "sub", "iss" and "aud". It can have an optional claim as "nbf". Following are the definitions of each claim:

Claim Description Mandatory
exp This claim will contain the expiry time in seconds since 1st January, 1970. It cannot be before the current time. This is an integer value, don't put quotes around the value Yes
nbf This claim will contain the time in seconds since 1st January, 1970 before which the JSON web token cannot be processed. Current date date/time must be equal to or after this value. This is an integer value, don't put quotes around the value Yes
iss This claim contains the name of the issuer Yes
sub This claim will contain the api key of the consumer. Refer this link Yes
aud This claim will contain the token URL which are fixed strings.
For sandbox: `https://auth-sandbox.abnamro.com/oauth/token`
For production: `https://auth.abnamro.com/oauth/token`
true

Note: The difference between "exp" and "nbf" cannot be greater than 20 minutes. A sample payload is as following:


{
	"nbf": 1499947668,
	"exp": 1499948668,
	"iss": "me",
	"sub": "anApiKey",
	"aud": "https://auth-sandbox.abnamro.com/oauth/token"
}

 

4. Create the signature

The signature is created using the following pseudocode.


data = base64urlEncode( header ) + “.” + base64urlEncode( payload )
signature = Hash( data, secret );

What this pseudocode does is base64url encodes the header and the payload created in steps 1 and 2. The algorithm then joins the resulting encoded strings together with a period (.) in between them. This joined string is assigned to data. To get the JSON web token signature, the data string is hashed with the private key(generated in first step) using the hashing algorithm specified in the JWT header. The Base64 url encoded values and the signature are as following:


header = eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
payload = eyJzdWIiOiJ4eHh5eHgiLCJleHAiOiIxNDk5OTQ3NjY4IiwiaXNzIjoibWUiLCJhdWQiOiJodHRwczovL2F1dGgtc2FuZGJveC5hYm5hbXJvLmNvbS9vYXV0aC90b2tlbiJ9
signature = jGwHKG_YjgKpR8NPpaLu6nJ97obeP2vcxg6fOWBKdJ0

The JSON web token will be like the following:
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ4eHh5eHgiLCJleHAiOiIxNDk5OTQ3NjY4IiwiaXNzIjoibWUiLCJhdWQiOiJodHRwczovL2F1dGgtc2FuZGJveC5hYm5hbXJvLmNvbS9vYXV0aC90b2tlbiJ9.jGwHKG_YjgKpR8NPpaLu6nJ97obeP2vcxg6fOWBKdJ0

Sample JSON web tokens can be generated at jwt.io You can also use the following node.js code snippet to generate a JSON web token. The code snippet reads the private key from a file named "private_rsa.pem".


var jwt = require('jsonwebtoken');
var fs = require('fs');
var algo='RS256';
var payload={
nbf:Math.floor(Date.now() / 1000),
	exp:Math.floor(Date.now() / 1000) + 300,
	sub:'DLjpQoVpzPshdnwIJEMXnTUhGzGrCG2m',
	iss:'me',
	aud:'https://auth-sandbox.abnamro.com/oauth/token'
};

// sign with RSA SHA256
var cert = fs.readFileSync('private_rsa.pem');  // get private key
jwt.sign(payload, cert, { algorithm: algo},function(error,token){
console.log(token);
});

A complete example call made with curl:


curl -X POST https://api-sandbox.abnamro.com/v1/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "API-Key: xxxxxx" \
-d 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&grant_type=client_credentials&client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ4eHh4eHgiLCJleHAiOiIxNDk5OTQ3NjY4IiwiaXNzIjoibWUiLCJhdWQiOiJodHRwczovL2F1dGgtc2FuZGJveC5hYm5hbXJvLmNvbS9vYXV0aC90b2tlbiJ9.jGwHKG_YjgKpR8NPpaLu6nJ97obeP2vcxg6fOWBKdJ0&scope=tikkie'

If the request is successful, you can expect the following response:


{
	"access_token": "{your access token}",
	"expires_in": "{duration of validity in seconds}",
	"scope": "{scope(s) for which the access token is valid}",
	"token_type": "{it is always Bearer}"
}

 

 

 

 

Error handling

This section provides an overview of the ABN AMRO APIs error model.

 

Error format

All ABN AMRO APIs throw errors in following JSON format:

	
{
	"errors": [
		{
			"code": "ERROR_UNIQUE_CODE",
			"message": "ERROR_MESSAGE",
			"category" : "SHORT_DESCRIPTION/ERROR_CATEGORY",
			"reference" : "API_DOCUMENTATION_LINK",
			"status" : "HTTP_STATUS_CODE",
			"traceId" : "UUID"
			
		}
	]

}

These response attributes are explained below:

Name Type Required Description
code String true Code that uniquely identifies the error for the API
message String true Long text message describing the error
category String true Short description or category of the error
reference String true API Documentation link
status String true HTTP Status code
traceId String true Unique request ID associated with the API call

 

Error codes

Error codes in the error response uniquely describe the error. Whenever you contact API Support for any specific error you are seeing in an API please provide the error code and traceId.

Details of generic error codes are as follows:

Code Category Description
ERR_1001_001 INCORRECT_HEADER Malformed or incorrect Authorization header
ERR_1002_001 MISSING_HEADER Basic authentication header missing
ERR_1002_002 MISSING_HEADER Access token header missing
ERR_1002_003 MISSING_HEADER API Key Header missing
ERR_1003_001 MALFORMED_REQUEST JSON Request: Container Depth exceeded
ERR_1003_002 MALFORMED_REQUEST JSON Request: Number of elements/ properties in an object exceeded the allowed limit
ERR_1003_003 MALFORMED_REQUEST JSON Request: Number of elements in an array exceeded the allowed limit
ERR_1003_004 MALFORMED_REQUEST JSON Request: Object entry/property name too long
ERR_1003_005 MALFORMED_REQUEST JSON Request: Object property value too long
ERR_1003_006 MALFORMED_REQUEST Request message malformed
ERR_1003_007 MALFORMED_REQUEST SOAP Request Message malformed
ERR_1004_001 INCORRECT_PARAMETER Incorrect or missing value for {parameter name}
ERR_1004_002 INCORRECT_PARAMETER Incorrect value of grant type
ERR_1004_003 INCORRECT_PARAMETER Token passed is not a valid token type
ERR_1004_004 INCORRECT_PARAMETER Incorrect or missing value for client_assertion_type.
ERR_1005_001 JWT_LIFESPAN_TOO_LONG JWT lifespan is too long.
ERR_1006_001 JWT_INCORRECT An attribute is incorrect, see the error message.
ERR_1007_001 JWT_INCOMPLETE An attribute is missing, see the error message.
ERR_1008_001 JWT_EXPIRED The presented JWT has expired.
ERR_1009_001 JWT_INACTIVE The presented JWT is not active.
ERR_1010_001 JWT_INVALID The signature of the presented JWT is not valid.
ERR_1010_002 JWT_INVALID The algorithm used to sign the presented JWT is not supported.
ERR_1011_001 JWT_MALFORMED The presented JWT is malformed.
ERR_2001_001 INVALID_CLIENT_IDENTIFIER Client identifier is either missing or invalid.
ERR_2002_001 INVALID_ACCESS_TOKEN Invalid access token.
ERR_2003_001 ACCESS_TOKEN_EXPIRED Access token expired.
ERR_2004_002 APIKEY_STATUS_NOT_ACTIVE The creator of the developer application, whose API key you are using, has an inactive status.
ERR_2004_003 APIKEY_STATUS_NOT_ACTIVE The developer application associated with the API key has been revoked.
ERR_2005_001 INVALID_API_KEY Invalid API Key
ERR_2005_002 INVALID_API_KEY API Key cannot be used for the API call.
ERR_3001_001 ACCESS_DENIED Access denied for this IP address.
ERR_3002_001 INSUFFICIENT_SCOPE Insufficient scope of the token. Token cannot be used for this call.
ERR_3002_002 INSUFFICIENT_SCOPE Insufficient scope of the token. Token cannot be used for this call.
ERR_7001_001 QUOTA_VIOLATION Quota for the call has been exceeded.
ERR_7002_001 TOO_MANY_REQUESTS Spikes in an API call.
ERR_8XXX_XXX INTERNAL_SERVER_ERROR All errors of this code range correspond to an internal server error.
ERR_9001_001 SERVICE_UNAVAILABLE Service is currently unavailable.

 

Note: Error codes that are specific to an particalur API are described in the relating documentation.

 

 

 

 

Postman collections

 

Run ABN AMRO API Collections directly in Postman.

 

FX Trade

FX Trade is a set of APIs that enable you to perform foreign exchange transactions, obtain indicative rates, and retrieve trades performed. The API provides the ability to retrieve a quote and place an order for an FX spot and outright. For more information, see FX Trade.

Run in Postman

 

Tikkie Payment Request

The Tikkie Payment Request API is used to create payment requests on behalf of users. For more information, see Tikkie Payment Request.

Run in Postman

 

Tikkie Fast Checkout

The Tikkie Fast Checkout API is used to check out webshop customers without entering details like email and address information. For more information, see Tikkie Fast Checkout.

Run in Postman