Getting started

Get connected

Before you can integrate with our API, you need to have been onboarded by us as a customer and have a valid authentication profile set up. This authentication profile includes your Digital Certificate and secure API token. The API token needs to be included in the header of all REST API calls.

Create 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).

To create a valid authentication profile:

1. Generate your public key and private key pair in PKCS #8 format.

   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).

2. Generate your certificate signing request (CSR) in PKCS #10 format which contains your certificate and public key.

3. Save your CSR as a .csr file.

4. Sign in to the ClearBank Portal using the URL from the table above.

5. From the menu, select Institution > Certificates and Tokens.

6. Select Generate API Token.

   

7. Upload your certificate signing request (.CSR) file.

8. Enter the Token Name and select an Expiry Date.

9. Select Generate to generate your token.

   Your token will appear in the View Token window:

   • The maximum token validity length is a year from the date of creation. You can set a shorter validity period if required.
   • You will only be able to view your token once: at the time of creation.
   • You can copy the token directly or copy it to your clipboard using the button provided.
   • Ensure that you store your token securely now. Otherwise, you will need to generate a new one.

Congratulations! You have successfully created your authentication profile.

Create your digital signature

We use a digital signature to ensure that the integrity of a request body (sent to us) is maintained. The whole HTTP request body (in its original format) is used to create a digital signature, as it is specific to the body of each request.

We use the following specifications to create a digital signature:

• Raw message encoding: UTF-8
• Message digest algorithm: SHA-256
• Signing algorithm: RSA
• Padding: PKCS#1 v1.5
• Digital signature encoding: Base64

To create a digital signature:

1. UTF-8 encode the exact request body that will be sent to our API (any differences including the addition or removal of spaces will result in a totally different digital signature)

2. Hash the encoded value using SHA-256

3. Request a digital signature for that hash value from your hardware security module (HSM)

   (In the simulation environment, this can be done using open source solutions.)

4. The output is the message digital signature

5. Send the Base64 encoded string representation of the digital signature in the HTTP header DigitalSignature for all requests that have a request body

For additional help with creating your authentication profile and digital signature, please refer to the following examples on the ClearBank GitHub repository:

• C# example for ClearBank API and Webhooks
• Postman Collections for invoking the ClearBank API
• C# example for signing ClearBank API requests
• Python example for signing ClearBank API requests
• Java example for signing ClearBank API requests

Please note that the code in these examples is not production ready and has been simplified for brevity.

Use endpoints

Once you have set up your connection to our simulation environment, you are ready to send requests using our API endpoints. The information here allows you to use the GET /v1/Test and POST /v1/Test endpoints.

Header parameters

We utilise HTTP-request headers for our API calls which include Authorization, DigitalSignature and X-Request-Id headers. In all our responses we will send an X-Correlation-Id in the header, together with an HTTP status code.

Different request types require different headers as shown in this table:

Here are the details of each parameter:

Authenticate your API calls

We use your API token to authenticate your requests and allow you to securely access protected resources.

The base URL for your environment is either:

• Simulation https://institution-api-sim.clearbank.co.uk/
• Production https://institution-api.clearbank.co.uk/

Your API token should be included in your HTTP Authorization header. Please refer to Header parameters for more information.

This example request shows the API token in the Authorization , DigitalSignature and X-Request-Id header.

curl -v -POST https://institution-api-sim.clearbank.co.uk/v1/Test \
  -H “Authorization: Bearer <<your api token>>”
  -H “DigitalSignature: <<digitalsignature>>”
  -H “X-Request-Id: <<X-request-ID>>”      
  -d ‘{ "body": "hello world!" }’      

The response shows results from the test call

{
    "Message": "hello world!"
}

To confirm that authentication and signature verification are working as expected, when you send a POST/v1/Test request you will receive a FITestEvent webhook from ClearBank (if you are subscribed to it). We use webhooks to deliver transaction confirmation notifications and account-specific reconciliations to your system as soon as such events occur on your account. Please refer to Test Webhooks for more information.

Query parameters

For most of our GET requests, one or more query parameters in the request URL can be used to specify the number of returned results and the number of pages returned.

HTTP status codes

When you send a request, the response will include an HTTP status code to indicate the success or failure of the request. For successful requests, we return a HTTP 2XX status code. For failed requests, we return a HTTP 4XX or 5XX status code. Some endpoints return JSON response bodies that include errors and additional properties.

5xx status codes

If you receive a 5xx error code, you should retry your request as these are service errors. A request that returns these errors may, in exceptional circumstances, result in being processed regardless. Following which, you will receive a notification (webhook) delivered to you as expected.

To avoid any duplication, always retry all such requests with exactly the same request ID header and payload. If the initial request is successful, the retry request will trigger a notification (HTTP response or webhook) to confirm that it has not been processed as it was identified as a duplicate.

Example of a response containing detailed errors

{
  "errors": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

HAL Links

We use HAL (Hypertext Application Language) to hyperlink between resources in our API.

Each HAL hyperlink contains:

Example HAL Links

{
    "accounts": [
        {
            "id": "9140d28b-58d4-4e14-a5fe-43a655c82162",
            "name": "Gen Seg Acc Wsale - TradingBankEnd2End",
            "type": "CACC",
            "currency": [
                "GBP"
            ],
            "balances": [
                {
                    "name": "Gen Seg Acc Wsale - TradingBankEnd2End",
                    "amount": 2000000.00,
                    "currency": "GBP",
                    "status": "VALU"
                }
            ],
            "iban": "GB90CLRB04190000001107",
            "bban": "CLRB04190000001107"
        },
        {
            "id": "9b3dd95c-92a0-4c22-8314-da97906f4a2b",
            "name": "Mandated Minimum Balance Account",
            "type": "CACC",
            "currency": [
                "GBP"
            ],
            "balances": [
                {
                    "name": "Mandated Minimum Balance Account",
                    "amount": 2000000.00,
                    "currency": "GBP",
                    "status": "VALU"
                }
            ],
            "iban": "GB57CLRB04190000001119",
            "bban": "CLRB04190000001119"
        },
        {
            "id": "0392ffce-fd15-47a6-824f-708e0bee007b",
            "name": "Operating Account",
            "type": "CACC",
            "currency": [
                "GBP"
            ],
            "balances": [
                {
                    "name": "Operating Account",
                    "amount": 1999992.00,
                    "currency": "GBP",
                    "status": "VALU"
                }
            ],
            "iban": "GB95CLRB04190000001114",
            "bban": "CLRB04190000001114"
        }
    ],
    "halLinks": [
        {
            "name": "self",
            "href": "https://institution-sim.clearbank.co.uk/v1/Accounts",
            "templated": false
        },
        {
            "name": "Account",
            "href": "https://institution-sim.clearbank.co.uk/v1/Accounts/{accountId}",
            "templated": true
        },
        {
            "name": "Transactions",
            "href": "https://blue-institution-sim.clearbank.co.uk/v1/Accounts/{accountId}/Transactions",
            "templated": true
        },
        {
            "name": "Mandates",
            "href": "https://blue-institution-sim.clearbank.co.uk/v1/Accounts/{accountId}/Mandates",
            "templated": true
        }
    ]
}

Use webhooks

What are webhooks?

When certain events occur, we generate and send out a webhook message to your defined URL. You can subscribe to the webhooks you wish to receive as described in Set up and test webhook listener URLs. When you receive a webhook, you will need to respond to it to confirm receipt.

All ClearBank webhooks consist of a DigitalSignature, Type, Version, Payload, and Nonce. Payload parameters vary depending on the webhook.

Webhooks are asynchronous events and can be delivered in any order. We provide at-least-once delivery of webhooks. Because webhooks may be sent more than once, your webhook handlers must be idempotent. You can check for duplicates based on the payload of the webhook.

Webhook structure

Response structure

Webhook responses contain a 200 HTTP status code which includes a Nonce number in the body and your DigitalSignature.

IP address ranges

The ranges of IP addresses that ClearBank webhooks are sent from are different for the simulation and production environments. All the IP addresses listed here should be included on your allow list so that webhooks are not blocked by your security.

The ranges of public IP addresses to support your interaction with ClearBank webhooks are:

• Simulation public IP address ranges: 51.145.122.16/28, 20.39.213.0/28, 172.187.147.144/28, 20.117.212.176/28
• Production public IP address ranges: 51.145.122.32/28, 172.187.179.192/28, 172.187.243.32/28, 20.117.189.64/28

This list was last updated on 24 August 2023.

Handling a webhook

Webhooks sent by ClearBank include the security components needed for you to verify the authenticity of the data they contain. It is important that you use these to verify each webhook was sent by ClearBank. Subsequently, ClearBank verifies that you have successfully received the webhook (based on your response acknowledging receipt).

The handling of a webhook can be thought of in three different parts: verification, response, and processing.

Verification

You need to verify that ClearBank is the true source of the webhook, and that the webhook has not been tampered with.

To verify the integrity of the webhook received from ClearBank:

1. In the ClearBank Portal, on the Webhook Management page, select Download Public Key.

   This provides a public key specific to your institution.

2. Hash the request body using SHA 256.
3. Convert the DigitalSignature request header value from a Base64 encoded string into the byte array.
4. Verify the signature using the RSA algorithm.

We have provided an example C# controller in the ClearBank fi-api-101 Github Repository which shows how to calculate the hash value and verify the digital signature. Once you know the webhook can be trusted, you can respond.

Response

If you were able to successfully verify that ClearBank was the true source of the webhook then you must return a 200 HTTP response. This must include the nonce number in the response body and be signed with a valid digital signature. (If your response is invalid, we will consider the webhook to have failed.)

If you are not able to verify the webhook source then you should respond with a reasonable status code/error code to signify that the webhook should be treated as failed.

We will retry webhooks that we are not able to consider successful every 15 minutes for 24 hours or until you return a successful response. We err on the side of caution to ensure you have correctly received the webhook. For more information, refer to Idempotency.

To create the webhook digital signature:

1. Take the nonce number from the webhook and place it in the body of the response (like this: {"nonce": <value>}).
2. Hash the response body using SHA 256.
3. Sign the hash with your private key and attach the signed hash as a Base64 encoded string in the DigitalSignature response header.

Your private key needs to correspond to a public key which has been used to create a certificate signing request (CSR). Please refer to create your authentication profile for more information.

Example HTTP request:

POST http://yourdomain.com/sample/webhook HTTP/1.1
Content-Type: application/json
Content-Length: 72
Digitalsignature: YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
X-Request-Id: f0309d95-4f68-4ecd-9c8d-b2d08d9fedd8

{"Type":"FITestEvent","Version":1,"Payload":"test me","Nonce":1448545215}

Example HTTP response:

HTTP/1.1 200 OK
Digitalsignature: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/json

{
    "Nonce": 1448545215
}

Processing

Due to the 5 second timeout window that applies to successful webhook responses, it makes sense to minimise the processing that is done before responding to the webhook. We recommend verifying, queuing, and responding to the webhook synchronously. An internal queuing solution can then handle any further processing asynchronously (including any checks for duplicates).

Idempotency

We use at-least-once delivery when sending webhooks. This means to ensure you have received a webhook, we may send it to you multiple times.

Duplicate webhooks can generally be identified by looking at the EventType, Timestamp and Id within the payload. If the values are the same, the webhook is a duplicate.

You must be able to handle duplicate webhooks idempotently. This means you should always respond in the appropriate format even if you have detected a duplicated or retried webhook. If you don't, we won't be able to verify the webhook was successfully received and will therefore retry delivery.

Set up and test webhook listener URLs

You can create one webhook listener for all events or separate webhook listeners for specific events. In this example, you will setup an FITestEvent webhook URL, which you can test against the TEST POST endpoint.

To manage your webhook definitions and set your webhook listener URLs for each event:

1. Log in to the ClearBank Portal. More information about accessing the portal can be found here.
2. From the menu, select Institution > Webhook Management.

   

3. Search for Test webhook and select Edit.
4. Enter the URL you want to define as your webhook listener for this webhook and set the webhook status to Enabled.
5. Select Save.
6. To test the webhook, select Test button.
7. Enter a test message in the Test webhook window for example, ‘Hello World’ and select Send.

   You should receive an FITestEvent webhook to your nominated URL containing the test message in the body.

You must not include any sensitive information (such as API keys) in your webhook URLs.