Integration Setup

MPO Connector Configuration

  1. Log in to the Workspace MPO environment. Click on Create button and select the From file option.
  2. Upload the JSON file with the pre-integration template. The ComplyAdvantage_TransactionMonitoring vX.X.X (YYYY-MM-DD) folder will be available in the workspace.
  3. Open the Setup process, switch to View mode and press New task. Fill all the parameters and click Add task. Wait until the task is processed (moves to the final point).

MPO. TM Setup

Alternatively, the following JSON data can be used as Setup, on top of the already defined objects at Customisations Configuration. Modify it accordingly and paste into the Code editor tab.

{
    "clientUsedFields": [{
        "targetId": "customer_first_name",
        "path": "firstName"
    }, ....], --> "Relevant pre-defined Mambu fields and custom fields added at client level"
    "groupUsedFields": [{
        "targetId": "customer_type",
        "value": "GROUP"
    }...], --> "Relevant pre-defined Mambu fields and custom fields added at group level"
    "incomingSCTTransactionUsedFields":[{
        "targetId": "tx_date_time",
        "path": "grpHdr.creDtTm"
    },
    {
        "targetId": "customer_account_id",
        "path": "cdtTrfTxInf[0].cdtrAcct.id.iban"
    }...], --> "Relevant fields from the incoming SCT transaction received from the Payment Gateway"
    "outgoingSCTTransactionUsedFields":[{
        "targetId": "tx_id",
        "path": "cdtTrfTxInf[0].pmtId.txId"
    },
    {
        "targetId": "counterpartyacct_bank_name",
        "path": "cdtTrfTxInf[0].dbtrAgt.finInstnId.bic"
    },...], --> "Relevant fields from the outgoing SCT transaction received from the Payment Gateway"
    "incomingSDDTransactionUsedFields":[{
        "targetId": "counterparty_reference",
        "path": "grpHdr.msgId"
    },
    {
        "targetId": "customer_bic",
        "path": "drctDbtTxInf[0].dbtrAgt.finInstnId.bic"
    }...], --> "Relevant fields from the incoming SDD transaction received from the Payment Gateway"
    "outgoingSDDTransactionUsedFields":[{
        "targetId": "tx_reference_text",
        "path": "drctDbtTxInf[0].purp.prtry"
    },
    {
        "targetId": "amount",
        "path": "drctDbtTxInf[0].intrBkSttlmAmt.value"
    }...], --> "Relevant fields from the outgoing SDD transaction received from the Payment Gateway"
    "depositAccountUsedFields":[{
        "targetId": "customer_account_number",
        "path": "_Deposit_Accounts.accountNumber"
    },
    {
        "targetId": "tx_account_balance",
        "path": "balances.availableBalance"
    }...],--> "Pre-defined Mambu fields and custom fields added at deposit account level"
    "complyAdvantageConfigReference": "complyAdvantage",
    "complyAdvantageUrl": "api.[CA-tenant].tm.complyadvantage.com",
    "complyAdvantageUsername": "CA username",
    "complyAdvantagePassword": "CA password",
    "customAMLReject":"true/false",
    "ignoreSoftStopAlert": "true/false",
    "isAMLwithExternalData": "true/false",
    "complyAdvantageSourceFormatName": "CA source format (e.g: TM Lite)",
    "mambuConfigReference": "mambu",
    "mambuUrl": "https://[tenant].[environment].mambucloud.com",
    "mambuUser": "Mambu username",
    "mambuPassword": "Mambu password",
    "mambuApiKey": "Mambu API key (payments/EAR)",
    "mambuBankBics":  [
        "HABALT22XXX",
        "BTRLRO22",
        "BTRLRO22XXX",
        "HABALT22"
    ], // --> the list of Mambu Bank BICs (payments/gateway)
    "complyAdvantageRetryLimit": "Number of retries that should be done for failed ComplyAdvantage API Calls",
    "complyAdvantageRetryInterval": "Time (in seconds) between retries for failed ComplyAdvantage API Calls",
    "mambuRetryLimit": "Number of retries that should be done for failed Mambu API Calls",
    "mambuRetryInterval": "Time (in seconds) between retries for failed Mambu API Calls",
    "notificationConfigReference": "notification",
    "notificationChannel": "",
    "defaultTaskAssigneeKey": "",
    "webhookUrl": "",
    "zenDeskAPIKey": "",
    "zenDeskGroupId": "",
    "zenDeskLogin": "",
    "zenDeskSubdomain": "",
    "submitTransaction": "true/false",--> "If set to true, a notification is sent for each transaction that fails to Submit transaction to ComplyAdvantage process"
    "amlPayment": "true/false"--> "If set to true, a notification is sent for each transaction that fails inside Send AML status to payment gateway process"

  }

Based on the selected notification method: task, zenDesk or URL the following JSON data data should be filled in:

  • Notification via Mambu Task
{
    "notificationChannel": "task",
    "defaultTaskAssigneeKey": "8a0146096e3bce3a016e3bce3a2e0002 (Mambu User Encoded Key)",
}
  • Notification via ZenDesk Ticket
{    
    "notificationChannel": "zenDesk",
    "zenDeskAPIKey": "IUbepAEuiyypiuLQOzhAQWumi8Pyww2ODVrn6Yux (ZenDesk API key)",
    "zenDeskGroupId": "450002405759 (ZenDesk User Group ID)",
    "zenDeskLogin": "ZenDesk Username/Email",
    "zenDeskSubdomain": "complyAdvantagempo (ZenDesk subdomain)"
}
  • Notification via Webhook URL
{    
    "notificationChannel": "URL",
    "webhookUrl": "Link to external notification system",
    "webhookApiKey": "API key to be used for webhookUrl"
}

Notes:

  1. A notification is sent only if the corresponding value for the process where the error occurred, submitTransaction or amlPayment parameters, is set to true in the Setup.
  2. All errors, except for customer implementation on Enrich with external data process, are also saved in State Diagrams in order to be analyzed.
  3. To get the values for mambuBankBics navigate to Mambu Gateway > Configuration > Schedulers and create a list with all BICs available in the Bank BIC column. Mambu Payment Gateway supports multiple BICs. The purpose of the BIC list is to identify the transaction direction: Inbound or Outbound.
  4. To get the value for complyAdvantageSourceFormatName navigate to ComplyAdvantage > Segments > Select source format in the the dropdown and copy the name of the source.
  5. In case customAMLReject is set to true: when a payment is rejected in Alerts Analyser Router [to be linked to CA], instead of sending the AML status Rejected back to SEPA Payments Gateway, a notification is sent according to the selected notification method.
  6. In case of a Suspended payment, the status in SEPA Payment Gateway remains unchanged, until all the alerts triggered by that payment are reviewed in ComplyAdvantage and transitioned from In Review to an end state of either Accepted or Rejected.

Extension Configuration

In order to allow data from systems other than Mambu (to be processed and sent to ComplyAdvantage) and to enable customer specific customisations (of the transaction sent to Comply Advantage), it’s necessary to:

  1. Set the variable isAMLwithExternalData to true in Mambu Config.
  2. Define the data model (object externalDataUsedFields from customization configuration), as per the example below.
   "externalDataUsedFields": [
        {
            "targetId": "customer_date_of_birth",
            "path": "customer_dob"
        },
        {
            "targetId": "customer_income_sources",
            "path": "customer_income.incomeSources"
        }
    ]
  1. Implement the MPO processes Enrich with external data and Custom processing of CA transaction:

Customer Processes

The Enrich with external data MPO process calls the external service and fetches the external data in the externalData object, while the Custom processing of CA transaction MPO process does the customer specific customisations of the CATransaction object. They should respect the following rules:

  • a successful flow for this process replies to the parent process with only the externalData object (for Enrich with external data process) or only with CATransaction object (for Custom processing of CA transaction process)
  • developing, maintaining and troubleshooting code, error handling (e.g. when fetching data from the external system is not working) for these MPO processes is in the customer’s responsibility; a Reply To process node needs to be placed before every final node in order to avoid tasks getting stuck in the Call Process node of the parent.
    The customer can customise the MPO process Custom processing of CA transaction by adding custom code in the Custom processing of CA transaction code node. There could be various customer specific use cases, but below are some examples:
    • if a field needs to be sent to Comply Advantage in a particular format (different from the input field format), this can be done by using specific Javascript instructions (like data.CATransaction.customer_date_of_birth=birthDateInitial.substring(0, 10) + " " + birthDateInitial.substring(11, 19) to submit customer date of birth as string in the format YYYY-MM-DD HH:MM:SS)
    • if a defined value for a field needs to be sent to Comply Advantage in some particular situation (otherwise a default value should be provided), this can be done by testing the specific case with an if condition and assigning the desired value accordingly (like if (data.CATransaction.hasOwnProperty("value_to_be_sent") {data.CATransaction.value_to_be_sent = "Yes"} else {data.CATransaction.value_to_be_sent = "No"})
  1. Create the MPO aliases pointing to the MPO processes defined above (i.e. ca-tm-enrich-with-external-data for Enrich with external data and ca-tm-customisation-for-customer for Custom processing of CA transaction):

Customer Aliases

Webhooks configuration

Mambu Payment Gateway webhook

To configure the Mambu Payment Gateway environment to receive Incoming and Outgoing transactions:

  • Log in to Mambu Payment Gateway environment.
  • Navigate to Configuration > System Properties.

Gateway Target URL

  • From section AML configuration check options: AML Credit Transfer Incoming Enabled,AML Credit Transfer Outgoing Enabled,AML Direct Debit Incoming Enabled, orAML Direct Debit Outgoing Enabled.
  • Add as Target URL the _copied webhook via JSON_ from the MPO Main Process Payment Receiver Router [link to Mambu Payment Gateway webhook]

MPO webhook URL

  • Click Update button to save the configuration in the Mambu Gateway.
  • Create Scheduler for each Bank BIC used in Payment Gateway and start the Schedulers for Incoming and Outgoing payments. Store the BICs values in MPO Setup process under the field mambuBankBics as string parameters separated by a comma: “HABALT22XXX”, “BTRLRO22”, “BTRLRO22XXX”, “HABALT22”.

Gateway Schedulers

ComplyAdvantage Alerts webhook

The MPO process Alerts Analyser Router [to be linked to CA] URL must be linked to ComplyAdvantage environment in order to be able to have a final status for Suspended payments (alerts were triggered); once a transaction is transitioned from In Review status to Accepted or Rejected status and one or multiple webhook(s) is sent by ComplyAdvantage as a result.

Note: ComplyAdvantage makes this configuration on the customer’s behalf.