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:
- The client provides all the required data via digital channel to obtain 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 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
)
Based on the value of the Currencycloud boolean configuration property subAccountEnabledInCC
, the Mambu client details are retrieved or not. The behavior when this property is enabled or disabled is outlined below:
- When
subAccountEnabledInCC
is set to true, Mambu client details will be retrieved in order for thecontactId
parameter (received from the previous retrieval) to be used in the funds conversion. - When
subAccountEnabledInCC
is set to false, the retrieval of the Mambu client details will be skipped.
Once the currencies are checked and, if subAccountEnabledInCC
is set on true, the client contactId
is retrieved, 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. 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 The process2.[Prefund] House Account -> register the exchange between Mambu accounts
is triggered instantly. - When
postTransactionAfterSettlement
is set totrue
, the transaction should be posted only during the settlement cycle. The process2.[Prefund] House Account -> register the exchange between Mambu accounts
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 with deciding whether to continue with the house transfer flow or not.
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 the webhook receivers page.
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 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": { } }
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 Mambu configuration JSON you will configure during Setup
.
House Transfer payload details
Data required for executing the MPO process for House Account transfer flow:
Structure
Key | Type | Description |
---|---|---|
debitAccountId | string | Mambu debit account - sell_currency. |
sell_currency | string | Currency sold. Three-digit code (ISO code). |
creditAccountId | string | Mambu credit account - buy_currency. |
buy_currency | string | Currency purchased. Three-digit code (ISO code). |
fixed_side | string | Operation type: buy or sell . |
conversion_date | string(date) | Date of delivery of purchase currency. ISO 8601 format YYYY-MM-DD . If not specified, deals settle in two working days. |
fees | Object | Specifies the types of fees being charged. See fees. |
exchangeAmount | number | Amount of the fixed buy or sell currency. |
Fees object
Key | Type | Description |
---|---|---|
variable_percent | number | a fee charged as a percentage of the amount being converted. Optional, can be 0 |
fixed_amt | number | a 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 the connector architecture page.
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.
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 |
2 | Withdrawal transaction - debit client deposit account in Mambu | The error is registered in the Error Handling SD (FX & House) state diagram.Cancel |
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 |
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. |
1,2 | The adjust transaction fails | The error is registered in the Error Handling SD (FX & House) state diagram.Stop flow. |
1,2 | postTransactionAfterSettlement = false & conversionStatus = 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.