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, via Mambu APIs, identify the linked Mambu account and, if the account is valid, create the necessary deposit transaction, making the funds available to the client.

Main flow

Incoming payments flow

The process 6.[COMMON] Incoming payments webhook receiver [Linked to CCy webhook] 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, triggering a webhook. The only webhooks that are processed in this flow are those with message_type = cash_manager_transaction and notification_type = 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 AML 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 AML transaction monitoring is being used, the payment details are sent for an AML check.

Settle transaction

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 in the end of the happy flow from the client’s sub-account to the bank’s house account.

Webhook format

Incoming webhooks sent to the connector from Currencycloud should take the format below. More information on Currencycloud webhooks can be found in the push notifications section of their developer documentation.

{
   "header":{
      "message_type":"cash_manager_transaction",
      "notification_type":"cash_manager_transaction_notification"
   },
   "body":{
      "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "balance_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "account_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "currency":"EUR",
      "amount":"100000.00",
      "balance_amount":"100000.00",
      "type":"credit",
      "related_entity_type":"inbound_funds",
      "related_entity_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "related_entity_short_reference":"",
      "status":"completed",
      "reason":"",
      "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"
   }
}

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 Mambu Process Orchestrator 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.

Webhook Receivers