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. Transaction Channels
CHAPS Disbursement Transaction Channel
FPS Repayment Transaction Channel

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. Administration
      Loan Account Virtual Account Id
      Loan Account IBAN
  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. Transactions Custom Fields Transactions Custom Fields

Webhooks for loan disbursement

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

TargetOn EventConditions
Clients and/or GroupsLoan DisbursementWhen:
Channel -> EQUALS -> MBU_Loan_Disbursement_CHAPS or MBU_Loan_Disbursement_FPS
And:
transactionStatus is Empty

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.

Loan Disbursement Webhook

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.

    Edit Loan Disbursement Clients Webhook Edit Loan Disbursement Groups Webhook 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. Closed Loan Account Webhook

Loans written off

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

TargetOn EventWhen
Clients and/or GroupsLoan Account Closed (Repaid)When
virtualAccountId -> NOT EMPTY
And
Account State -> EQUALS -> Closed or Closed(Written Off)

Loan Write Off Webook

  • 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:

TargetOn EventWhen
Clients and/or GroupsLoan Write OffWhen
virtualAccountId -> NOT EMPTY
And
Account State -> EQUALS -> Closed or Closed(Written Off)

Loan Account Closed (Repaid) Webook

  • 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.
    Create 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. Upload Lambda Function Save Upload Lambda Function After uploading, you should find the following files in the Lambda function Code source:
    Lambda Function File Structure

  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. ClearBank Download Public Key The public key needs to be uploaded to AWS as a file named publicKey.pem that is available to the Clearbank lambda function: Lambda Function New File Copy and paste the key you downloaded from ClearBank into this file. It should look similar to this:
    Lambda Function CB Public Key

  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.
    Environment Variables

Notes:

  • To get the values for Secret key, API login and process ID required for Lambda function create an API key for the Webhook Listener [AWS] process.
  • The value for company_id can be taken from the URL regardless of the opened process and it is always the last value in the endpoint that starts with i - (e.g. https://[tenantName].[environment].mpo.mambu.com/editor/1/2/i000000000). MPO. Company Id
  • Open the Webhook Listener [AWS] process and click on Start node. Select the previously created API key.
    MPO. Api key
  1. 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.
    Basic Settings

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: AWS Secrets Manager Afterwards, you need to create a new secret like this: New AWS Secret configuration - step 1 New AWS Secret configuration - step 2

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

New AWS Secret configuration - step 3 New AWS Secret configuration - step 4 New AWS Secret configuration - step 5

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

New AWS Secret configuration - step 6

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.: View Lambda Function role document - 1 View Lambda Function role document - 2
  3. Create Function.
  4. Upload the .zip file digitalSignature_kms_lambda.zip which you will find in the GitLab repository for this connector. Upload Lambda Function
  5. Add an environment variable to point to the previously defined AWS secret. Edit Environment Variables Add MPO Secret Id Environment Variables

→ 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: Edit Environment Variables Add MPO Secret Id Environment Variables

  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.: View Lambda Function role document - 1 View Lambda Function role document - 2

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. Upload Lambda Function Basic Settings
  5. Add the SECRET_ID environment variable: Edit Environment Variables Add 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). Create REST API Create API
  2. Open your new API. Go to Resources > Actions and click on Create Resource. 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).
    Create POST Method Request
  4. Select Method Request section from API Gateway (POST). Add Request Validator - Validate query string parameters and headers under Settings. Method Request
  5. Select the Integration Request section from API Gateway (POST) and add Mapping Templates, selecting application/json as the content type. Integration Request Mapping Template 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
    }
}
  1. Open the Method Response section from API Gateway (POST). Map the success response message for Clearbank and add DigitalSignature as a header.
    Method Response Map 401 response (Unauthorized) to an Error response body model. Method Response
  2. Select the Integration Response section from API Gateway (POST). Map ClearBank DigitalSignature as a header and success response message.
    Integration Response
    ##  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: Integration Response

{
  "errorMessage" : "$input.path('$.errorMessage')"
}
  1. Select Deploy API from the Actions menu.
    Deploy API Deploy API Stage
  2. 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.
    Create Authorizer
    Authorizer
  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. Method Request Method Request Header
  6. Open the Integration Request section from API Gateway (POST). Add Mapping Templates for the content type application/json. Integration Request Mapping Template
    {
        "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.
    Method Response For error messages, map Response Body model to Error: Method Response Method Response
  8. Open the Integration Response section from API Gateway (POST). Map ClearBank DigitalSignature header and success response message.
    Integration Response
    ##  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: Integration Response

    {
      "errorMessage" : "$input.path('$.errorMessage')"
    }
    
  9. Select Deploy API from the Actions menu. Deploy API Deploy API Stage
  10. Copy the Invoke URL available under the Stages section and keep this to hand. This will be required later for setting up MPO. Invoke URL - Digital Signature

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). Generate Certificate & Token
  3. From function code rename generate CSR file to index. Then select Deploy and then Test. Generate Certificate & Token
  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.
    Generate API Token
  4. Copy the API Token and keep it to hand, it will be needed later.

Key Management Service (KMS)

Note: this step can be skipped if CloudHSM solution is used.

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. KMS Key

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

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

    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. KMS Key Policy

S3 Bucket

  1. Navigate to Services > S3. Select Buckets and create a new bucket by clicking Create bucket. S3 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.
    S3 Default Encryption
  3. In the Set Permissions screen, check the option Block all public access. S3 Blocking Access
  4. Review the configuration and check everything is correct. S3 Review Encryption S3 Encryption S3 Default Encryption KMS
  5. Upload the private key (file with extension .pem that was created in the certificate and token section) to the newly created bucket. S3 Upload
  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. S3 Set Permissions S3 Set Properties S3 Set Properties Encryption
  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.
    DigitalSignature Permissions
  2. Check that the AmazonS3ReadOnlyAccess policy is attached to the DigitalSignature Lambda function execution role. DigitalSignature Roles
  3. Update the environment variables and click Save. Environment Variables Basic Settings

Note: If AmazonS3ReadOnlyAccess policy is not attached to Lambda function execution role, it is necessary that an Admin(AWS) performs the actions in the screenshots below:

  1. Attach Policy
  2. Attach Policy
  3. Attach Policy
  1. 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. KMS Key KMS Role

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) DSH Environment Variables

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. MPO. Setup 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.

Please note:
If using ZenDesk as your ticketing solution, see the ZenDesk section below for details on how to generate an API key for this integration.

  • Notification via Mambu Task
    MPO. Notification Setup 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)"
    }
    

    MPO. Notification Setup ZenDesk

Notes:

  1. A notification is sent only if the value is set to true in the Notification Setup.
  2. When notifications are set to false or are set to true but the Mambu/Zendesk ticket fails, the responses are saved in State Diagrams in order to be analyzed.
  3. Tenant timezone format should be checked. Integration flows for Disbursement and Repayment are using current date and the tenant date format should match the one returned in Mambu API calls. Currently the format used in MPO and to perform Mambu transactions is: $.date(%y-%m-%dT%h:%i:%sZ) (e.g. 2020-03-05T08:16:32Z). Clearbank RequestExecutionDate follows the ISO 8601 format (e.g. 2018-03-23T17:15:12.124Z).

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. Virtual Account Webhooks
FPS_CHAPS Webhooks


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 Admin Generate 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:
    Truncated API Token

  3. Get the Group ID
    Manage Group Group ID