IBAN verification

Introduction

An up to date swagger API specification is available.

Use CM's IBAN Verification API to retrieve a person's IBAN number using iDEAL. The customer will be billed €0.01

If you are curious about how your consumers would be using IBAN verification, then you can experiment with CM's Demonstration.

Integration

Using the credentials provided , you initially have access to dummy data only via our API. The credentials provided by CM are confidential and should not be distributed further. If you have not yet received any credentials, you can request them via this link.

Before starting integration of IBAN verfication into your services, we advise you to read our Merchant Implementation Guide (Dutch).

Notes

  • IBANs can belong to either consumers or businesses

directory

post

https://ibancheck.cmdisp.com/ibancheck/v1.0/directory

Request

{
  "merchant_token": "3c01abeb-b031-4fea-9f2d-c55c283cd78e"
}

Parameters

Required:

  • merchant_token: a guid string that is unique and private to you as a merchant. Do not share this key, keep it safe. Example 283b1550-ed02-4aee-8529-38a8ae90f10e

Response codes

http status description
200 List of banks
400 Invalid request
403 Authorization required

200 Response

Note that this list is different from the list of banks as returned by iDIN.

[
  {
    "country": "string",
    "issuers": [
      {
        "issuer_id": "RABONL2U",
        "issuer_name": "Rabobank"
      }
    ]
  }
]

Parameters

  • country: The readable name of the country
  • issuer_id: An identifier for the bank. Used as the value of the in bank selector dropdowns. The end user selects a value and iDIN will direct the end user to that bank, so that the user can identify himself. Has the pattern /[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}/
  • issuer_name: The name of the issuing bank intended for display purposes. Used as the content of in the HTML dropdowns.

Error response

Any API call can return an error message

{
  "status": 500,
  "message": "string",
  "code": 1000
}
  • status: Response status code, matches the HTTP error code
  • message: High level description of the error that occured. This description, when present, can be shown to the end user. It might describe that a bank is not available or that the system is offline, or that an unexpected error occured. In test mode, the API will return more information (targeted at the developer) here then in production mode.
  • code: Low level and/or internal error code describing the error.

transaction

post

https://ibancheck.cmdisp.com/ibancheck/v1.0/transaction

Request

{
  "merchant_token": "3c01abeb-b031-4fea-9f2d-c55c283cd78e",
  "issuer_id": "RABONL2U",
  "entrance_code": "string",
  "merchant_return_url": "string",
  "name": true
}

Parameters

Required:

  • merchant_token: a guid string that is unique and private to you as a merchant. Do not share this key, keep it safe. Example 283b1550-ed02-4aee-8529-38a8ae90f10e
  • issuer_id: An identifier for the bank which the customer has chosen. /[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}/
  • entrance_code: This is a token that will allow you to rejoin the user to his session when he returns. It can be a maximum of 40 characters and should only contain the characters a-z, A-z and 0-9. It should only be valid once and needs to be random enough (best use a cryptographically secure random generator), to avoid the possibility of replay attacks`
  • merchant_return_url: The place where the issuing bank should redirect the user to at the end of the flow. The bank will append two query parameters to this url when returning the user to you, trxid and ec. The latter will contain the value of entrance_code, trxid is the transaction_id that you will receive in this request. When not specified, a default can you be used which you specified with CM.

Responses

http status description
200 Succesful transaction
400 Invalid request
403 Authorization required

200 Response

{
  "transaction_id": "string",
  "issuer_authentication_url": "https://issuerserver/transaction",
  "merchant_reference": "string"
}

Parameters

  • transaction_id: A public token ID for this transaction. You should store this with your session data, so that at any point, you can make a callback to the CM api and retrieve the status and/or results. Note that it is not guaranteed that your user will return to you via your merchant_return_url. A connection might be dropped, a user might accidently close a window, or he might trigger the back button and return that way. This id is the only way you can retrieve any information in that case.
  • issuer_authentication_url: The location with the issuing bank to which you should now forward the customer
  • merchant_reference: A private reference id for accounting purposes. Send this together with the transaction_id when making a Status request

status

post

https://ibancheck.cmdisp.com/ibancheck/v1.0/status

Request

{
  "merchant_token": "3c01abeb-b031-4fea-9f2d-c55c283cd78e",
  "transaction_id": "string",
  "merchant_reference": "string"
}

Parameters

Required:

  • merchant_token: a guid string that is unique and private to you as a merchant. Do not share this key, keep it safe. Example 283b1550-ed02-4aee-8529-38a8ae90f10e
  • transaction_id: The public identifier of the transaction.
  • merchant_reference: The private reference of the transaction as provided by the Status response

Responses

http status description
200 OK
400 Invalid request
403 Authorization required
404 The transaction could not be found

200 Response

{
  "status": "success",
  "name": "A. van Dijk",
  "iban": "NL45INGB0000012345"
}

Parameters

Only those values that are available will be represented in the response.

  • status: Either open, success, cancelled, failure, expired. If the status is open, then the information was not yet available. Please try again after a few more seconds or fail. If the status is success then you can expect the requested information to be present. A status of cancelled means that the user has cancelled the flow.
  • bin: When identity was requested, this will be a consistent identifier for this user. If identity was not requested, then this will differ every single time. /[a-zA-Z]{6,6}.*/ Up to 256 characters.
  • name: A description of the name of the customer. Usually consists of initials and last name.
  • iban: The IBAN account number. /[A-Z]{2}\d{2}\s?([0-9a-zA-Z]\s?){20}/