Getting started

Overview

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. You can find information about how to generate these in our introduction section.

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

GET requests have an Authorization header.

NON-GET requests such as POST, PATCH and DELETE have an Authorization header.

Authorization

  • string
  • header
  • Required
  • get
  • post
  • patch
  • delete
  • request

Your API token retrieved from the portal.

DigitalSignature

  • string
  • header
  • Required
  • post
  • patch
  • delete
  • request

This is a hash of the request body signed with your private key.

X-Request-Id

  • string
  • header
  • Required
  • post
  • patch
  • delete
  • request

This is what we use for idempotency and enables a duplication check. You generate this identifier which must be unique within a 24 hour period.

If an X-Request-Id Header is not supplied, or is invalid, a 400:Bad Request HTTP status code response will be returned.

If ClearBank® detects a duplicate, a 409: Conflict HTTP status code response will be returned.

X-Correlation-Id

  • string
  • header
  • response

This is a unique identifier generated by ClearBank® for the request. ClearBank® would require this identifier for troubleshooting purposes.Therefore, it is recommended you store this response header.

Authenticate your API calls

We use your API token to authenticate your requests and allows 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 Common 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>>
-HX-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.

All TEST Endpoints

Test

get/v1/Test

A test endpoint which ensures that authentication is working as expected

Parameters

  • Authorization string, header, Required

    Your API Token, retrieved from the web portal

Response (application/json)

  • 200 Success
  • 403 Forbidden
  • 500 Server Error
  • 503 Server Error

Test

post/v1/Test

A test endpoint which echoes the supplied content to ensure that signature verification and authorization is working as expected

Parameters

  • Authorization string, header, Required

    Your API Token, retrieved from the web portal

  • DigitalSignature string, header, Required

    Signed hash of the body of the request. The hash is signed by your private key

  • X-Request-Id string, header, Required

    A unique identifier for the request

Response (application/json)

  • 200 Success
  • 403 Forbidden
  • 409 Conflict
  • 500 Server Error
  • 503 Server Error

FITestEvent Webhook

To confirm that authentication and signature verification is working as expected, when you send a POST /v1/Test request you will receive a FITestEvent webhook from ClearBank®.