Integration Setup

Mambu

At the end of this section you will have created the necessary transaction channels, custom fields and webhooks to support the connector.

Transaction channels

Six Transaction Channels should be created in Mambu to support the connector. FPS and CHAPS payment schemes should have dedicated transaction channels for disbursement and repayment transaction types and disbursement transaction channels are further broken down by where the disbursement was made, either in ClearBank or Mambu.
- two for Disbursement transaction triggered from Mambu: MBU_Loan_Disbursement_FPS, MBU_Loan_Disbursement_CHAPS - two for Disbursement transaction triggered from ClearBank: CB_Loan_Disbursement_FPS, CB_Loan_Disbursement_CHAPS - two for Repayment transaction: CB_Loan_Repayment_FPS, CB_Loan_Repayment_CHAPS
The screenshots below indicate the minimum configuration, however, some fields, such as General ledger Accounts may also need to filled in, consult our support page for transaction channels and your internal Mambu champion for more information.

Custom fields

1. Create custom fields for the Loan Account entity. These fields are required for saving ClearBank Virtual Account ID, IBAN and Assigned Deposit User. The MPO API user or its assigned role should be granted view and edit rights. These fields can be added to any existing Standard Custom Field Set or a new type Standard type can be created.
   
   • virtualAccountId, ibanLoan and assignedLoanUser custom fields should be created as regular free text fields.
   • virtualAccountId and ibanDeposit custom fields should be unique.
   • the assignedLoanUser custom field is optional. This field is used to save the encoded key of a user, for example the Credit Officer, who is responsible for a given deposit account.
     
     
     
2. Create custom fields for the Transactions entity for saving payee (creditor) and payer (debtor) transaction details and the EndtoEndTransactionID used for reconciliation. Give access rights for all the transaction channels where these custom fields are used.
   
   • creditorName, creditorIBAN, debtorName, debtorIBAN, paymentReference, transactionEndToEndId, transactionStatuscustom fields should be created as regular text fields.
   • transactionEndToEndId custom field stores the transaction key: for Disbursement triggered from Mambu is Mambu Disbursement encoded key and for Disbursement triggered from ClearBank is ClearBank EndToEndTransactionId, for Repayment is ClearBank EndToEndTransactionId. This field is needed also for Reconciliation process.
   • transactionStatus custom field stores the transaction status from ClearBank. Allowed values: Settled, Held, Rejected.

Webhooks for loan disbursement

Create an Opt-Out Loan Disbursement Webhook for the corresponding Target, either Clients or Groups. Webhook setup:

These settings ensure that the webhook is triggered only when the Disbursement transaction is made using one of the dedicated channels; MBU_Loan_Disbursement_FPS, MBU_Loan_Disbursement_CHAPS.

Use one of the following templates for the webhook body, depending on the target:

• Loan disbursement webhook body for Clients:
  

  {
      "amount": "{TRANSACTION_AMOUNT}",
      "paymentScheme": "{TRANSACTION_METHOD}",
      "transactionEncodedKey": "{ENCODED_KEY}",
      "loanAccountId": "{ACCOUNT_ID}",
      "loanName": "{ACCOUNT_NAME}",
      "transactionId": "{TRANSACTION_ID}",
      "debtorName": "{RECIPIENT_NAME}",
      "paymentReference": "{CF:TRANSACTION:PAYMENTREFERENCE}",
      "debtorIBAN":"{CF:TRANSACTION:DEBTORIBAN}",
      "creditorIBAN":"{CF:TRANSACTION:CREDITORIBAN}",
      "creditorName": "{CF:TRANSACTION:CREDITORNAME}",
      "accountCurrency": "{ACCOUNT_CURRENCY_CODE}",
      "assignedLoanUser": "{CF:LOAN:ASSIGNEDLOANUSER}",
      "transactionEndToEndId": "{CF:TRANSACTION:TRANSACTIONENDTOENDID}"
  }
  

• Loan disbursement webhook body for Groups:
  

  {
      "amount": "{TRANSACTION_AMOUNT}",
      "paymentScheme": "{TRANSACTION_METHOD}",
      "transactionEncodedKey": "{ENCODED_KEY}",
      "loanAccountId": "{ACCOUNT_ID}",
      "loanName": "{ACCOUNT_NAME}",
      "transactionId": "{TRANSACTION_ID}",
      "debtorName": "{RECIPIENT_NAME}",
      "paymentReference": "{CF:TRANSACTION:PAYMENTREFERENCE}",
      "debtorIBAN":"{CF:TRANSACTION:DEBTORIBAN}",
      "creditorIBAN":"{CF:TRANSACTION:CREDITORIBAN}",
      "creditorName": "{CF:TRANSACTION:CREDITORNAME}",
      "accountCurrency": "{ACCOUNT_CURRENCY_CODE}",
      "assignedLoanUser": "{CF:LOAN:ASSIGNEDLOANUSER}",
      "transactionEndToEndId": "{CF:TRANSACTION:TRANSACTIONENDTOENDID}",
      "groupId": "{RECIPIENT_ID}"
  }
  

  Please note:
  You will not have the webhook target URL until after importing the connector into MPO, so will need to come back to these webhooks and update this field with the correct values later. See the screenshots below for the name of the process from which you should obtain the URL.

  5. Loan Account should be in an valid state for Disbursement and transaction (Active | Active (Partially Disbursed) | Approved).
  6. Loan Account should be in an valid state for Repayment transaction (be already Disbursed).
  

Webhooks for loan account closure

Create an Opt-Out Webhooks for Loan Account Closed (Repaid) and Loan Write Off.

Loans written off

The following conditions should be used for the Loan Write Off webhook:

• Loan account closure webhook body for Loan Account Write Off:
  

  {
  "virtualAccountId":"{CF:LOAN:VIRTUALACCOUNTID}",
  "comment":"{TRANSACTION_COMMENT}",
  "loanAccountId":"{ACCOUNT_ID}",
  "loanCFIBAN": "{CF:LOAN:IBAN}"
  }
  

Loans paid off

The following conditions should be used for the Loan Account Closed (Repaid) webhook:

• Loan account closure webhook body for Loan Account Closed (Repaid):
  

  {
  "virtualAccountId":"{CF:LOAN:VIRTUALACCOUNTID}",
  "comment":"{TRANSACTION_COMMENT}",
  "loanAccountId":"{ACCOUNT_ID}",
  "loanCFIBAN": "{CF:LOAN:IBAN}"
  }
  

AWS

The configuration required for AWS depends on where you decide to store the private key used for the Digital Signature, which can be:

• Amazon S3 + AWS Key Management Service (KMS)
• AWS CloudHSM

Lambda Function for Webhooks

1. Navigate to Services - Lambda. Create clearbankFunction Lambda function.
   

   Note:
   

   • When no execution role exists, select the option Create a new role with basic Lambda permissions.

2. Create Function.

3. Upload the .zip file clearbankFunction_lambda.zip which you will find in the GitLab repository for this connector. After uploading, you should find the following files in the Lambda function Code source:
   

4. In order to verify the webhooks from ClearBank, you will need to obtain the public key from the Webhook Management section found in the Institution settings in the ClearBank UI. The public key needs to be uploaded to AWS as a file named publicKey.pem that is available to the Clearbank lambda function: Copy and paste the key you downloaded from ClearBank into this file. It should look similar to this:
   

5. Update the environment variables with values from MPO - Webhook Listener [AWS] Secret key, API login and process ID) and company_id which will receive the webhooks and sign back the Nonce response. See the note below on where to find these values. Click Save.
   

6. Update the allocated memory from Lambda function (e.g: clearBankFunction) - Basic Settings - Memory (MB). If many requests are sent than allocate the default memory 2048 MB with 10 seconds delay for the process.
   

AWS Secrets setup

The AWS Secrets should be defined in order to store the authorization token and the secret key used to authenticate requests coming from MPO to AWS.

Firstly, you need to access the AWS Secrets Manager service: Afterwards, you need to create a new secret like this:

Please note that value1 and value2 from the screenshot above should match the authorizationTokenAWS and secretKey values from MPO Clearbank config!

In the end, you should have a new secret stored in AWS:

Lambda Function for Digital Signature

→ Using Amazon S3 and KMS solution

1. Navigate to Services - Lambda. Create digitalSignature Lambda function.
2. If no execution role exists, create a new execution role by selecting the option Create a new role with basic Lambda permissions. In addition, Lambda function also needs to have permissions to read the Secret value for the AWS secret, i.e.:
3. Create Function.
4. Upload the .zip file digitalSignature_kms_lambda.zip which you will find in the GitLab repository for this connector.
5. Add an environment variable to point to the previously defined AWS secret.

→ Using AWS CloudHSM solution

If you are using the Digital Signature based on an AWS CloudHSM private key, you need to follow the steps documented our Digital Signature with AWS CloudHSM and Lambda guide.

After setting up the Lambda function according to the guide, there are two more steps in order to interact with the AWS secret:

1. Create an additional environment variable for the Lambda function that points to the previously created AWS secret:

2. Verify the permissions of the Lambda function role - Lambda function needs to have permissions to read the Secret value for the AWS secret, i.e.:

Lambda Function for Authorization Token

This Lambda function is required to authenticate the requests coming to the API Gateway for Digital Signature (ensuring that they come from MPO). To create and configure this function, you need to follow the steps below:

1. Navigate to Services - Lambda. Create authorizer Lambda function.
2. Choose a role that gives the Lambda function access to AWS Secret Manager (see step 2 of Lambda Function for Digital Signature using CloudHSM solution)
3. Create Function.
4. Upload the .zip file authorizer_lambda.zip which you will find in the GitLab repository for this connector.
5. Add the SECRET_ID environment variable: This should point to the secret created in the section AWS Secret Setup.

API Gateway for Webhooks

1. Navigate to Services - API Gateway and create the endpoint path (click on Create API button and select Rest API - Build).
2. Open your new API. Go to Resources > Actions and click on Create Resource.
3. Create a synchronous endpoint by selecting the previously created resource (e.g: /gateway). Click on Actions > Create Method > POST. Select the POST method and add the lambda function (e.g: forClearBank).
   
4. Select Method Request section from API Gateway (POST). Add Request Validator - Validate query string parameters and headers under Settings.
5. Select the Integration Request section from API Gateway (POST) and add Mapping Templates, selecting application/json as the content type. The following code needs to be placed at the mapping templates:

{
    "body":"$util.escapeJavaScript($input.body).replaceAll("\\'","'").replaceAll("\'","'")",
    "headers":{
        #foreach($param in $input.params().header.keySet())
        "$param": "$util.escapeJavaScript($input.params().header.get($param))"
        #if($foreach.hasNext),#end
        #end
    }
}

6. Open the Method Response section from API Gateway (POST). Map the success response message for Clearbank and add DigitalSignature as a header.
   Map 401 response (Unauthorized) to an Error response body model.
7. Select the Integration Response section from API Gateway (POST). Map ClearBank DigitalSignature as a header and success response message.
   

   ##  See http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html
   ## WARNING: Every character matters in this form (including spaces)! Do not change a bit!
   #set($inputRoot = $input.json('$.Nonce')){"Nonce":$inputRoot}
   

   Response codes:

   Accepted -> 200 response code
   Rejected -> 401 response code
   

Map 401 response code to the “AUTHORIZATION ERROR” Lambda error regex and the mapping template below:

{
  "errorMessage" : "$input.path('$.errorMessage')"
}

8. Select Deploy API from the Actions menu.
   
9. Copy the Invoke URL available under Stages section and save this for later, it will be needed when setting up ClearBank webhooks.
   ! Invoke URL

API Gateway for Digital Signature

1. Navigate to Services > API Gateway and create the endpoint path (click on Create API and select Rest API > Build).
2. Open your new API. Go to Resources - Actions and click on Create Resource.
3. Create a synchronous endpoint by selecting the previously created resource (e.g: /gateway). Click on Actions > Create Method > POST, select the POST method and add the lambda function (e.g: digitalSignature).
4. Link the authorizer lambda function to Digital Signature API Gateway in the Authorizers section.
   
   
   
5. Open the Method Request section from API Gateway (POST). Add the Authorization as HTTP Request Header and use the following Settings:
   • Authorization - select the authorizer token created as a lambda function authorizer (e.g: AuthorizerSM).
   • Request Validator - Validate query string parameters and headers.
6. Open the Integration Request section from API Gateway (POST). Add Mapping Templates for the content type application/json.

   {
       "body":$input.json("$"),
       "queryparams":{
           #foreach($param in $input.params().querystring.keySet())
           "$param": "$util.escapeJavaScript($input.params().querystring.get($param))"
           #if($foreach.hasNext),#end
           #end
       },
       "headers":{
           #foreach($param in $input.params().header.keySet())
           "$param": "$util.escapeJavaScript($input.params().header.get($param))"
           #if($foreach.hasNext),#end
           #end
       }
   }
   

7. Open the Method Response section from API Gateway (POST). Map ClearBank success response message and add DigitalSignature as a header.
   For error messages, map Response Body model to Error:
8. Open the Integration Response section from API Gateway (POST). Map ClearBank DigitalSignature header and success response message.
   

   ##  See http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html
   #set($inputRoot = $input.json('$'))
   $inputRoot
   

   As method response for the status 400, map ERROR response message as below:

   {
     "errorMessage" : "$input.path('$.errorMessage')"
   }
   

9. Select Deploy API from the Actions menu.
10. Copy the Invoke URL available under the Stages section and keep this to hand. This will be required later for setting up MPO.

Certificate and Token

Note: if you are using the CloudHSM solution, the certificate needs to be generated according to the documentation in our Digital Signature with AWS CloudHSM and Lambda guide.

→Generate Certificate

1. Navigate to Services > Lambda and select your DigitalSignature function, or use search to find it.
2. From function code rename index file (e.g: index_1).
3. From function code rename generate CSR file to index. Then select Deploy and then Test.
4. From the response, create the .csr file. Copy the certificate which starts from, and includes the line -----BEGIN CERTIFICATE REQUEST----- and ends in, and includes the line -----END CERTIFICATE REQUEST-----. Save the file with the extension .csr.
5. From the response create the .pem file. Copy the Private Key which starts from, and incldues the line -----BEGIN PRIVATE KEY----- and ends in, and includes the line -----END PRIVATE KEY-----. Save the file with extension .pem.
6. Rename the file index to generate CSR and rename the file the file from Step 2 back to index.

→Generate Token

1. Navigate to ClearBank UI > Certificates and Tokens > Generate API Token.
2. Upload the .csr file you created in the previous step.
3. Provide a Token Name, select an Expiration Date and click Generate.
   
4. Copy the API Token and keep it to hand, it will be needed later.

Key Management Service (KMS)

→KMS for Digital Signature Encryption

1. Navigate to Services > Key Management Service (KMS) and create a new key by clicking on Create a Key and selecting Symmetric as key type.

2. Choose an alias for the key and, optionally, add a description, tag key and tag value.

3. Add your key administrators, selecting the IAM users and roles that can use Customer Managed Keys in cryptographic operations.

   Note:
   Multiple users and roles can be added here, the important thing is to include the Role under which the digitalSignature Lambda function is executed and the User who is assigned as the key administrator.

4. Review Key policy and click Finish.

→S3 Bucket

1. Navigate to Services > S3. Select Buckets and create a new bucket by clicking Create bucket.
2. In the Configure options screen, check Automatically encrypt objects when they are stored in S3 and select the previously created KMS key.
   
3. In the Set Permissions screen, check the option Block all public access.
4. Review the configuration and check everything is correct.
5. Upload the private key (file with extension .pem that was created in the certificate and token section) to the newly created bucket.
6. Set Read/Write permissions, selecting Standard storage class and setting AWS KMS master-key as Encryption type and choose the previously created KMS key.
7. Review settings and upload the file.

→Grant access of Digital Signature Lambda function to the encrypted AWS S3

1. Navigate to Services > Lambda, select DigitalSignature function or use search to find it. Open the Permissions tab.
   
2. Check that the AmazonS3ReadOnlyAccess policy is attached to the DigitalSignature Lambda function execution role.
3. Update the environment variables and click Save.

4. Check that the DigitalSignature Lambda execution role is attached to the KMS key. Navigate to Services > Key Management Service and search for the KMS key.

Update Digital Signature Lambda function

1. Navigate to Services > Lambda > DigitalSignature.
   
2. Add two environment variables:
   • CB_BUCKET -> AWS encrypted bucket (as defined in S3 Bucket section)
   • CB_KEY_FILE -> the file name where the key is store in the bucket (as defined in S3 Bucket section - .pem file)

MPO

At the end of this section you will have set up the connector in MPO and defined how users should be notified in case there are any issues with payments or manual steps that need to be taken.

Import connector

1. Login into the Workspace of your MPO environment.
2. Open the ClearBank Lenders vX.X.X (YYYY-MM-DD) folder, which was created when you imported the .zip file for this connector.
3. Open the Setup process, switch to View mode and select New task. Fill in the values for the listed keys and click Add task. Alternatively, the following JSON data can be used as Setup. Modify it accordingly and paste into the Code editor tab. This Setup process contains configuration data for two main areas; ClearBank and Mambu data.

   {
       "authorizationHeader": "ClearBank API Authorization Token -> token obtained from CB after uploading the .csr; this is used for authorising requests from MPO to CB",
       "authorizationTokenAWS": "token used to authorize requests, must match the authorization value from AWS Secret Manager",
       "clearBankConfigReference": "clearBank",
       "clearbankUrl": "https://[tenant].clearbank.co.uk",
       "clientMoneyAccount": "ClearBank Client Money Account ID -> displayed in ClearBank UI URL",
       "clearBankDisbursementChannelCHAPS": "CB_Loan_Disbursement_CHAPS",
       "clearBankDisbursementChannelFPS": "CB_Loan_Disbursement_FPS",
       "clearBankRepaymentChannelCHAPS": "CB_Loan_Repayment_CHAPS",
       "clearBankRepaymentChannelFPS": "CB_Loan_Repayment_FPS",
       "digitalSignatureGatewayUrl": "Invoke URL from DigitalSignature API Gateway",
       "hasVirtualAccountForPrePayment": "true/false",
       "hasVirtualAccountForDisbursement": "true/false",
       "hasVirtualAccountExternalID": "true/false",
       "mambuConfigReference": "mambu",
       "mambuUrl": "https://[tenant].mambu.com",
       "mambuUser": "Mambu username",
       "mambuPassword": "Mambu password",
       "mambuDisbursementChannelCHAPS": "MBU_Loan_Disbursement_CHAPS",
       "mambuDisbursementChannelFPS": "MBU_Loan_Disbursement_FPS",
       "mambuTransactionChannelCFieldSet": "_ClearBank_Transactions (Transaction Channel Field Set ID)",
       "mambuCreditorIBANCFieldId": "creditorIBAN (Custom Field ID)",
       "mambuCreditorNameCFieldId": "creditorName (Custom Field ID)",
       "mambuDebtorIBANCFieldId": "debtorIBAN (Custom Field ID)",
       "mambuDebtorNameCFieldId": "debtorName (Custom Field ID)",
       "mambuPaymentReferenceCFieldId": "paymentReference (Custom Field ID)",
       "mambuTransactionEndToEndIdCFieldId": "transactionEndToEndId (Custom Field ID)",
       "mambuLoanAccountCFieldSet": "_ClearBank_Loan_Accounts (Custom Field Set ID)",
       "mambuVirtualAccountIdCFieldId": "virtualAccountIdLoan (Custom Field ID)",
       "mambuIBANCFieldId": "ibanLoan (Custom Field ID)",
       "mambuAssignedLoanUserCFieldId": "assignedLoanUser (Custom Field ID)",
       "mambuTransactionStatusCFieldId": "transactionStatus (Custom Field ID)",
       "operatingAccountIban": "ClearBank Operating Account IBAN -> displayed in Clearbank UI",
       "secretKey":"key used to sign the requests from MPO to AWS, must match the signatureSecretKey value from AWS Secret Manager",
   }
   

   Notes:

   • The value of clientMoneyAccount can be found in ClearBank UI > Institution > Institution Accounts. Click on Client Money Account 2 (Wholesale) and copy the account ID from the URL (eg. hyc9704d-03fa-76a5-9f324-9c87966ec55e).
   • To get the value of digitalSignatureGatewayUrl please check the API Gateway for Digital Signature section.
   • If the hasVirtualAccountExternalID key is set to true in your ClearBank configuration, an IBAN will be automatically generated by ClearBank based on the unique external identifier provided, and when set to false an IBAN must have been previously generated or provided.
   • The property hasVirtualAccountForPrePayment applies only for Loan Repayment flows. When this property is set to false, the linkage between Mambu and ClearBank via Virtual Account ID and IBAN logic is skipped. When set to true, the linkage between Mambu and ClearBank via Virtual Account ID and IBAN logic is verified.
   • The property hasVirtualAccountForDisbursement applies only for Loan Disbursement flows. When this property is set to false, the linkage between Mambu and ClearBank via Virtual Account ID and IBAN logic is skipped. When set to true the linkage between Mambu and ClearBank via Virtual Account ID and IBAN logic is verified.
   • The custom field key mambuAssignedLoanUserCFieldId is optional. This field is used to save the encoded key of the user that is assigned to a specific loan account, for example, a Credit Officer. When this key is populated in your configuration and the notification method is task, all mambu Tasks created will be assigned to this user instead of the user defined under defaultTaskAssigneeKey.
     

Notifications setup

Open the Notification Setup process, switch to View mode and press New task. Fill all the parameters based on your selected notification channel and click Add task.

• Notification via Mambu Task
  
  Alternatively, the following JSON data can be used as Notification Setup. Modify it accordingly and paste into the Code editor tab.
  

  {
      "notificationConfigReference": "notification",
      "notificationChannel": "task",
      "webhookUrl": "",
      "webhookAPIKey": "",
      "zenDeskAPIKey": "",
      "zenDeskGroupId": "",
      "zenDeskLogin": "",
      "zenDeskSubdomain": "",
      "defaultTaskAssigneeKey": "6h0146096e3bce3a016e3bce3a2e0002 (Mambu User Encoded Key)",
      "adjustRepayment": "true/false",
      "checkPaymentScheme": "true/false",
      "createDisbursement": "true/false",
      "createPayment": "true/false",
      "createPrePayment": "true/false",
      "createVirtualAccount": "true/false",
      "disableVirtualAccount": "true/false",
      "searchLoanAndClientDetails":"true/false",
      "checkLoanIBANCF": "true/false",
      "reverseDisbursement": "true/false",
      "searchTransaction": "true/false",
      "searchVirtualAccountbyIBAN": "true/false",
      "updateCustomField": "true/false",
      "updateVirtualAccountOwnerName": "true/false"
  }
  

  Based on the selected notification method: task, zenDesk or URL the following values should be used:
  

• Notification via Mambu Task

  {
      "notificationChannel": "task",
      "defaultTaskAssigneeKey": "8a0146096e3bce3a016e3bce3a2e0002", // (Mambu User Encoded Key)
  }
  

• Notification via Webhook URL

  {    
      "notificationChannel": "URL",
      "webhookUrl": "link to external notification system"
  }
  

• Notification via ZenDesk Ticket

  {    
      "notificationChannel": "zenDesk",
      "zenDeskAPIKey": "IUbepAEuiyypiuLQOzhAQWumi8Pyww2ODVrn6Yux", // (ZenDesk API key)
      "zenDeskGroupId": "450002405759", // (ZenDesk User Group ID)
      "zenDeskLogin": "ZenDesk Username/Email",
      "zenDeskSubdomain": "clearBankMpo (ZenDesk subdomain)"
  }
  

  
  

ClearBank

At the end of this section you will have configured the necessary webhooks that will trigger various processes in the connector.

Configure webhooks

Configure webhooks for FasterPayments and CHAPS schemes by adding the AWS Gateway URL and enable each webhook event notification from Webhook Management.

ZenDesk

If you are using ZenDesk as your task management solution, you will need to have a ZenDesk account. At the end of this section you will have generated an API token, which will need to be provided when setting up the connector in MPO, and defined the target group for any notifications generated by the connector.

Generate API token

1. Login into ZenDesk with your account credentials.
   
2. Generate an API Token Click Save to return to the API page.

   Please note:
   You should copy the token and keep it somewhere secure, like a keychain or password manager. Once this window is closed, the full token will never be displayed again, only a truncated version of the token will be shown, for example:
   

3. Get the Group ID