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

Communication between systems

Communication between the systems - receiving and responding to ClearBank - is 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.

Webhooks received in the Webhook Listener [AWS] process are stored in the Webhook Retailers 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. 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

Before a payment is initiated, the link 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 is created in ClearBank and the IBAN mapped to the Mambu deposit account. The link 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 link is in place, the client can initiate any type of payment using dedicated Mambu transaction channels, as long as there are sufficient funds.