FX Transfers

FX transfers are a transfer of funds where the beneficiary currency is different from the payer currency. To pay a beneficiary in a particular currency, the payer must hold funds in that currency or convert funds from one currency to another before making a payment. Currencycloud simplifies the process by taking the initial payment in any supported currency, performing the currency conversion, and executing the required payment to the beneficiary.

FX transfers are considered priority payments and are made using the global SWIFT network.

This integration relies on your bank or institution holding pre-funded collector accounts in Currencycloud. The amounts held in the collector accounts are reconciled according to a contractually agreed time frame. Money moves between collector accounts for the conversion and then from the target currency collector account to the beneficiary.

FX transfer flow

The first part of the FX flow involves the client receiving a quote for the exchange rate:

1. The client provides all the required data via digital channel to get the exchange rate for the FX transfer. The data required for an FX transfer can be provided via your banking UI, API calls, or by any other means, as long as the MPO receives the correct transfer details.
2. The exchange rate data is returned to the client via your banking UI.

The following sections go into detail on the rest of the process outlined in the sequence diagram.

Beneficiary retrieval and conversion creation

If the client is happy with the exchange rate and wishes to proceed with the transaction, they will need to provide the beneficiary ID. Once this is submitted, the 1.1. [Entry Point][Prefund] FX Transfer - > Create Conversion process starts gathering details about the deposit account, Mambu client record, and the beneficiary in Currencycloud using the ID provided. This first part can also be triggered by a Sync API call corresponding to the Mambu Process Orchestrator (MPO) process: CurrencyCloud_Vx.y.z > [Prefund] FX & House Transfer > FX Transfer > 1.1. [Entry Point][Prefund] FX Transfer - > Create Conversion.

Based on the value of the Currencycloud boolean subAccountEnabledInCC configuration property, the beneficiary details are retrieved with or without the on_behalf_of parameter. This parameter stores the value of the Currencycloud contact ID. If a Currencycloud account has been created with the special field on_behalf_of, when the beneficiary details are retrieved, the flag subAccountEnabledInCC from Currencycloud configuration must be set to true. The behavior when this property is outlined below:

• When subAccountEnabledInCC is set to true, beneficiary details will be retrieved with the on_behalf_of parameter. If no link is found on the client level, for example, the custom field contact ID does not exist or is empty, and an error is thrown and a notification is sent.
• When subAccountEnabledInCC is set to false, beneficiary details will be retrieved without the on_behalf_of parameter and there is no link made between the Currencycloud contact ID and the Mambu client.

The conversion starts in Currencycloud once the beneficiary, client, and deposit account are identified and validated and only if the deposit account currency matches the transaction’s sell currency. Depending on the subAccountEnabledInCC parameter value, the conversions can be created using the on_behalf_of parameter, when subAccountEnabledInCC is set to true, or can be created without it. After creation, the conversion is stored in the 4. [COMMON] Conversions SD state diagram with an intermediate status of Awaiting Funds. When the conversion webhook is received with a final status of either trade_settled or closed the process continues to the next step.

Conversion status updates

Whenever the status of a conversion in Currencycloud changes, a conversion webhook is sent. The webhook triggers the 2. [COMMON] Currency Cloud WEBHOOK receiver for CONVERSIONS [Linked to CCy webhook] process, where the decision to continue or close the FX transfer flow is taken.

More information on the statuses supported by the conversions webhook receiver can be found in Webhook Receivers.

Withdrawal and the Anti-Money Laundering extension

The second part of the FX transfer flow is covered by the 1.2. [Prefund] FX Transfer - > (Withdrawal + AML) process and is automatically triggered when a conversion webhook is sent and received by the 2. [COMMON] Currency Cloud WEBHOOK receiver for CONVERSIONS [Linked to CCy webhook] process, and if the conversion status is trade_settled.

Once the details for the withdrawal transaction have been validated, the Mambu client deposit account is debited with the sell_currency amount. The next step depends on the values of the amlExtensionUsed and checkThreshold parameters:

• If the amlExtensionUsed parameter is set to false, the transaction will be monitored by using an external Anti-Money Laundering (AML) system, the process ends, and the third part of the FX transfer flow should be triggered on demand by the client.
• If the amlExtensionUsed parameter is set to true and enableTransactionMonitoring 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 When 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 amlExtensionUsed parameter is set to true and enableTransactionMonitoring is set to false, no monitoring will be performed on the transaction, and the FX transfer continues with the next step of the flow.

The AML extension flow is optional.

Currencycloud transfer and fees

After the withdrawal transaction has been posted to Mambu, the 1.3. [Prefund] FX Transfer - > (CCy payment + Transfer + Fees) process is automatically triggered. If an AML system is being used, this process will only start once the transaction has also received the AML status Accepted.

Based on the value of the boolean subAccountEnabledInCC configuration property, the payment is created in Currencycloud with the buy_currency amount according to the following rules:

• When subAccountEnabledInCC is set to true during payment creation, the on_behalf_of parameter will be used and the payer details parameters should not be sent. These details will be populated using the information from the sub-account.
• When subAccountEnabledInCC is set to false during payment creation, the on_behalf_of parameter will not be used, and the payer details should be sent. In this case, the details are taken from those mapped to the Mambu client or group.

The following details should be sent when the payer is of the type Client:

{
        "payer_entity_type": "individual",
        "payer_first_name": "Asha",
        "payer_last_name": "Barron",
        "payer_date_of_birth": "1990-12-01",
        "payer_country": "DE",
        "payer_city": "Berlin",
        "payer_address": "Karl-Liebknecht Straße 5"
}

The following details should be sent when the payer is of the type Group:

{
        "payer_entity_type": "company",
        "payer_company_name": "My Company",
        "payer_country": "DE",
        "payer_city": "Berlin",
        "payer_address": "Karl-Liebknecht Straße 5",
        "payer_identification_type": "incorporation_number",
        "payer_identification_value": "45RTFVHYN"
}

Once the payment has been created in Currencycloud, the details are stored in the 1. [COMMON] Payments SD state diagram with an intermediate status of ready_to_send.

If multi-currency is enabled for your Mambu tenant, the transactions will be posted using a dedicated transaction channel, linked to general ledger accounts for that currency. Both Transit GL and CC Settlement GL prefixes should be defined in your Mambu configuration when setting up the connector. For example, if the transit GL account reference is 1234, then the transit general ledger account for payments in Euros will be 1234_EUR.

Manual journal entries are logged into Mambu - Debit, Transit GL and Credit, and Settlement GL - and payment details are copied into 1. [COMMON] Payments SD state diagram. After the withdrawal transaction custom fields are updated with the paymentID, conversionID, paymentShortRefId, and paymentStatus values from Currencycloud, a transfer will be created depending on the value of the Currencycloud subAccountEnabledInCC configuration property:

• When subAccountEnabledInCC is set to true, a transfer will be created with the Currencycloud contact ID as destination_account_id, Currencycloud House Account ID as source_account_id, and the sell_currency amount.
• When subAccountEnabledInCC is set to false, the transfer will be skipped in the FX flow.

If the fees object contains only zeroes or is empty, no fee is charged. For any other configuration, the feeAmount is calculated using the formula: feeAmount = fixed_amt + (variable_percent * transferred_amount / 100) and then charged. Fees are charged under the fee specified in the config, corresponding to the transaction currency. If no fee is specified in the Mambu configuration for a currency, and a fee amount was sent, the fee will be charged as an arbitrary fee.

Payment status updates

When the status of a payment is changed in Currencycloud, a payment webhook is triggered. The webhook triggers the 3. [COMMON] Currency Cloud WEBHOOK receiver for PAYMENTS [Linked to CCy webhook] process. This process updates the payment status of the associated Mambu withdrawal transaction using the appropriate custom field created when initially setting up the connector. Consult with your Mambu Customer Success Manager if you are unsure which custom field to use.

Reasons for failure can include rejection by the beneficiary bank or a failed Currencycloud compliance check. A payment that has been marked as completed by Currencycloud can later be rejected by the beneficiary bank. This triggers a failed payment webhook and starts the refund flow.

FX transfer payload details

The following data is required for executing the MPO process for 1.1. [Prefund] FX Transfer - > Create Conversion.

{
        "amount": 11,
        "beneficiaryId": "cabfa20f-6b27-4ff0-a78c-46787920dadc",
        "buy_currency": "EUR",
        "conversion_date": "2021-11-25",
        "depositAccountId": "XIWF285",
        "fees": {
                "fixed_amt": 10,
                "variable_percent": 0.33
        },
        "fixed_side": "sell",
        "payment_type": "priority",
        "reason": "Money to repay my mortgage",
        "reference": "Mortgage",
        "sell_currency": "USD",
        "term_agreement": true,
        "purpose_code": "CHC",
        "charge_type": "ours"
}

Webhooks

The FX transfer flow uses both the payments and conversions webhooks, as conversions are involved in the transfer logic.

• The conversions webhook receiver is used only in the MPO logic. The decision is made whether to continue or stop the flow based on the status updates received by this process.
• The payments webhook receiver process is used only to update the Mambu withdrawal transaction with the current payment status changes of the payment in Currencycloud.

Failed FX transfers

Failures are recorded in a state diagram in MPO. Depending on the nature of the failure, there are different remediation steps to take.

Anti-Money Laundering monitoring integration

The Currencycloud connector can be integrated with external anti-money laundering monitoring (AML) systems such as our Generic FinCrime connector. The outbound transaction is routed through the AML monitoring system to analyze and assess whether the transaction is suspicious or fraudulent. If the client is not using a proprietary transaction monitoring system - when amlExtensionUsed is set to true - transaction monitoring is done via the Generic FinCrime connector. This is a separate connector and should be installed and configured separately following its own documentation. Please make sure that under the transaction mapping object, the payment source FXTransferPrefundCCY object contains the corresponding mapping parameters.

The 1.2. [Prefund] FX Transfer - > (Withdrawal + AML) process is configurable through the option enableTransactionMonitoring and when amlExtensionUsed is true. The value of this parameter can be either true or false and it is stored in the Mambu configuration and is used to send the transaction through the AML system.

The transaction flow when enableTransactionMonitoring is true and amlExtensionUsed is true:

1. Retrieval of the deposit and client accounts from Mambu.
2. Retrieval of the beneficiary.
3. Withdrawal transaction in Mambu.
4. Generic FinCrime connector is called (through the AML Adaptor process):
   • If the transaction is Accepted, the payment flow continues.
   • If the transaction is Rejected, it is stored in the Suspended State Diagram (Outbound) and the AMLstatus custom field value for withdrawal transaction is updated with the value Rejected, followed by stopping the payment flow.
   • If the transaction is Suspended, it is stored in the Suspended State Diagram (Outbound) and the AMLstatus custom field value for withdrawal transaction is updated with the value Suspended, followed by stopping the payment flow until further response.
   • If the transaction returned with Error status, the transaction withdrawal is adjusted and the AMLstatus custom field value for withdrawal transaction is updated with the value Error, followed calling the Reverse Listener if needed.
   • If the transaction returned with Unknown status, the transaction withdrawal is adjusted and the AMLstatus custom field value for withdrawal transaction is updated with the value Unknown.
5. Currencycloud payment.
6. Posting manual journal entries in Mambu.
7. Optional: A Currencycloud transfer, only when the value of subAccountEnabledInCC is true.
8. Optional: Applying fees, only when fees are sent and are not zero.

Link between FX transfers and Generic FinCrime: In the AML Adaptor process, the FinCrime integration [ENTRY POINT/ To be linked to payment connector] process is called. In case of an error, the Reverse Listener is called, if needed.

Anti-Money Laundering Listener

The AML Listener process is called from the Generic FinCrime connector. Whenever a transaction with the AML status suspended is analyzed in the Generic FinCrime connector, the AML Listener process is triggered. This process receives the following parameters as input: AMLid, AMLstatus, and the paymentSource. Its main purpose is to route the transaction to the payment connector’s next steps based on the AML status received:

• For Accepted status: the process continues with the third part 1.3. [Prefund] FX Transfer - > (CCy payment + Transfer + Fees), which creates the payment in Currencycloud.
• For Rejected or Unknown status: the process patches the AML status to the withdrawal transaction in Mambu and the transaction is withheld.
• For Error status: the process patches the AML status to the withdrawal transaction in Mambu, and the withdrawal transaction is adjusted.

If the Currencycloud connector is re-uploaded or redeployed, the CCy_AML Listener(Local Outbound) alias linked process in the Generic FinCrime connector corresponding to the FXTransferPrefundCCY payment source must be updated.

Generic FinCrime redeployment

In case the Generic FinCrime connector is re-uploaded or redeployed, the ccy-fincrime-entry-point and ccy-fincrime-reverse-listener linked aliases in the Currencycloud connector must be updated with their new process IDs by following these steps:

1. Go to your MPO environment and select Aliases in the top-right menu button.
2. Search for CCy_FinCrime_Entry_Point and CCy_FinCrime_Reverse_Listener.
3. Right click their specific row and select Edit.
4. Change the Select process field.

Additional details

If the creation of a transfer in Currencycloud needs to be reversed, only a transfer that has the status pending can be cancelled. If the status is completed, the same transfer is posted again, but this time the destination account and the sender account are reversed. The last segment of a payment - moving the money from the Currencycloud Collector account to the beneficiary - is handled exclusively by Currencycloud and is outside of the scope of this connector.

If the payment or conversion is made after accounting cut-off, it is not performed on the same day. For more information about cut-off times in Currencycloud, check the documentation available for Currencycloud Payment timelines.

For more information on FX transfers in Currencycloud, refer to the Currencycloud Developer Center.