Incoming Payments

Jump to Section

Sub-accounts in Currencycloud can accept incoming payments in a variety of currencies. The connector exposes a webhook URL where transaction notifications can be sent from Currencycloud. When this webhook URL receives a notification that a transfer has been made, the connector will identify the linked Mambu account via Mambu APIs and, if the account is valid, create the necessary deposit transaction. This will make the funds available to the client.

Incoming payments flow

The 6.[COMMON] Incoming payments webhook receiver [Linked to CCy webhook] Mambu Process Orchestrator (MPO) process is used in the integration as a receiver for Currencycloud push notifications for incoming payments. The purpose of this process is to handle any incoming payments received by a client’s sub-account in Currencycloud.

Receive payment notification

The process is triggered whenever a funding transaction changes state in Currencycloud, which triggers a webhook. The only webhooks that are processed in this flow are those with message_type is cash_manager_transaction and notification_type is cash_manager_transaction_notification. All other webhooks are ignored by this process. The process uses the account_id parameter from the incoming webhook to identify the corresponding deposit account in Mambu.

Enrich transaction and carry out Anti-Money Laundering checks

Once the Mambu deposit account has been identified, further details about the payment are fetched from Currencycloud, including any details about the sender of the payment. Optionally, if Anti-Money Laundering (AML) transaction monitoring is being used, the payment details are sent for an AML check.

The AML transaction monitoring depends on the enableTransactionMonitoring and checkThreshold parameter:

If the enableTransactionMonitoring parameter is set to true, the transaction will be monitored using the Generic FinCrime connector.
- If the checkThreshold parameter is set to true, then the transaction calculation threshold is compared with the value stored in Mambu configuration for the threshold parameter. If the threshold calculated value is:
  - less than or equal to the home base currency threshold amount then the transaction will not be sent to be monitored.
  - greater than the home base currency threshold amount then transaction will be monitored.
- If the checkThreshold parameter is set to false, then the transaction will be sent to be monitored.
- If the checkThreshold parameter is set to true and the value of threshold parameter is an empty string ("") or 0 (number), and/or the value of mambuHomeCurrency is an empty string ("") then all transactions will be monitored.
If the enableTransactionMonitoring parameter is set to false, no monitoring will be performed on the transaction, and the process continues with the next step of the flow.

Once both parties have been identified and if all AML checks are accepted, the funds are settled in the client’s Mambu deposit account. In Currencycloud, the money is transferred at the end of the successful flow from the client’s sub-account to the bank’s house account.

Webhook

Incoming webhooks sent to the connector from Currencycloud should take the format below. For more information on Currencycloud webhooks, see the push notifications section of their developer documentation.

{
        "header":{
                "message_type": "cash_manager_transaction",
                "notification_type": "cash_manager_transaction_notification"
        },
        "body":{
                "id": "3-c629166d-eefb-442b-a367-ee1220fbc55e",
                "balance_id": "87ba507d-0edb-489f-8f32-b7795a0f40f8",
                "account_id": "a5bfec96-e651-4d6d-94c8-05c291adfa37",
                "currency": "ZAR",
                "amount": "3001.40",
                "balance_amount": "23203.05",
                "type": "credit",
                "related_entity_id": "f59b7f94-d1ad-4937-92d5-d3dbb7da7838",
                "related_entity_short_reference": "",
                "status":" completed",
                "reason": "To pay for mortgage",
                "settles_at": "2018-01-05T14:39:41+00:00",
                "created_at": "2018-01-05T14:39:41+00:00",
                "updated_at": "2018-01-05T14:39:41+00:00",
                "completed_at": "2018-01-05T14:39:41+00:00",
                "action": "funding"
        }
}

Parameter	Type	Description
`header`	object	Object containing header information.
`header.message_type`	string	The message type.
`header.notification_type`	string	The notification type.
`body`	object	The body of the webhook request from Currencycloud.
`body.id`	string	The ID of webhook request from Currencycloud.
`body.balance_id`	string	The ID of the balance provided.
`body.account_id`	string	The ID of the beneficiary account.
`body.currency`	string	The currency as a three-letter code.
`body.amount`	string	The amount of the payment.
`body.balance_amount`	string	The balance of the payment.
`body.type`	string	The type of the transaction.
`body.related_entity_type`	string	The ID of teh related entity.
`body.related_entity_id`	string	The ID of the initial payment, which is related to the webhook received from Currencycloud.
`body.status`	string	The status of the webhook.
`body.reason`	string	Additional information about the reason for the payment.
`body.settles_at`	string	The date when the payment is settled in the ISO 8601 format.
`body.created_at`	string	The date when the payment was created in the ISO 8601 format.
`body.updated_at`	string	The date when the payment was updated in the ISO 8601 format.
`body.completed_at`	string	The date when the payment was completed in the ISO 8601 format.
`body.action`	string	The corresponding action in Currencycloud.

Failed incoming payment

There are a number of points in the process where failures could occur. Any failures are generally recorded in a state diagram in MPO and a notification is sent.

Point of Failure	Action
Find Mambu deposit account	If the account is not found or the currency of the account does not match the currency of the incoming payment, there will be no deposit transaction recorded and a notification will be sent.
AML status == `rejected`	If the initial AML checks return the status `rejected`, a notification will be sent.
AML status == `error`	If the initial AML check reports an error, any general ledger entries for the transfer will be reversed and a notification sent.
Final AML status == `rejected`	If the final AML check reports that the transfer is rejected, a notification is sent.
Final AML status == `unknown`	If the final AML check reports a status of unknown, a notification is sent and further investigations should be made.
Final AML status == `error`	If the final AML check reports an error, any general ledger entries for the transfer will be reversed and a notification sent.

Applying fees

The connector supports two types of fees which can be applied to deposit accounts each time an incoming transaction is registered:

Arbitrary fees.
Manual fees with no amount defined.

Manual fees are charged under the fee encodedKey specified in the config object productFee, corresponding to the transaction currency. If a manual fee is used, all the deposit accounts on which the incoming transactions are posted must be of the same deposit product under which the fee is defined. The same type of fee will be applied to all the transaction types in a specific currency.

If no fee encodedKey is mentioned in the Mambu config for a currency, and the incomingPaymentsFee object contains valid details to calculate the fee value, the fee amount is calculated and then charged as an arbitrary fee.

The fee amount is calculated using the formula feeAmount = fixed_amt + (variable_percent * transferred_amount / 100). The fixed amount and the variable amount are specified as values for the corresponding properties fixed_amt and variable_percent, which are defined under the incomingPaymentsFee object in Mambu config.

At the fee transaction level the deposit transaction id is detailed in the notes field. The fee amount is specified at deposit transaction level in a dedicated custom field. If a fee cannot be posted, due to an MPO error or insufficient funds, a notification is created and the error details are saved in a dedicated state diagram. The fee transaction then needs to be manually applied.

Negative values are not valid values for these two mentioned properties. If a property has a negative value then a notification with specific details will be created and the fee will not be applied.

Webhook Receivers