Introduction

Overview

The ClearBank® API is a JSON RESTful API which allows you to seamlessly integrate your system with our Banking as a Service (BaaS) platform. Our API enables you to open and manage accounts and process transactions in near real-time. We use webhooks to deliver transaction confirmation notifications and account-specific reconciliations to your system as soon as such events occur on your account.

The ClearBank® API is available for consumption by financial institutions, Financial Conduct Authority (FCA) regulated businesses and fintech companies which have been onboarded with ClearBank®.

If you’re any of the above and would like to connect with ClearBank®'s API, please click here to apply.

alt text

What you need to get started

Your integration journey with the ClearBank® API includes the following steps:

  • You test your connectivity and interaction with our full suite of endpoints and webhooks in a simualtion environment (sandbox ennvironment)
  • We take you through a QA process to confirm successful integration
  • Finally, you will be promoted to use the API in a live/production environment

Accessing the Simulation Environment

You will need the following to connect to the API in a simulation environment:

  • Web address for the Institution portal: https://institution-sim.clearbank.co.uk/
  • Login credentials for the Institution portal (these are provided to you during the onboarding process)
  • Your authentication profile

Accessing the Production Environment

You will need the following to connect to the API in a production environment:

  • Web address for the Institution portal: https://institution.clearbank.co.uk/
  • Login credentials for the Institution portal (these are provided to you during the onboarding process)
  • The ClearBank® authenticator app registered with your Android, iOS or Windows device (this can be downloaded from Google Play, the App Store or the Microsoft Store)
  • Your authentication profile

Creating your authentication profile

Your ClearBank® authentication profile links your institution to your public key. Therefore, it must be valid.

Your authentication profile is a combination of:

  • A Key Pair (public/private)
  • A Certificate Signing Request (CSR) in PKCS #10 format*
  • A token

*In the simulation environment, a CSR can be generated using Open Source solutions. In the production environment, a CSR must be generated using a FIPS 140-2 level 2 compliant Hardware Security Module (HSM) such as Azure KV HSM, Amazon CloudHSM, GoogleCloudHSM (this is not an exhaustive list).

Follow these steps to create a valid authentication profile

  • Generate your Public Key and Private Key pair in PKCS #8 format*
  • Generate your Certificate Signing Request (CSR) in PKCS #10 format which contains your certificate and Public Key
  • Save your CSR as a .csr file
  • Sign in to the Institution portal
  • From the menu, select Institution > Certificates and Tokens

*In the simulation environment, you can utilise Open Source tools to store your Private Key. In the production environment, you must use a physical or virtual HSM solution to store your private key (see HSM requirements above)

alt text

  • Click the Generate API User Certificate button
  • Upload your Certificate Signing Request (CSR) file
  • Enter a Profile Friendly Name and an Expiry Date for your CSR file (the default expiry period is 12 months)
  • Click the Generate New Certificate button to generate your token

alt text

alt text

Congratulations! You have successfully created your authentication profile.

Creating your Digital Signature

We use your Digital Signature to ensure that the integrity of any request body sent to us is maintained. The whole HTTP request body is used to create the Digital Signature and is specific to the body of each request.

Follow these steps to generate a Digital Signature using the Secure Hashing Algorithm (SHA):

  • Hash the request body using SHA 256
  • Pass the hash value produced into your Hardware Security Module (HSM)*
  • Request a Digital Signature using the RSA encryption algorithm (all carried out within the HSM)*
  • The output is the Message Digital Signature
  • Place the Digital Signature within the HTTP header for all requests that have a request body

*In the simulation environment, these operations can be undertaken using Open Source solutions.

For additional help with creating your authentication profile and Digital Signature, we have a GitHub resource to help with your integration in the simulation environment. Please note that these are examples only and are not recommended for use in a production environment.