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 flow
The first part of the house transfer flow involves the client getting a quote for the exchange rate:
- The client provides all the required data via digital channel to get the exchange rate for the house transfer.
- 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 tosell
. - Or between the Credit Deposit Account currency and the bought currency, when the
fixed_side
value is set tobuy
.
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 tofalse
, the payment is processed outside of the settlement window, without waiting for the status of a conversion from Currencycloud. The2.[Prefund] House Account -> register the exchange between Mambu accounts
process is triggered instantly. - When
postTransactionAfterSettlement
is set totrue
, the transaction should be posted only during the settlement cycle. The2.[Prefund] House Account -> register the exchange between Mambu accounts
process is triggered only when the conversion status istrade_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 status | Action |
---|---|
trade_settled | Continue with step two of house transfer flow. |
closed | Stop 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
- Debit client source account with the
sell_currency
amount. - Credit client target account with the
buy_currency
amount. - If the
fees
object is only zeroes or is empty, no fee is charged. For any other configuration, thefeeAmount
is calculated using the formula:feeAmount = fixed_amt + (variable_percent * transferred_amount / 100)
and then charged. - 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. - Fees are charged under the fee specified in the
config
, corresponding to the transaction currency. If no fee is specified in the Mambuconfig
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
}
Parameter | Type | Description | Required |
---|---|---|---|
debitAccountId | string | The Mambu debit account ID for the sell currency. | YES |
sell_currency | string | The currency being sold as a three-letter code. | YES |
creditAccountId | string | The Mambu credit account for the buy currency. | YES |
buy_currency | string | The currency purchased as a three-letter code. | YES |
fixed_side | string | The operation type, which may be buy or sell . | YES |
conversion_date | string(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 |
fees | Object | Specifies the types of fees being charged. | NO |
fees.variable_percent | number | A fee charged as a percentage of the amount being converted. | NO |
fees.fixed_amt | number | A fixed, flat fee that will be charged for the conversion. | NO |
exchangeAmount | number | Amount 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.
Step | Point of failure | Action |
---|---|---|
1 | Validate deposit account currency | The error is registered in the Error Handling SD (FX & House) state diagram.Stop flow. |
1 | Get Mambu client details | The error is registered in the Error Handling SD (FX & House) state diagram.Stop flow. |
1 | Create conversion in Currencycloud | The error is registered in the Error Handling SD (FX & House) state diagram.Stop flow. |
1 | Store the conversion information in MPO conversion state diagram | The error is registered in the Error Handling SD (FX & House) state diagram.Stop flow. |
1 | Process 2. [Prefund] House Account -> register the exchange between Mambu accounts is not triggered | The error is registered in the Error Handling SD (FX & House) state diagram.Cancel, and mirror the conversion in Currencycloud. Stop flow. |
2 | Withdrawal transaction - debit client deposit account in Mambu | The error is registered in the Error Handling SD (FX & House) state diagram.Cancel, and mirror the conversion in Currencycloud. Stop flow. |
2 | Patch custom fields for Withdrawal transaction | The error is registered in the Error Handling SD (FX & House) state diagram.Stop flow. |
2 | Deposit transaction - credit target account | The 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. |
2 | Patch custom fields for Deposit transaction | The error is registered in the Error Handling SD (FX & House) state diagram.Stop flow. |
2 | Update custom field at Withdrawal transaction with conversionID | The error is registered in the Error Handling SD (FX & House) state diagram.Stop flow. |
2 | Calculate fee amount | The error is registered in the Error Handling SD (FX & House) state diagram.Stop flow. |
2 | Post fee transaction in Mambu | The error is registered in the Error Handling SD (FX & House) state diagram.Stop flow. |
2 | Patch fee custom field for Withdrawal transaction | The error is registered in the Error Handling SD (FX & House) state diagram.Stop flow. |
2 | Patch fee custom field for Deposit transaction | The error is registered in the Error Handling SD (FX & House) state diagram.Stop flow. |
1,2 | The adjust transaction fails | The error is registered in the Error Handling SD (FX & House) state diagram.Stop flow. |
1,2 | If postTransactionAfterSettlement isfalse and conversionStatus is closed | Trigger 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.