The ClearBank connector is divided into 2 main phases: the first one is the IBAN linkage and the second is invoked when a new payment is initiated using one of the following UK payment schemes:
CHAPS (The Clearing House Automated Payment System) or
BACS (Bankers' Automated Clearing System).
The communication between the systems - receiving and responding to ClearBank is made via webhooks through AWS Gateways. All the webhooks are sent to the
Webhook Listener [AWS] Mambu Process Orchestrator (MPO) process. The
Webhook Listener [AWS] process enables listening for and receiving webhook event notifications from ClearBank, and informing ClearBank of the webhook listener URL.
The webhook ClearBank sends to acknowledge the API request also acts as a verification mechanism. This verification occurs when a
Nonce, which was provided in the webhook request body, is included in the response body along with a Digital Signature. The response sent back acknowledging receipt of the valid webhook, allowing ClearBank to verify that the webhook was successfully received. If the response is invalid, ClearBank will reject it.
The standard HTTP
authorization header contains a security token and is used by ClearBank to authenticate and approve valid API requests. The
public key is held securely within the security token in AWS Secret Manager and is used for identification when authenticating a request. ClearBank validates each web request with the public key in the Certificate Signing Request and if provided, the Digital Signature.
Security Tokens are used to authenticate the request and use the public key to validate the digitally signed messages. The Security Token must be stored within a virtual Hardware Security Module (HSM) or AWS S3 Bucket.
Each non GET API call must contain the
Digital Signature header to prove:
- That a message has been signed by the holder of the private key
- The data integrity of the message - that is to say that no data has been altered during transit
The API message body is signed by using the private key, which, based on the chosen solution, can be stored in a virtual Hardware Security Module (HSM) or AWS S3 Bucket. The message digital signature is placed within a ClearBank specific header. In case HSM is used, the solution is FIPS 140-2 Level 2 compliant.
Before a payment is initiated, the linkage between Mambu and ClearBank must be in place. Whenever a new Deposit Account is created in Mambu with a currency of
GBP, the main process
IBAN linkage [link to Mambu webhook(s)] is triggered and a new Virtual Account will be created in ClearBank and the IBAN mapped to the Mambu Deposit Account. The linkage can be made using External Account Representation (
EAR) or Custom Fields. The IBAN can be automatically generated by ClearBank at Virtual Account creation or can be provided by the client when a new Deposit Account is created in Mambu.
After the linkage is in place, the client can initiate any type of payment as long as there are sufficient funds (
Transfer) using dedicated Mambu transaction channels.
The architecture of the ClearBank Retailers connector is displayed in the below sequence diagram: