Connector Architecture

Jump to Section

The ClearBank connector is divided into two 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: FPS (FasterPayments), 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 webhooks received in the Webhook Listener [AWS] are stored in a state diagram: Webhook Retailers Receiver SD. The key used for storing the webhooks is a composite key which contains:

  • the type of the webhook
  • an unique identifier like EndToEndTransactionId or IBAN (only for Virtual account webhooks)
  • the Scheme if that exists
  • and a suffix like -REV or -RETRY for FPS reversal webhooks. The webhooks are stored in the state diagram for 15 days, and then released.

In case there is a duplicate webhook sent from ClearBank, the step with storing the webhook in the state diagram will fail and the process will end with the Error Handling step.

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 (Inbound, Outbound or Transfer) using dedicated Mambu transaction channels.

The architecture of the ClearBank Retailers connector is displayed in the below sequence diagram:

More details on the flows can be found in the Business Flows (FPS & CHAPS) and Business Flows (BACS) sections.