Integration Setup

1. Installation and configuration

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

Setup

Alternatively, the following JSON data can be used as Setup. Modify it accordingly and paste into the Code editor tab. The Setup contains data for four config areas: ComplyAdvantage, Mambu, Customisation and Notification data.

{
    "complyAdvantageConfigReference": "complyAdvantage",
    "complyAdvantageUrl": "api.[CA-tenant].tm.complyadvantage.com",
    "complyAdvantageUsername": "CA username",
    "complyAdvantagePassword": "CA password",
    "complyAdvantageSourceFormatName": "CA source format",
    "customisationConfigReference": "customisation",
    "clientUsedFields": [
        {
            "targetId": "customer_name",
            "path": "mambuClientFullName"
        },
        {
            "targetId": "customer_country",
            "path": "addresses[0].country"
        }
    ],
    "groupUsedFields": [
         {
            "targetId": "customer_type",
            "value": "GROUP"
        }
    ],
    "depositUsedFields": [
        {
            "targetId": "customer_account_number",
            "path": "_Deposit_Accounts.accountNumber"
        },
          {
            "targetId": "tx_account_balance",
            "path": "balances.availableBalance"
        }
    ],
    "transactionUsedFields": [
          {
            "targetId": "tx_type",
            "path": "transactionType"
        },
        {
            "targetId": "tx_direction",
            "path": "transactionDirection"
        },
        {
            "targetId": "tx_id",
            "path": "transactionEncodedKey"
        },
        {
            "targetId": "tx_amount",
            "path": "amount"
        },
    ],
    "counterpartyUsedFields": [],
    "isExternalDataRequiredForAml": "true/false",
    "externalDataUsedFields": [],
    "amlAlertsActions": [
        {
            "label": "Hard Stop",
            "action": "R"
        },
        {
            "label": "Soft Stop",
            "action": "S"
        },
        {
            "label": "No Stop",
            "action": "I"
        }
    ],
    "mambuConfigReference": "mambu",
    "mambuUrl": "https://[tenant].[environment].mambucloud.com",
    "mambuUser": "Mambu username",
    "mambuPassword": "Mambu password",
    "searchAccountviaEAR": "true/false",
    "mambuApiKey": "Mambu API key (payments/EAR)",
    "mambuDepositAccountAssignedUserCFieldId": "6h0146096e3bce3a016e3bce3a2e0002 (Mambu User Encoded Key)",
    "mambuDepositAccountCFieldSet": "Custom field SET",
    "mambuDepositAccountIBANCFieldId": "custom Field ID",
    "mambuSchemeGLChannel": "GL code (e.g: scheme_GL)",
    "mambuSuspenseGLChannel": "GL code (e.g: suspense_GL)",
    "mambuTransitGLChannel": "GL code (e.g: transit_GL)",
    "mambuWithholdGLChannel": "GL code (e.g: withhold_GL)",
    "mambuTimezone": "Mambu tenant timezone",
    "notificationConfigReference": "notification",
    "notificationChannel": "",
    "defaultTaskAssigneeKey": "",
    "postJournalEntry": "true/false",
    "reverseManualJE": "true/false",
    "reverseWithdrawal": "true/false",
    "submitTransaction": "true/false",
    "cancelTransaction": "true/false",
    "copyPaymentDetails": "true/false",
    "timeForStatus": "Time (in seconds) - retry mechanism for failed API Calls",
    "webhookUrl": "",
    "zenDeskAPIKey": "",
    "zenDeskGroupId": "",
    "zenDeskLogin": "",
    "zenDeskSubdomain": ""
}

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

  • 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"
}

Notes:

  1. A notification is sent only if the value is set to true.
  2. When notifications are set to false or are set to true but the Mambu or Zendesk ticket fails, the responses are saved in state diagrams in order to be analyzed.
  3. To get the value for complyAdvantageSourceFormatName navigate to ComplyAdvantage > Segments > Select source format (dropdown) and copy the name of the source.
  4. To get the value for mambuTimezone navigate to Mambu environment Administration > General Setup > Organisation Details and copy the value of the Time Zone field.
  5. Custom field key mambuDepositAccountAssignedUserCFieldId is optional. This field is used to save the encoded key of the user that is assigned to a specific deposit account (i.e the Credit Officer). When it is populated in config and notification method is task all the Tasks created will be assigned to this user instead of defaultTaskAssigneeKey user.
  6. If EAR feature is used for IBAN linking then the config property searchAccountviaEAR must be set on true and property mambuApiKey should be populated - otherwise mambuApiKey should be empty.
  7. Allowed values for amlAlertsActions are R for Rejected, S for Suspended and I for Ignored.

1.1. Customization Configuration

To allow more flexibility with the fields that each customer sends to ComplyAdvantage, it is mandatory to define a customisationConfig. This should contain the fields to be sent for a specific entity: customer (client or group), transaction, deposit account and/or counter party.

The following arrays from the customisationConfig should be defined: clientUsedFields, groupUsedFields, transactionUsedFields, counterpartyUsedFields, and depositAccountUsedFields. If additional data from external systems needs to be monitored in ComplyAdvantage, the array externalDataUsedFields must be defined along with isExternalDataRequiredForAml = true from Mambu config.

If there are no fields to be mapped for any of these entities, then they should be set as empty arrays (e.g.: "groupUsedFields": []).

Inside customisationConfig used fields arrays, for each field to be sent to ComplyAdvantage there is an object containing two values:

  • target: the Field ID sent to ComplyAdvantage.
  • path: the Field ID from the source system where the value is taken from. The path can have the following format:
    • CustomFieldSet_Id.CustomField_Id, if the value is taken from Mambu custom fields (e.g. "path": "_Data_Clients.customerRisk").
    • _Object_._NestedObject_.field, if the value is taken from another entity, which has nested objects. Multiple levels of nesting can be used (e.g. "path": "balances.availableBalance").
    • _Array_[index].object.field, if the value is taken from an array (e.g. "path": "addresses[0].country").
    • Standalone fields (e.g. "path":"mambuClientFullName").

Important:

  • If a field needs to have the same value for all transactions sent to ComplyAdvantage, inside customisationConfig use "value" instead of "path" for that field (e.g. "value": "GBP").
  • Each source format from ComplyAdvantage has a unique structure and specific fields that must be mapped in order to be able to submit a transaction in ComplyAdvantage, using the customisationConfig defined during the Setup.
  • UK payments: two dedicated and empty fields in ComplyAdvantage scheme for customerIBAN, transactionID, and paymentScheme (fields used for reconciliation).
  • Due to the fact that each client has a unique structure and specific fields that must be mapped in order to be able to submit a transaction in ComplyAdvantage, some manual intervention is needed as described in the [Configuration] ClearBank Retailers with FinCrime file.

1.2. External Data Configuration

In order to allow data from systems other than Mambu to be processed and sent to ComplyAdvantage, it is necessary to:

  • Set the variable isExternalDataRequiredForAml to true in Mambu Config.
  • Define the data model (object externalDataUsedFields from customization configuration):
   "externalDataUsedFields": [
        {
            "targetId": "customer_date_of_birth",
            "path": "customer_dob"
        },
        {
            "targetId": "customer_income_sources",
            "path": "customer_income.incomeSources"
        }
    ]
  • Implement the process AML External Data: this process calls the external service and fetches the external data in the externalData object and should respect the following rules:
    • The successful flow for this process replies to the parent process only with the externalData object.
    • Error handling for this process, when fetching of data from the external system is not working, is the customer’s responsibility; before every Final node a Reply To process node needs to be placed in order to avoid the task getting stuck in the Call Process node of the parent in MPO.

1.3. AML Alerts Actions

In ComplyAdvantage config can be defined for up to three alerts, which must be stored in descending order based on the maximum priority action. The first alert should be the one with the higher priority from ComplyAdvantage, followed by the next one and so on.

If the third alert is stored, it’s purpose should be for analytics and reporting and not decisioning. If a transaction can be accepted or not this alert should always have the action I for Ignored. If only two alerts are defined in ComplyAdvantage this label can be removed from the list.

The label and the action for each alert is configurable, a Hard Stop can act like a Rejected payment or like a Suspended payment first.

"amlAlertsActions": [
        {
            "label": "Hard Stop",
            "action": "R"
        },
        {
            "label": "Soft Stop",
            "action": "S"
        },
        {
            "label": "No Stop",
            "action": "I"
        }
    ]

"amlAlertsActions": [
        {
            "label": "Hard Stop",
            "action": "S"
        },
        {
            "label": "Soft Stop",
            "action": "I"
        }
    ]

2. ComplyAdvantage Webhook Linkage

THe MPO process Alerts Analyser Router [to be linked to CA] URL must be linked to ComplyAdvantage’s 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 webhooks are sent by ComplyAdvantage as a result.

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