Documentation REST

IBANcheck Nationaal

Summary

Ensure correctly entered bank account details and avoid payment failures or additional bank charges.

Method

IBAN is the International Bank Account Number. The IBAN is a way of showing your existing bank account details in an internationally recognised and standardised format

It is made up of 4 elements:

  • Country code: 2 characters to describe the country
  • Check digit:  2 digits are used to check the validate of the IBAN.
  • Bank code: Up to 4 characters to describe the bankname.
  • Account number: Up to 10 alphanumeric characters starting with a zero.

We offer 2 APIs within IBANcheck Nationaal product. Either validate a complete IBAN code or turn an (old existing) bank account number into a complete IBAN code:

APIDescription
https://api.postnl.nl/iban/national/v1/validateAPI that validates a complete IBAN code. 
https://api.postnl.nl/iban/national/v1/calculateAPI that turns a bank account number in a complete IBAN by adding a country code, bank code and check digit.

Use of services

Calling a service

A service is called by sending a message to a service endpoint. The message contains a header with security information (API-key) and the content type. The body contains the service method and related parameters.

Below you can see examples of the header and body, within Postman (an API tool to visualize APIs).

Please note: the content used is purely for illustration purposes. Example header (paste the API in “{{apikey}}”:

Example header ibancheck1

Example body:

Example body IBANcheck1

Each message that is received by the API is authenticated and authorized. The authorization mechanism determines if the user has access to the requested service.

After processing the request, the service will return a message with a response. The message contains a body with the information.

Parameter specification & field order

For each API, the parameters of a service are specified. Also, the behavior of these parameters are detailed. It is important to maintain the exact order of the fields as specified in the documentation. Changing the order of fields will result in unspecified errors returned back at the client.

Security information

Each service is secured with an API-key. You can find your API-key in API manager. Quotamanager is secured with a username and password. If you don’t have credentials for Quotamanager yet, please fill in the form on this link.

Call details

Preview the API call buildup below. 

Calculate API:

Input

{
"account":"0123456789"
}

Preview the API call buildup below. 

Calculate API:

Output

{
  "address": "GELDSTRAAT 18",
  "bank": "BANK NEDERLAND",
  "bic": "BANKNL2UXXX",
  "city": "UTRECHT",
  "iban": "NL98BANK0123456789",
  "zip": "1000 AA"
}

Validate API

Input

{
"iban": "NL98BANK0123456789"
}

Validate API

Output

   "bank_data": {
    "bic": " BANKNL2UXXX ",
    "bank": " BANK NEDERLAND ",
    "address": " GELDSTRAAT 18",
    "city": "UTRECHT",
    "zip": "1000 AA",
    "country": "Netherlands",
    "country_iso": "NL",
    "account": "0123456789"
  },
  "errors": [],
  "validations": [
    {
    "code": "C02",
    "message": "Check digit account number correct"
    },

    {
   "code": "C01",
   "message": "Check digit correct"
    },

    {
      "code": "C05",
      "message": "Structure correct"
    },

    {
      "code": "C03",
      "message": "Length correct"
    }

}

Requests

The following input parameters should be used for calculate API:
AttributeMandatoryFormatDescriptionExample
account  MString [10]  Either with or without the first character ‘0’. Within the IBAN code a bank account number starts with a ‘0’.Account number0123456789

The following output parameters are returned: 

AttributeDescriptionExample
ibanIBAN codeNL24BANK0123456789
addressAddress of the bankTeststreet 100
bankBank nameRabobank
bicBank Identifier CodeBANKNL2XXXX
cityCity of the bank Amsterdam
zipPostalcode of the bank1000 AA

The following input parameters should be used for validate API: 

Attribute MandatoryDescriptionExample
ibanMIBAN codeNL24BANK0123456789

The following output parameters are returned:

Attribute group AttributeDescriptionExample
bank_data bicBank Identifier CodeBANKNL2AXXX
 bankBank nameBANK NEDERLAND
 addressAddress of the bankGELDSTRAAT 18
 cityCity of the bank AMSTERADM
 zipZIP of the bank1000 AA
 countryCountry of the bank of the bankNetherlands
 country_isoCountry ISO of the bankNL
 accountAccount number0123456789
errorscodeStatus codes (up to 5 in the output)I01

Status codes

The following status codes can be returned for the calculation API:

AttributeFormat
I01Invalid account number
I03Bank code not found

The following status codes can be returned for the validation API:

Status CodeTypeDescription
C01CorrectCheck digit correct
C02CorrectCheck digit account number correct
C03CorrectLength correct 
C04CorrectCheck digit not supported by account number
C05CorrectStructure correct
I01IncorrectCheck digit account number incorrect
I02IncorrectCheck digit incorrect
I03IncorrectLength incorrect
I04IncorrectStructure incorrect

I05

Incorrect Only dutch (NL) account numbers allowed
E01ErrorInvalid API Key 

E02

ErrorAccount error
E03ErrorNo queries available
E04ErrorAccess denied