FX Transfers

FX transfers represent 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 final beneficiary.

FX transfers are also 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 final beneficiary.

Sequence diagram

FX transfer

FX transfer flow breakdown

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 obtain the exchange rate for the FX transfer.
  2. Exchange rate data is returned to the client via your 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 MPO process 1.1. [Entry Point][Prefund] FX Transfer - > Create Conversion 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 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 configuration property subAccountEnabledInCC, the beneficiary details are retrieved with or without the on_behalf_of parameter. This parameter stores the value of the Currencycloud contact ID. The behavior when this property is enabled or disabled is outlined below:

  • When subAccountEnabledInCC is set to true, beneficiary details will be retrieved with the on_behalf_of parameter. In case no link is found on the client level, for example the custom field contact ID does not exist or is empty, 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 Currencycloud contact ID and Mambu client.

Once the beneficiary, client, and deposit account are identified and validated and only if the deposit account currency matches the transaction sell currency, the conversion is initiated in Currencycloud. 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 with the next step.

Conversion status updates

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

Conversion statusAction
trade_settledContinue FX transfer flow.
closedStop the FX transfer flow.

Please Note
More information on the statuses supported by the conversions webhook receiver can be found in the webhook receivers article.

Withdrawal and AML extension

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

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 amlExtensionUsed parameter:

  • If the amlExtensionUsed parameter is set to false, the transaction will be monitored by using an external 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 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.

Please be Aware
The AML extension flow is optional.

Currencycloud transfer and fees

After the Withdrawal transaction has been posted to Mambu, the MPO process 1.3. [Prefund] FX Transfer - > (CCy payment + Transfer + Fees) 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 configuration property subAccountEnabledInCC, 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, therefore the payer details parameters should not be sent. These will be populated using the details from the sub-account.
  • When subAccountEnabledInCC is set to false during payment creation, the on_behalf_of parameter will not be used, therefore 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 a Client:

{
        "payer_entity_type": "individual",
        "payer_first_name": "Mambu Client First Name", // -> required
        "payer_last_name": "Mambu Client Last Name", // -> required
        "payer_date_of_birth": "Mambu Client Birth Date",
        "payer_country": "Mambu Client Country",
        "payer_city": "Mambu Client City",
        "payer_address": "Mambu Client Address (line 1)"
}

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

{
        "payer_entity_type": "company",
        "payer_company_name": "Mambu Group name", // -> required
        "payer_country": "Mambu Group Country",
        "payer_city": "Mambu Group City",
        "payer_address": "Mambu Group Address (line 1)",
        "payer_identification_type": "incorporation_number", // -> required for `payment_type`: **priority**,
        "payer_identification_value": "Mambu Group ID" // -> required for `payment_type`: **priority**
}

Once the payment has been created in Currencycloud, its 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 GL account for payments in Euros will be 1234_EUR).

Manual journal entries are logged into Mambu - Debit, Transit GL & Credit, 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 configuration property subAccountEnabledInCC:

  • 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 (see below for examples), 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": {
       "variable_percent" : 0,
       "fixed_amt" : 0
     }
}
 {
    "fees": {
        "fixed_amt" : 0
      }
}
{
    "fees": {
        "variable_percent" : 0
      }
}
{
   "fees": {
      }
}

Payment status updates

Whenever the status of a payment is changed in Currencycloud, a payment webhook is triggered. The webhook triggers the MPO process 3. [COMMON] Currency Cloud WEBHOOK receiver for PAYMENTS [Linked to CCy webhook]. This process updates the payment status of the associated Mambu Withdrawal transaction using the appropriate custom field created as part of the Mambu setup process.

Payment statusAction
ready_to_sendUpdate the status of the Withdrawal transaction in Mambu.
completedUpdate the status of the Withdrawal transaction in Mambu.
failedUpdate the status of the Withdrawal transaction in Mambu.
Refund process is triggered.

Reasons for failure can include rejection by the beneficiary bank or a failed Currencycloud compliance check.

Please be Aware:
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.

Main structure

KeyTypeDescription
amountnumberAmount of the fixed buy or sell currency.
beneficiaryIdstringThe ID of the beneficiary.
buy_currencystringCurrency purchased. Three-digit code.
conversion_datestring (date)Earliest delivery date. ISO 8601 format YYYY-MM-DD.
depositAccountIdstringMambu debit account - sell currency.
feesobjectSee fees.
fixed_sidestringFix the buy or sell currency, i.e, whether the amount field relates to the buy currency or the sell currency.
payment_typestringCan be either priority or regular.
referencestringA reference for the payment.
reasonstringClient-generated reason for payment. Free form text.
sell_currencystringCurrency sold. Three-digit code.
term_agreementbooleanIndicates agreement to terms and conditions.

Fees object

KeyTypeDescription
fixed_amtnumberThe fixed fee amount charged. Optional.
variable_percentnumberThe fee percentage. Optional.
Click to see JSON format for FX transfers
{
    "amount": <amount>,
    "beneficiaryId": <beneficiary ID>,
    "buy_currency": <buy currency>,
    "conversion_date": <conversion date>,
    "depositAccountId": <deposit account id>,
    "fees": {
        "fixed_amt": <fixed amount fee>,
        "variable_percent": <fee percentage>
    },
    "fixed_side": <fixed side>,
    "payment_type": <priority / regular>,
    "reason": <payment reason>,
    "reference": <reference>,
    "sell_currency": <sell currency>,
    "term_agreement": <term agreement>
}
Click to see example of FX transfers JSON body
{
    "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
}

Webhooks used

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.

StepPoint of failureActions
1Get Mambu deposit account detailsThe error is registered in the Error Handling SD (FX payments) state diagram and a notification is sent.
Stop flow.
1Get Mambu client or group detailsThe error is registered in the Error Handling SD (FX payments) state diagram and a notification is sent.
Stop flow.
1Get Currencycloud beneficiary detailsThe error is registered in the Error Handling SD (FX payments) state diagram and a notification is sent.
Stop flow.
1Create conversion in CurrencycloudThe error is registered in the Error Handling SD (FX payments) state diagram and a notification is sent.
Stop flow.
1Store the conversion details in the MPO conversion state diagramThe error is registered in the Error Handling SD (FX payments) state diagram and a notification is sent.
Stop flow.
2Create withdrawal transaction - debit client deposit account in MambuThe error is registered in the Error Handling SD (FX payments) state diagram and a notification is sent.
Initiate conversion in Currencycloud - mirror conversion using the Error Handling for 1.2. FX Payment process.
Stop flow.
3Create payment transaction in CurrencycloudThe error is registered in the Error Handling SD (FX payments) state diagram and a notification is sent.
Initiate conversion in Currencycloud - mirror conversion and the Withdrawal transaction is adjusted or refunded through a deposit transaction.
Stop flow.
3Create manual journal entries in MambuThe error is registered in the Error Handling SD (FX payments) state diagram and a notification is sent.
The process continues.
3Copy Currencycloud payment details to Payments State DiagramThe error is registered in the Error Handling SD (FX payments) state diagram and a notification is sent.
The process continues.
3Update Mambu custom fields at Withdrawal transaction with Currencycloud payment and conversion detailsThe error is registered in the Error Handling SD (FX payments) state diagram and a notification is sent.
The process continues.
3Create transfer in CurrencycloudThe error is registered in the Error Handling SD (FX payments) state diagram and a notification is sent.
The process continues.
3Calculating fee amountThe error is registered in the Error Handling SD (FX payments) state diagram and a notification is sent.
The process continues.
3Create fee transactionThe error is registered in the Error Handling SD (FX payments) state diagram and a notification is sent.
The process continues.
3MPO receives a failed payment status from Currencycloud webhookThe paymentStatus of the transaction in Mambu is updated to failed.
[common] Refund flow router process is called and adjusts the fee transaction, if applied, posts a deposit transaction as a refund of the withdrawal, adjusts the manual journal entries, creates a mirror conversion in Currencycloud, reverses or cancels the Transfer in Currencycloud .
Stop flow.
2,3The refund process failsThe error is registered in the Error Handling SD (FX payments) state diagram.
Stop flow.

AML monitoring integration

The Currencycloud connector can be integrated with external anti-money laundering monitoring 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 (amlExtensionUsed = true), transaction monitoring is done via the Generic FinCrime connector, which 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 paymentSource FXTransferPrefundCCY object contains the corresponding mapping parameters.

TM option

Where AML fits in the flow

The 1.2. [Prefund] FX Transfer - > (Withdrawal + AML) process is configurable through the option enableTransactionMonitoring and amlExtensionUsed is true. The value of this parameter can be either true or false. It is stored in the Mambu config and is used to send the transaction through the AML system. See the MPO Setup section for more information.

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. Currencycloud transfer. Optional - only when subAccountEnabledInCC = true.
  8. Applying the fees. Optional - only when fees are sent and are non-zero.

Linkage 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.

AML 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 by interpreting the alerts webhook received from ComplyAdvantage and a final status is identified, 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) that 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.

In case 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 click on the top right menu button Aliases.
  2. Search for CCy_FinCrime_Entry_Point and CCy_FinCrime_Reverse_Listener. Search these aliases
  3. Right click their specific row and select Edit. Click on Edit button
  4. Change the Select process field. Change the process ID

Additional details

  1. 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. If a Currencycloud account has been created with the special field on_behalf_of, then, when the beneficiary details are retrieved, the flag subAccountEnabledInCC from Currencycloud config must be set to true.
  3. 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.
  4. The last segment of a payment - moving the money from the Currencycloud Collector account to the final beneficiary is handled exclusively by Currencycloud and is outside of the scope of this connector.
  5. 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.
  6. For more information on FX transfers in Currencycloud, refer to the Currencycloud Developer Center.