House Transfers

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

House Transfer

House transfer flow

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 get 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 Mambu Process Orchestrator (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 started 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 2.[Prefund] House Account -> register the exchange between Mambu accounts process is triggered instantly.
  • When postTransactionAfterSettlement is set to true, the transaction should be posted only during the settlement cycle. The 2.[Prefund] House Account -> register the exchange between Mambu accounts process 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 for deciding whether to continue with the house transfer flow.

Conversion statusAction
trade_settledContinue with step two of house transfer flow.
closedStop the house transfer flow.

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.
  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 with your Mambu Customer Success Manager, you will be able to decide some configuration options. Depending on the settings provided, the transaction will happen instantly, or the connector will wait for an event before moving forward.

House transfer payload details

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

{
        "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
}
ParameterTypeDescriptionRequired
debitAccountIdstringThe Mambu debit account ID for the sell currency.YES
sell_currencystringThe currency being sold as a three-letter code.YES
creditAccountIdstringThe Mambu credit account for the buy currency.YES
buy_currencystringThe currency purchased as a three-letter code.YES
fixed_sidestringThe operation type, which may be buy or sell.YES
conversion_datestring(date)Date of delivery of the purchase currency in the ISO 8601 format YYYY-MM-DD. If not specified, deals settle in two working days.NO
feesObjectSpecifies the types of fees being charged.NO
fees.variable_percentnumberA fee charged as a percentage of the amount being converted.NO
fees.fixed_amtnumberA fixed, flat fee that will be charged for the conversion.NO
exchangeAmountnumberAmount of the fixed buy or sell currency.YES

Webhooks

The house transfer flow uses the conversion webhook functionality. The conversions webhook receiver is used only in the MPO logic. Based on the status updates in 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 MPO. 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.

StepPoint of failureAction
1Validate deposit account currencyThe error is registered in the Error Handling SD (FX & House) state diagram.
Stop flow.
1Get Mambu client detailsThe error is registered in the Error Handling SD (FX & House) state diagram.
Stop flow.
1Create conversion in CurrencycloudThe error is registered in the Error Handling SD (FX & House) state diagram.
Stop flow.
1Store the conversion information in MPO conversion state diagramThe error is registered in the Error Handling SD (FX & House) state diagram.
Stop flow.
1Process 2. [Prefund] House Account -> register the exchange between Mambu accounts is not triggeredThe error is registered in the Error Handling SD (FX & House) state diagram.
Cancel, and mirror the conversion in Currencycloud.
Stop flow.
2Withdrawal transaction - debit client deposit account in MambuThe error is registered in the Error Handling SD (FX & House) state diagram.
Cancel, and mirror the conversion in Currencycloud.
Stop flow.
2Patch custom fields for Withdrawal transactionThe error is registered in the Error Handling SD (FX & House) state diagram.
Stop flow.
2Deposit transaction - credit target accountThe error is registered in the Error Handling SD (FX & House) state diagram.
The withdrawal transaction is adjusted.
Cancel, and mirror the conversion in Currencycloud.
Stop flow.
2Patch custom fields for Deposit transactionThe error is registered in the Error Handling SD (FX & House) state diagram.
Stop flow.
2Update custom field at Withdrawal transaction with conversionIDThe error is registered in the Error Handling SD (FX & House) state diagram.
Stop flow.
2Calculate fee amountThe error is registered in the Error Handling SD (FX & House) state diagram.
Stop flow.
2Post fee transaction in MambuThe error is registered in the Error Handling SD (FX & House) state diagram.
Stop flow.
2Patch fee custom field for Withdrawal transactionThe error is registered in the Error Handling SD (FX & House) state diagram.
Stop flow.
2Patch fee custom field for Deposit transactionThe error is registered in the Error Handling SD (FX & House) state diagram.
Stop flow.
1,2The adjust transaction failsThe error is registered in the Error Handling SD (FX & House) state diagram.
Stop flow.
1,2If postTransactionAfterSettlement isfalse and conversionStatusis closedTrigger the processes in the [House Transfer] Refund flows folder.
If transactions exist:
Initiate adjustment of Withdrawal transaction in Mambu by posting a Deposit.
Initiate adjustment of the deposit transaction in Mambu by posting withdrawal.
Initiate fee adjustment in Mambu if a fee was charged.
Stop flow.

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.