Connecting to the API

The first step in connecting to the Banking Circle API is to get a new M2M user created, including requesting a new certificate, by your Integration Manager. When receiving the initial passphrase for the certificate, please use this to reset the password.

After changing the password, download the certificate that contains the Thumbprint so that you can start requesting an access token – this will be a standard JWT OAuth 2.0 signed token. Note that you always need a certificate to test our endpoints – this is also true for the sandbox environment.

When requesting access for production or the sandbox environment, you need to inform your Integration Manager of the IP addresses that should be whitelisted by Banking Circle.

An access token can be requested from the Authorization endpoint which requires the use of the Basic Authentication scheme.

Example of encoding the username and password to Base64:

var raw = CryptoJS.enc.Utf8.parse('username' + ":" + 'password') 
var base64 = CryptoJS.enc.Base64.stringify(raw)

Example of an authorisation request:

{
  url: 'authorizationURL',
  method: 'GET',
  header: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + base64
  }
}

Requesting access tokens

To send or request data via the Banking Circle API, an access token will need to be obtained by following the steps outlined below.

We encourage users connecting to the API to only request a new access token when required, i.e., only if the previous token has expired – this means that you should check the expiration time of the previous token before requesting a new one.

Steps:

  • Initiate a GET request to the Authorization endpoint /api/v1/authorizations/authorize
  • Store the following attributes from the response body: access_token (JsonWebToken) and expires_in (In seconds).
  • Check the expiration time of the token before every subsequent request:

    • If the token hasn’t expired, then use the currently stored token in the new request
    • If the token has expired, then follow the steps again to request a new token

Example 200 success response containing access token and expiry

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Im9JMmRKVjdpTUkxZU9pZWFsb nhCZ3lNb1pmOExRMmc2UGExUlVvdElVSFUifQ.eyJpc3MiOiJodHRwczovL2JhbmtpbmdjaXJjbGVub25wcm9kdGVuYW50LmIyY2xvZ2luLmNvbS9jNTUwZmZkZi01YWIyLTRjZTctYmM1NS0zNmU1YmIzZmYzYWQvdjIuMC8iLCJleHAiOjE1ODQwOTExMTIsIm5iZiI6MTU4NDA5MDgxMiwiYXVkIjoiYzZmMDEyNDgtYmNmYS00MDZhLWE3OTEtODRiNzE0MjM0NmM2Iiwic3ViIjoiYWE2ZTM3ODItNzExYi00MDY2LTliYzYtNDQ5ZDZlYzE5M2FiIiwib2lkIjoiYWE2ZTM3ODItNzExYi00MDY2LTliYzYtNDQ5ZDZlYzE5M2FiIiwibmFtZSI6IkFQSSBUZXN0dXNlciIsInVzZXJUeXBlIjoiNCIsInRodW1icHJpbnQiOiI2MDgzNzhCRkE2RTVFMkMwMUY3MDlBMzVENkREQjNBNkY4NDQ1NkUxIiwiYXpwIjoiYzZmMDEyNDgtYmNmYS00MDZhLWE3OTEtODRiNzE0MjM0NmM2IiwidmVyIjoiMS4wIiwiaWF0IjoxNTg0MDkwODEyfQ.nrjkLoivWiXHI0QuHSa_W7JmT V_KUs7zQWrf7-ko6oM1LMwLiHpM0w45d8PhxjNdG_o3hTmx8PhBkhvKoStlnkNzNGD4RYw3ZvpUjL5tuQpRPoY2xJ682R8u7pSN5kZvH0PCh2d0OVCD_twRVNFxdC5pYkabAlCgDE15RO0ZVxxBu6VFIe6 v9GaWxLL5Gn0NZgSZ1WzeP8RYgzrH3W7dRIXRHMe6fJBqCf9E7YXGUYuVRQ4l_PytnkICXiIX0e00xqwDwwEkpy_-1aAfkpk56QCEOfzO-QJwln2qbEU3S6okzsCvKvNbprqvmKbyjgknPuoGQjIVpM_sLloa2oA",
  "expires_in": "300"
}

To access Banking Circle’s API functionality, you need to send the access token in the Authorization request header field, using the Bearer Authentication scheme.