Connector Architecture

Jump to Section

The ClearBank connector is divided in to two main phases: the first is the initial linking of IBAN to Mambu accounts and the second come into play whenever a new payment is initiating using one of the following UK payment schemes: FPS (FasterPayments), CHAPS (The Clearing House Automated Payment System).

All communication between the Mambu and ClearBank is made via webhooks routed through AWS Gateway(s) to a Webhook Listener [AWS] MPO process. The Webhook Listener [AWS] process accepts webhook event notifications from ClearBank, and informs ClearBank of the webhook listener URL.

The webhooks received in the Webhook Listener [AWS] are stored in a state diagram: Webhook Lenders 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, allows ClearBank to verify that the webhooks were successfully received. If the response is invalid, ClearBank will reject it.

The standard HTTP authorization header holds a security token used by ClearBank to authenticate and approve all valid API requests. ClearBank validates each web request with a public key which must match that of the Certificate Signing Request and if provided, the Digital Signature. This public key is contained within the security token and securely stored in AWS Secrets Manager.

Each non GET API call must be digitally signed and the digital signature included in requests as a ClearBank-specific header to prove that:

  • a message has been signed by a holder of the private key,
  • the data integrity of the message has not been compromised or contents changed in transit.

The private key used to sign the API message body can be stored in either a virtual Hardware Security Module (HSM) or Amazon S3 Bucket. If HSM is used, the connector is FIPS 140-2 Level 2 compliant.

Disbursement transactions can be initiated either from within Mambu or the ClearBank UI, whereas Prepayment transaction 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.

Sequence diagram

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

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