Business Flows

Outbound payment

This connector allows initiating outbound transactions using an external deposit account for Mambu Clients and Groups (Pure and Solidarity) that have Mambu loan accounts, using the UK payment schemes: Faster Payments (FPS) and The Clearing House Automated Payment System (CHAPS).

ClearBank webhooks that can be triggered for Outbound flow:

  • TransactionSettled,
  • OutboundHeldTransaction,
  • PaymentMessageAssesmentFailed,
  • PaymentMessageValidationFailed,
  • TransactionRejected.

Mambu Disbursement

This busines flow applies to the following product configurations:

  • Loans with Multiple Disbursements
    • Revolving Credit
    • Tranched Loan
    • Interest Free Loan
  • Loans with a Single Disbursement
    • Dynamic Term Loan
    • Fixed Term Loan
  • Products available for
    • Clients
    • Groups
    • Solidarity Groups

Sequence diagram

ClearBank Lenders: Mambu Loan Disbursement

When a Disbursement transaction is initiated from Mambu using one of two transaction channels, MBU_Loan_Disbursement_FPS or MBU_Loan_Disbursement_CHAPS, a webhook is sent to MPO to trigger the process.

An approved loan account in Mambu is disbursed before the loan repayment cycle of the loan starts. Disbursement includes movement of the loan amount to the client account. For more information on loan lifecycle states in Mambu please visit our dedicated support page. The funds used to disburse the loan are held in the Operating Account defined in ClearBank. Upon Disbursement of the loan, the loan amount must move from the Bank’s Operating Account to the client’s external deposit account. In order to reconcile this payment, the encoded key of the Mambu transaction is mapped to the ClearBank payment field, transaction encoded key. This use case applies for new and existing ClearBank Virtual Accounts.

The main process of the connector, Disbursement Scheme Router [link to Mambu webhook], assesses whether the payment received from Mambu meets the following conditions:

  • loan account currency must be GBP,
  • the maximum payment value for FPS is £250k,
  • the transaction channel selected from the UI must match with the configured for the connector. If any of these conditions are not met then the Disbursement is Adjusted in Mambu and a notification is sent via Mambu Task/ZenDesk.

The Disbursement transaction must use a dedicated transaction channel based on the payment scheme, either MBU_Loan_Disbursement_FPS or MBU_Loan_Disbursement_CHAPS.

If the amount requested to be disbursed is greater than £250k and the payment scheme used is FPS, the payment will be Rejected by ClearBank. This is the maximum allowed amount for FPS. In this case the Disbursement transaction will be Adjusted in Mambu.

Notes:

  1. Only for Revolving Credit the amount that should be disbursed needs to be specified in an editable field, for all other loan accounts, the amount is predefined and the amount field will be non-editable.
  2. Data required for executing the main process initiated from Mambu to ClearBank:
{          
"debtorName": "Maria Velasquez",
"debtorIBAN":"GB72CLRB04062690545001", // -> ClearBank IBAN
"creditorIBAN":"GBR40478470872491 | GB68HBUK40478470872490", // -> external IBAN
"creditorName": "Mario Cruz",
"paymentReference": "loan disbursement"
}

ClearBank Disbursement

Sequence diagram

ClearBank Lenders: Loan Disbursement

The process is automatically triggered when a payment is initiated and approved from within the ClearBank UI and a TransactionSettled webhook is received sent to MPO.

An Approved loan account in Mambu is disbursed before the loan repayment cycle of the loan starts. Disbursement includes movement of the loan amount to the client account. The funds used to disburse the loan are held in the Operating Account defined in ClearBank. Upon Disbursement of the loan from the ClearBank UI, the loan amount must move from the Bank’s Operating Account to the client’s deposit account. A payment initiated from the ClearBank UI is referenced back to Mambu using the Loan ID in order to reconcile the payment. This use case applies for new and existing Virtual Accounts.

The main process UI_Disbursement Scheme Router [triggered by MPO webhook receiver] assesses whether the payment made from ClearBank meets the following conditions:

  • payment scheme is FPS or CHAPS
  • requested amount is within range,
  • the Disbursement transaction is made using dedicated Transaction Channel based on the payment scheme, either CB_Loan_Disbursement_FPS or CB_Loan_Disbursement_CHAPS. If any of the conditions are not met then a notification is sent via Mambu Task/ZenDesk.

In cases where the payment uses an internal IBAN, that is to say only ClearBank accounts are involved, then the payment scheme will be Transfer instead of Payment.

In the ClearBank UI, the Reference field must contain the prefix UI- followed by the Mambu Loan Account ID, e.g. UI-HDVC570. This enables us to differentiate transactions received and read from Clearbank TransactionSettled webhooks vs. from the UI.

Multiple payments can be sent from the ClearBank UI using Bulk Payment. This is equivalent to multiple disbursements in Mambu. When multiple payments are sent from the ClearBank UI, each payment transaction is logged separately in a different webhook (TransactionSettled) and the MPO process is triggered multiple times since each transaction is processed individually. Separate Disbursement transactions are also executed and logged in Mambu.

Note:

  • CHAPS payments which use numbers in the Reference field will be automatically put into a Held state in order to be analysed and released later if there are no issues with the payment (see Outbound Held Payment flow).

Important:

  • If the Mambu Disbursement transaction is not made using a dedicated transaction channel, the MPO process will not be triggered.
  • When property hasVirtualAccountExternalID is set to true in your ClearBank configuration, an IBAN will be generated by ClearBank. The Connector will create a unique external identifier and send a request to ClearBank to generate the IBAN by mapping the unique external identifier to X-Request-ID. The IBAN generated will be used to create the Virtual Account that will be linked to Mambu Loan Account.
  • When the property hasVirtualAccountExternalID is set to false in your ClearBank configuration, an IBAN must have been previously generated and linked to the Mambu Loan Account using a custom field.
  • When the property hasVirtualAccountForDisbursement is set to false in your ClearBank configuration, after an Outbound Payment is initiated from the ClearBank UI, the Disbursement transaction in Mambu is posted without verifying the association between Mambu Loan Account and ClearBank Virtual Account.
  • When the property hasVirtualAccountForDisbursement is set to true in your ClearBank configuration, when an Outbound Payment is initiated from the ClearBank UI, the association between Mambu Loan Account and ClearBank Virtual Account is verified and the Disbursement transaction in Mambu is posted only after this validation step has completed successfully.

Disbursement with Fees

The purpose of Loan Fee Analyzer by Product Type process is to decide whether a loan account with fees is eligible to be disbursed from the ClearBank UI. Disbursement with fees initiated from ClearBank UI applies for the following cases:

  • Loan amount that needs to be disbursed is predefined, which is the case for Dynamic Term Loans, Fixed Term Loans and Interest Free Loans.
    • Supported disbursement fees defined on the product level are Flat (with/without amount) and as a percentage of the loan amount.
    • Only fees which are active and marked as required will be applied to the disbursement transaction.
    • Any Optional fees are ignored regardless of whether the fee is flat or a percentage, with and without a pre-defined amount.

In case that a Payment Due fee is configured for the product and the disbursement transaction needs to be adjusted, this action can not be done using Mambu APIs; you must use the Mambu UI. For this case a task will be created in either Mambu or ZenDesk, based on the notification channel configured during setup of the connector. The notification will include information on the transaction which needs to be analyzed and, if needed, the disbursement transaction can be undone from the Mambu UI and manually reposted using CB_Loan_Disbursement_FPS or CB_Loan_Disbursement_CHAPS as the transaction channel.

Task created due to: CANNOT_BULK_ADJUST_ACTIVATION_TRANSACTION | for Loan Account: XUYB628. Requested amount from ClearBank 900 GBP is different than disburse amount in Mambu 897.0 GBP. Task was created from MPO for payment scheme: FPS. Process ID: 721474. Payment in ClearBank was done with End to End ID: 01D0159C3EY44C831101545 and transaction Identifier Field Ref: 01D5154C8ED64C43 1020200512826404787. Disbursement in Mambu was not Adjusted.

  • Loan amount that needs to be disbursed is custom, which is the case for Revolving Credit accounts.
    • Only Flat disbursement fees with predefined amounts supported on the product level supported.
    • Only Active fees which are marked as Required will be applied to the disbursement transaction
    • Any Optional fees are ignored regardless of whether the fee is flat or percentage and with or without a pre-defined amount.

If a Revolving Credit loan product has Active flat disbursement fees, without an amount or any other disbursement fee that is calculated based on a defined percentage of the loan amount, the disbursement transaction can not be made in Mambu since the loan and fee(s) amount is custom and would need to be provided. For this case a task will be created in the configured notification system. The task will contain the following message:

Task created due to: ClearBank Disbursement cannot be done with custom amounts or On The Fly fees (undefined amounts, loan amount percentage): REVOLVING_CREDIT. Disbursement should be done from Mambu UI using dedicated transaction channel for Loan Account: UFRH170. Task was created from MPO for payment scheme: FasterPayments. Process ID: 721471. Payment in ClearBank was done with End to End ID: 01D5154C3ED64C831101545 and transaction Identifier Field Ref: 01D5154C8ED64C43 1020200512826404787. Disbursement in Mambu was not done.

  • Loan amount that needs to be disbursed is predefined at tranche level, which is the case for Tranched Loans.
    • Defined disbursement fees on the product level supported are Flat (with amount) and loan amount percentage. -
    • Only Active fees marked as Required will be applied to the disbursement transaction.
    • Any Optional fees are ignored regardless of whether the fee is flat or percentage and with or without a predefined amount.

In case that a Tranched Loan loan product has Active flat disbursement fees without a pre-defined amount, the disbursement transaction will not be made in Mambu since an amount needs to be provided for the fees. For this case a task will be created in the notification system configured for the connector and the transaction should be in order to be analyzed. The task will contain the following message:

Task created due to: ClearBank Disbursement cannot be done with Undefined Disbursement Fee amount (product configuration): TRANCHED_LOAN. Disbursement should be done from Mambu UI using dedicated transaction channel for Loan Account: JVOG078. Task was created from MPO for payment scheme: FasterPayments. Process ID: 721471. Payment in ClearBank was done with End to End ID: 01D5154C8ED64C431101745 and transaction Identifier Field Ref: 01D5154C8ED64C43 1020200512826404787. Disbursement in Mambu was not done.

For negative flows, if notifications is set to true, then a task will be created in the configured notification system with a specific error message. The status and identifiers of the payment to be analyzed will be included in the task. Usually whenever a task is created, an analysis of the payment should be carried out, which can require manual intervention, for example re-posting the Disbursement in Mambu with the correct values.

Task created due to: Requested amount from ClearBank 60000 GBP is different than Mambu disbursed amount 50000 GBP. for Loan Account: JHSJ079. Task was created from MPO for payment scheme: FasterPayments. Process ID: 684129. Payment in ClearBank was done with End to End ID: 4a4de888022d4f5b84d8e1e864dc4b90 and transaction Identifier Field Ref: d0f646497e994cdeba1020200323826040626. Disbursement in Mambu was not done.

Important:

  1. When the Disbursement transaction needs to be manually posted in Mambu using the same payment data as in ClearBank, since the payment is already registered in ClearBank, one of the following transaction channels must be used depending on the payment scheme: CB_Loan_Disbursement_FPS or CB_Loan_Disbursement_CHAPS.
  2. For Tranched Loans, if fees are defined on the product level and the loan is eligible for disbursement, all Required fees will be applied only for the first tranche. Starting with the second tranche, all Required fees are seen as Optional. Only if a specific Optional fee needs to be applied for sequential tranches the disbursement transaction must be done from Mambu.
  3. For Revolving Credit accounts, if fees are defined on the product level and the loan is eligible for disbursement, all Required fees will be applied only for the first disbursement. Starting with the second disbursement all Required fees are seen as Optional. Only if a specific optional fee needs to be applied for sequential payments, the disbursement transaction must be done from Mambu.

Note: Data required for executing the main connector process for payments initiated from ClearBank to Mambu (Account Number and Sort Code are external)

{     
"Account Holder Name": "Mario Cruz",     
"Account Number":"70872491",
"Sort Code":"404784",
"Amount": 15000,
"Reference": "UI-[Mambu Loan Account ID]"
}

Outbound Held Payment

Following an Outbound Held payment two webhooks will be received. One for each of the following stages:

  • Initial notification:

    • OutboundHeldTransaction
  • Then, following investigation:

    • False Positive -> payment released - TransactionSettled
    • True Positive -> payment remains under investigation

The ClearBank webhook OutboundHeldTransaction, is only triggered when the payment should be monitored or investigated, for example during Sanction Screening. OutboundHeldTransaction webhooks are stored in the Payment Webhook state diagram. A notification is sent as either a Mambu Task or to ZenDesk with the following message:

Task created due to:Outbound payment transaction is Held in ClearBank for Loan Account: WEUB834. Task was created from MPO for payment scheme: CHAPS. Process ID: 684116. Payment in ClearBank was not made with End To End ID: 8a013bca70e46d540170edc0d7b00bc5. Disbursement in Mambu was Adjusted.

If your analysis reveals that the result is a False Positive, the payment is automatically released, and if the payment is successful a, TransactionSettled webhook is sent using the EndtoEndTransactionID field to match the payment in ClearBank. The payment is stored under Clearing Transactions from ClearBank UI until any manual analysis has been carried out.

If a held transaction is rejected in ClearBank, then a TransactionRejected webhook is sent, the Withdrawal transaction is adjusted and the value of the transactionStatus custom field is updated from Held to Rejected.

In case the result is True Positive then the payment will be re-routed to your defined suspense account until further instructions are received.

Important:

  • When the Disbursement is initiated from ClearBank after the payment has been released and the TransactionSettled webhook sent, the Disbursement transaction will be automaticallty posted to Mambu.
  • When the Disbursement is initiated from Mambu after the payment has been released and TransactionSettled webhook sent, the Disbursement transaction must be manually posted in Mambu using the same payment details as in ClearBank and either CB_Loan_Disbursement_FPS or CB_Loan_Disbursement_CHAPS as the transaction channel, since the payment is already registered in ClearBank.

Outbound Reversal (FPS)

Following a FasterPayments reversal three TransactionSettled webhooks will be received. One for each of the following stages:

  • First Debit -> isReturn:false
  • First Credit (reversal) -> isReturn:true
  • Second Debit (retry) -> isReturn:false

After an outbound payment TransactionSettled webhook is sent for debit transaction with isReturn:false is acknowledged, if the FasterPayments scheme does not respond within 30 seconds, the transaction will be automatically reversed/returned by ClearBank. During the Reversal process a new TransactionSettled webhook is sent by ClearBank for the credit containing isReturn:true and the disbursement transaction is adjusted in Mambu.

A notification is sent when TransactionSettled webhook with isReturn:true is received with the following content:

Task created due to: Payload needs to be investigated TransactionSettled webhook received, for transaction with End To End ID: d244d267be9d47e18a77ada47f963d5e and transaction Identifier Field Ref: 2a6de672601f4124af1020200319826040626. Payment was made in ClearBank and was not processed in Mambu. Task was created from MPO for payment scheme: FasterPayments. Process ID: 684152.

ClearBank will try to resend the transaction (retry) and a new TransactionSettled webhook for the debit transaction is sent with isReturn:false. All three webhooks/transactions from the Reversal process are matched in ClearBank using the EndtoEndTransactionID.

Important:

  • Outbound Reversal applies only for the FasterPayments scheme.
  • The third TransactionSettled (Second Debit - isReturn:false) webhook may be a Single Immediate Payment (suffix: 10), in which case it will be sent almost immediately, or a Forward Dated Payment (suffix: 40), in which case it can be sent, hours or, indeed, days later.
  • When the Disbursement is initiated from Clearbank after the second Debit transaction is sent then the Disbursement transaction will be automaticallty posted to Mambu.
  • When the Disbursement is initiated from Mambu after the second Debit transaction is sent then the Disbursement transaction must be manually posted in Mambu using the same payment details as in ClearBank and the transaction channel CB_Loan_Disbursement_FPS.

Inbound payment

This flow allows for initiating inbound transactions using an external deposit account for Mambu Clients and Pure or Solidarity Groups that have Mambu loan accounts, using UK payment schemes: Faster Payments (FPS) and The Clearing House Automated Payment System (CHAPS).

This business flow is compatible with the following product configurations:

  • Loans with multiple disbursements
    • Revolving Credit
    • Tranched Loan
  • Loans with single disbursements
    • Dynamic Term Loan
    • Fixed Term Loan
    • Interest Free Loan
  • Products available for
    • Clients
    • Groups
    • Groups (Solidarity)|

ClearBank webhooks that can be triggered for Inbound flow:

  • TransactionSettled,
  • InboundHeldTransaction.

Sequence diagram

ClearBank Lenders: Loan Repayment

The LoanPrePayment Scheme Router [triggered by MPO webhook receiver] MPO process is automatically triggered when a payment is initiated from the ClearBank Portal Simulator and a TransactionSettled webhook is received by MPO. The purpose of this process is to decide if the payment received from ClearBank needs to be routed via FPS or CHAPS. If any conditions are not met then a notification is sent.

Once the loan is successfully disbursed, the loan repayment cycle starts according to the schedule of the loan. The client may choose to repay the loan based on regular monthly payments or prepay any arbitrary amount. The incoming payment made via the FPS/CHAPS scheme is cleared and settled into the Bank’s Operating Account in ClearBank. This incoming payment contains a reference to the Mambu Loan Account ID in order to reconcile payments between ClearBank and Mambu. When a successful TransactionSettled webhook is received from ClearBank, a loan prepayment must be acknowledged and new loan schedule generated in Mambu.

The Repayment transaction must be made using a dedicated Transaction Channel based on the payment scheme; either CB_Loan_Repayment_FPS or CB_Loan_Repayment_CHAPS.

In the ClearBank Portal Simulator, the Payment Reference field can contain only the Loan Account ID from Mambu (e.g: HDVC570) or the prefix UI- followed by the Loan Account ID from Mambu (e.g: UI-HDVC570) in order to identify the loan account where the repayment will be posted in Mambu.

For negative flows, if notifications have been enabled during setup of the connector, a task will be created in either Mambuor ZenDesk with a specific error message and details of the transaction, including state and relevant identifiers. When a task is created, an analysis of that payment should be carried out, which may lead to manual intervention in Mambu or needing to contact ClearBank for follow-up information.

Notes:

  1. Data required for executing the Loan Repayment FPS process manually:
{
"Payment Reference": "[Mambu Loan Account ID]/ [UI-Mambu Loan Account ID]",
"Amount": 1000,
"Creditor Name": "Maria Velasquez",     
"Creditor Sort Code":"040626",
"Creditor Account Number":"90545001",
"Debtor Name": "Mario Cruz",
"Debtor Sort Code":"404784",    
"Debtor Account Number":"70872491"
}
  1. Data required for executing the Loan Repayment CHAPS process manually:
{
"Payment Reference": "[Mambu Loan Account ID] / / [UI-Mambu Loan Account ID]",
"Amount": 1000,
"Creditor IBAN": "GB72CLRB04062690545001",  
"Debtor IBAN":"GB68HBUK40478470872491",
"Creditor BIC 11":"CLRBGB22011",
"Debtor BIC 11":"HBUKGB4BXXX"
}

Important:

  • If the Repayment needs to be manually posted in Mambu after the payment is released and TransactionSettled webhook is sent, the CB_Loan_Repayment_FPS transaction should be used since the payment is already registered in ClearBank.
  • If the property hasVirtualAccountForPrePayment is set to false in your ClearBank configuration, after an Inbound Payment is initiated from Payment Simulator the Repayment transaction in Mambu is posted without verifying the association between Mambu and ClearBank using Virtual Account ID and IBAN.
  • If the property hasVirtualAccountForPrePayment is set to true in your ClearBank configuration, when an Inbound Payment is initiated from the Payment Simulator, the association between Mambu and ClearBank via Virtual Account ID and IBAN logic verified and the Repayment transaction in Mambu is posted only after this validation has been successfully completed.

Inbound Held Payment

Following an Inbound Held payment, two webhooks will be received. One for each of the following stages:

  • Initial stage flagging a held transaction:

    • InboundHeldTransaction
  • Follow up webhook after investigation:

    • False Positive -> payment released - TransactionSettled
    • True Positive -> payment remains under investigation

The ClearBank webhook InboundHeldTransaction is triggered only when the payment should be monitored or investigated, for example, in order to carry out Sanction Screening. The InboundHeldTransaction webhook is stored in Payment Webhook state diagram. A notification is sent as a Mambu/ZenDesk tast with the following message:

Task created due to:Inbound payment transaction is Held in ClearBank for Loan Account: WEUB834. Task was created from MPO for payment scheme: CHAPS. Process ID: 684116. Payment in ClearBank was not made with End To End ID: 8a013bca70e46d540170edc0d7b00bc5. Repayment in Mambu was Adjusted.

If analysis reveals the result to be a False Positive, then the payment is automatically released, a TransactionSettled webhook sent and the Repayment transaction is automatically posted in Mambu. Within ClearBank the transactions are matched using the EndtoEndTransactionID.

If the result turns out to be True Positive, the payment will be re-routed to the designated suspense account until more instructions are received and while no TransactionRejected webhook is received by ClearBank. An Inbould Held transaction is not available in ClearBank using the UI or API.

Important:

  • If the Repayment needs to be manually posted in Mambu after a TransactionSettled webhook is received indicating the payment has been released, either the CB_Loan_Repayment_FPS or CB_Loan_Repayment_CHAPS transaction channel should be used since the payment is already registered in ClearBank.
  • An inbound held transaction is not shown in ClearBank UI under Clearing Transactions.

Inbound Reversal (FPS)

Following a FasterPayments reversal, three TransactionSettled webhooks will be received. One for each of the following stages:

  • First Credit -> isReturn:false
  • First Debit (reversal) -> isReturn:true
  • Second Credit (retry) -> isReturn:false

After an inbound payment is sent and TransactionSettled (Credit - isReturn:false) webhook is acknowledged, if the FasterPayments scheme does not respond in less than 30 seconds, the transaction will be automatically reversed/returned by ClearBank. During the reversal process, a new TransactionSettled webhook is sent by ClearBank (Debit - isReturn:true) and the Repayment transaction in Mambu is Adjusted.

ClearBank will try to resend the transaction, at which point a new TransactionSettled webhook (Credit - isReturn:false) will be sent and Repayment transaction posted automatically to Mambu. All three webhooks/transactions from the Reversal process are matched in ClearBank using the EndtoEndTransactionID.

Important:

  • Inbound Reversal applies only for the FasterPayments (FPS) scheme.
  • If the Repayment needs to be manually posted in Mambu after the payment is released and TransactionSettled webhook is sent, the CB_Loan_Repayment_FPS transaction channel must be used since the payment is already registered in ClearBank.
  • The third TransactionSettled webhook (Second Credit - isReturn:false) might be a Single Immediate Payment (suffix: 10), in which case it will be sent almost immediately, or a Forward Dated Payment (suffix: 40), in which case it can be sent hours or days later.

Disable Virtual Account

This template allows disabling a virtual account from ClearBank when a Mambu loan account for a client or group is closed as either Repaid or Written Off.

Sequence diagram

ClearBank Disable Virtual Account

The Disable Virtual Account [link to Mambu webhook] MPO process is automatically triggered when the loan account is transitioned to Closed (Repaid) or Write Off state and the custom field virtualAccountId is not empty. Once a loan is transitioned to Closed (Repaid)/Write Off state, the virtual account from ClearBank should be Disabled and the virtualAccountId custom field value from Mambu should be updated by adding a[Disabled] prefix.

The following data is required for manually executing the main process for Disable Virtual Account.

{
    "loanAccountId": "Mambu loan account ID"
}

Notes:

  1. In cases where the loan account state is Closed - Refinanced or Rescheduled, a new loan account is created which has the same virtualAccountId and IBAN as the previous loan account. For states Closed (Withdrawn) or Rejected the disbursement is not done yet and the account is still Pending Approval.
  2. The process can also be manually triggered for any other closed loan account states.
  3. Disabling a Virtual Account is an irreversible action - the Virtual Account can not be re-activated. If the loan account is reopened for any reason, it should be mapped to a new IBAN.