Connector Architecture

The ClearBank connector flow is divided into two main phases: the first one is IBAN linkage and the second is invoked when a new payment is initiated using one of the following UK payment schemes: Clearing House Automated Payment System (CHAPS), Faster Payments Service (FPS), and Bacs Payment Schemes Limited (Bacs).

Please Note:
More details on the flows can be found in the Business Flows section.

Communication between systems

Communication between the systems - receiving and responding to ClearBank - is via webhooks through Amazon Web Services (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.

Webhooks received in the Webhook Listener [AWS] process are stored in the Webhook Lenders Receiver SD state diagram. The key used for storing the webhooks is a composite key which contains:

  • The type of the webhook.
  • A unique identifier, such as EndToEndTransactionId or IBAN (only for virtual account webhooks).
  • If it exists, the Scheme.
  • A suffix, such as -REV or -RETRY for FPS reversal webhooks.

The webhooks are stored in the state diagram for 15 days, and then released.

If there is a duplicate webhook sent from ClearBank, storing the webhook in the state diagram will fail and the process will end with the error handling.

Verification and authorization

The webhook ClearBank sends to acknowledge the API request also acts as a verification mechanism. This verification occurs when a Nonce, provided in the webhook request body, is included in the response body along with a Digital Signature. A response is 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 in 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.

The API message body is signed using the private key, which can be stored in a virtual HSM or AWS S3 Bucket. The message digital signature is placed in a ClearBank specific header. If HSM is used, the solution is FIPS 140-2 Level 2 compliant.

Linking Mambu and ClearBank

Disbursement transactions can be initiated either from Mambu or the ClearBank UI, whereas prepayment transactions can only be initiated from the ClearBank payment simulator. Mambu custom fields are used to store the association between a Mambu Loan Account and a ClearBank virtual account.

After the connection is in place and the IBAN has been successfully mapped to the Mambu Account, the client can initiate inbound or outbound payment as long as there are sufficient funds to cover the transaction. These transactions will use dedicated Mambu transaction channels. The IBAN can be automatically generated by ClearBank at virtual account creation or can be provided by the client when a new disbursement is initiated from Mambu or ClearBank.

Architecture