House Transfers

The House Transfer flow is used for intrabank exchanges between two active deposit accounts owned by the same client, in different currencies.

Sequence diagram

House Transfer flow breakdown

The first part of the House Transfer flow involves the client getting a quote for the exchange rate:

1. The client provides all the required data via digital channel to obtain the exchange rate for the House 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.

Validate currency and conversion

If the client is happy with the exchange rate and wishes to proceed with the transaction, the MPO process 1. [Entry Point] [Prefund] House Account - > Create Conversion is triggered and begins to verify the deposit account currency with the inputted currency. Depending on the fixed_side value parameter, the currency check can refer to two pairs:

• either between the Debit Deposit Account currency and the sold currency (when the fixed_side value is set to sell)
• or between the Credit Deposit Account currency and the bought currency (when the fixed_side value is set to buy)

Once the currencies are checked, the conversion is initiated in Currencycloud. The conversion is then 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.

Depending on the value of postTransactionAfterSettlement parameter the processing of house transfer is as follows:

• When postTransactionAfterSettlement is set to false, the payment is processed outside of the settlement window, without waiting for the status of a conversion from Currencycloud The process 2.[Prefund] House Account -> register the exchange between Mambu accounts is triggered instantly.
• When postTransactionAfterSettlement is set to true, the transaction should be posted only during the settlement cycle. The process 2.[Prefund] House Account -> register the exchange between Mambu accounts is triggered only when the conversion status is trade_settled.

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 > House Transfer > 1. [Entry Point] [Prefund] House Account - > Create Conversion.

Conversion status updates

Whenever the status of a conversion is changed in Currencycloud, a conversion webhook is triggered. The webhook triggers an MPO process responsible with deciding whether to continue with the house transfer flow or not.

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

Withdrawal, deposit and fee posting

1. Debit client source account with the sell_currency amount.

2. Credit client target account with the buy_currency amount.

3. If the fees object is 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. The examples below would result in no fees being charged.

   {
     "fees": {
       "variable_percent" : 0,
       "fixed_amt" : 0
     }
   }
   

   {
     "fees": {
       "fixed_amt" : 0
     }
   }
   

   {
     "fees": {
       "variable_percent" : 0
     }
   }
   

   {
     "fees": {
     }
   }
   

4. The custom field indicating the fee gets patched to both the withdrawal and deposit transaction for uniformity, however, it is only charged for the withdrawal.

5. Fees are charged under the fee specified in the config, corresponding to the transaction currency. If no fee is specified in the Mambu config for a currency, and a fee amount was sent, the fee will be charged as an arbitrary fee.

When setting up the connector, you will be able to define some configuration options. Depending on the settings provided, the transaction will happen instantly or will wait for an event before going through. These settings are part of the JSON configuration object you will provide during MPO Setup.

House Transfer payload details

Data required for executing the MPO process for House Account transfer flow:

Structure

Fees object

The Fees object is optional. It’s possible to send a fixed amount, a percentage, or none. By sending an empty object or 0, no fees will be charged.

Example house transfer JSON body

{
  "debitAccountId": "ABC123",
  "sell_currency": "EUR",
  "creditAccountId": "DEF456",
  "buy_currency": "JPY",
  "fixed_side": "buy",
  "conversion_date": "2021-10-24",
  "fees": {
    "variable_percent" : 2.76,
    "fixed_amt" : 14.00
  },
  "exchangeAmount": 46290
}

Webhooks used in this flow

The House Transfer flow only uses the conversion webhook functionality.

• The conversions webhook receiver is used only in the MPO logic. Based on the status updates done through this process, the decision is made whether to continue or stop the flow.

More information on the conversion webhook receiver can be found in Webhook Receivers.

Failed house transfer

Failures are generally recorded in a state diagram in the Mambu Process Orchestrator. Based on the nature of the failure there are different remediation steps to take. In all cases, if notifications for failed payments has been set to true in your connector settings, a notification will be sent to the nominated user.

Additional details

The data required for a House Transfer can be provided via the bank UI, API calls or by any other means, as long as the MPO receives the correct transfer details.