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

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.

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

KeyTypeDescription
debitAccountIdstringMambu debit account - sell_currency.
sell_currencystringCurrency sold. Three-digit code (ISO code).
creditAccountIdstringMambu credit account - buy_currency.
buy_currencystringCurrency purchased. Three-digit code (ISO code).
fixed_sidestringOperation type: buy or sell.
conversion_datestring(date)Date of delivery of purchase currency. ISO 8601 format YYYY-MM-DD. If not specified, deals settle in two working days.
feesObjectSpecifies the types of fees being charged. See fees.
exchangeAmountnumberAmount of the fixed buy or sell currency.

Fees object

KeyTypeDescription
variable_percentnumbera fee charged as a percentage of the amount being converted. Optional, can be 0
fixed_amtnumbera fixed, flat fee that will be charged for the conversion. Optional, can be 0.

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.

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
2Withdrawal transaction - debit client deposit account in MambuThe error is registered in the Error Handling SD (FX & House) state diagram.
Cancel
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
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,2postTransactionAfterSettlement = false & conversionStatus = 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.