FPS & CHAPS

IBAN linkage

Outbound payment - Sequence diagram

ClearBank Retail Banking: IBAN linkage

The process is automatically triggered when a new Deposit Account is created in Mambu, and Deposit Account Created webhook is sent to MPO.

The purpose of IBAN linkage [link to Mambu webhook(s)] main process is to create a Virtual Account, then link the ClearBank IBAN to it and last map the IBAN to Mambu Deposit Account. At deposit account level are also mapped the following ClearBank account details into custom fields: virtualAccountID, sortCode, accountNumber and IBAN.

Notes:

  • IBAN value is mapped to Deposit Account custom field regardless the linkage method (EAR or Custom Field)
  • Only one Virtual account should be linked to a Deposit Account (1:1 relationship)
  • Only one IBAN can be mapped to a Deposit Account (1:1 relationship)
  • ClearBank webhooks triggered: VirtualAccountCreationFailed and VirtualAccountCreated.

Important:

  1. When property hasVirtualAccountExternalID is set to:
    • true in ClearBank config, an IBAN will be automatically generated by ClearBank based on the unique external identifier provided, that is automatically generated and matches ClearBank X-Request-ID. The IBAN generated will be used to create the Virtual Account that will be linked to Mambu Deposit Account.
    • false in ClearBank config, an IBAN must be previously generated and linked to Mambu Deposit Account.
  2. When hasVirtualAccountExternalID is set to true and also an IBAN is provided at Deposit Account Creation, then a Notification is sent due to conflicting IBAN generation.
  3. When property clearBankAccountSetup has the value singleRA the linkage must be skipped since no IBAN will be mapped at Deposit Account level, and Virtual Account feature is not used from ClearBank.

Inbound payment

This template allows initiating inbound transactions using an external account for existing Mambu clients that have Mambu deposit accounts, using UK payment schemes: Faster Payments (FPS) and The Clearing House Automated Payment System (CHAPS).

ClearBank webhooks that can be triggered for Inbound flow: TransactionSettled and InboundHeldTransaction.

Sequence diagram

ClearBank Retail Banking: Inbound Payment

Deposit Scheme Router [triggered by MPO webhook receiver] MPO process is automatically triggered when a payment is initiated from ClearBank Portal Simulator and TransactionSettled webhook is received in MPO.

The purpose of Deposit Scheme Router [triggered by MPO webhook receiver] main process is to decide if the payment made from ClearBank should be routed to payment scheme FPS or CHAPS.

Once the payment scheme is known, then the Inbound Payment process is triggered where the Deposit Account and Mambu customer are identified based on the value stored in ClearBank config for parameter clearBankAccountSetup as follows:

  • for VA value the IBAN provided in TransactionSettled webhook sent by ClearBank will be used for identification
  • for singleRA the payment reference provided in TransactionSettled webhook sent by ClearBank will be used for identification

Based on the payment scheme the following validations are made:

  • FasterPayments -> If confirmationOfPayee is set to true (in ClearBank config) then the following validation is made: only when Mambu Client Name equals to ClearBank Transaction Owner Name the payment is processed otherwise, if confirmationOfPayee is set to false this validation is skipped. After this validation, in case Mambu Client Name is different than ClearBank Owner Name, the Virtual Account owner is updated in ClearBank with Mambu Client Name. Mambu Deposit [Inbound Payment] MPO process is triggered once these validations are successfull. When Mambu Client Name is different than ClearBank Transaction Owner Name the payment is declined. This logic applies also for Inbound Interbank payments, Chaps International payments and Outbound Intrabank Transfer (only Credit).
  • Chaps -> The following validation is made: when Mambu Client Name equals to ClearBank Owner Name the payment is directly processed and Mambu Deposit [Inbound Payment] MPO process is triggered. In case they are different first the Virtual Account owner is updated in ClearBank with Mambu Client Name and after that the flow continues.
  • When clearBankAccountSetup has value singleRA the name validations are skipped (Mambu Client Name vs. ClearBank Transaction Owner Name) for all schemes. Config parameter transactionSingleAccount is required when clearBankAccountSetup is set to singleRA. If clearBankAccountSetup is set to singleRA and transactionSingleAccount is empty or missing, the Setup process will fail. transactionSingleAccount parameter specifies which ClearBank account IBAN will be used for all the transactions: OA - Operating Account or CMA - Client Money Account.

In Mambu, a Deposit transaction is posted under dedicated Transaction Channel based on the payment scheme: CB_Deposit_FPS or CB_Deposit_CHAPS, and transaction details are pushed into custom fields (transactionStatus is updated to Settled).

If the amount requested to be transferred is greater than £250k and the payment scheme used is FPS, the request will be rejected by the MPO router Deposit Scheme Router [triggered by MPO webhook receiver], since the maximum allowed amount for FPS was exceeded. In this case the payment is reversed in ClearBank (by posting a new Outbound payment).

Notes:

  • Deposit Scheme Router [triggered by MPO webhook receiver] MPO process will be triggered only when a TransactionSettled webhook is sent by ClearBank.
  • For the negative cases when the payment was released and TransactionSettled webhook is sent by ClearBank but due to other issues the Deposit transaction was not posted in Mambu a notification is sent based on the Notification Setup configuration. After the notification is analysed and payments details are know there can be 2 options:
    • the payment in ClearBank was reversed (by posting a new Outbound payment) if all the details were provided (identified by a specific empty error message: e.g. Inbound Reversal error: []). The reversed inbound payment can be identified in ClearBank by the payment reference Inbound Reversed.
    • When clearBankAccountSetup has value singleRA and the payment in ClearBank was reversed (by posting a new Outbound payment) if all the details were provided (identified by a specific empty error message: e.g. Inbound Reversal error: []). The reversed inbound payment can be identified in ClearBank by the payment reference [depositAccountID]-REV. If the Mambu Deposit Account will contain numbers then all the outbound CHAPS payment will be first held in ClearBank and the flow will continue once the payment is released by ClearBank.
    • in case the Inbound Reverse fails (identified by a specific error message) after the root cause is identified manual intervention might be needed.
  • If a Deposit transaction needs to be manually posted in Mambu after the payment is released and TransactionSettled webhook is received the following transaction channels CB_Deposit_FPS or CB_Deposit_CHAPS should be used since the payment already exists in ClearBank.
  • When key monitorInboundTransaction is set to true the transaction will be monitored and posted also in FinCrime module.
  • When config parameter clearBankAccountSetup has the value singleRA transactions cannot be monitored by using an AML extension. Transactions can be monitored only for option VA - Virtual Account feature used from ClearBank. Payment reference field must contain the Deposit Account ID from Mambu in order to be able to identify the account.
  • ClearBank Webhook(s) VirtualAccountCreated, VirtualAccountCreatedFailed and TransactionRejected don’t have a Reference field.

Inbound Held Payment

Following an Inbound Held payment one webhook can be received - TransactionSettled if the payment passed ClearBank sanction screening check.

  • InboundHeldTransaction:
    • False Positive -> payment released
    • True Positive -> payment remains under investigation

InboundHeldTransaction ClearBank webhook is triggered only when a payment is suspended and an analysis is required by ClearBank. The payment payload is stored in Inbound Payment Webhook MPO state diagram. An Info notification is sent based on the Notification Setup configuration with a specific message regarding the held payment in ClearBank.

If after the analysis the result is False Positive then the payment is released by ClearBank, a TransactionSettled webhook is sent, and Deposit Scheme Router [triggered by MPO webhook receiver] MPO process is triggered. InboundHeldTransaction and TransactionSettled webhooks are matched by the EndtoEndTransactionID in ClearBank.

In case the result is True Positive then the payment will be re-routed to the held suspense account until more instructions are received, and no TransactionRejected webhook is by ClearBank. An Inbound Held transaction is not available in ClearBank UI/API.

Inbound Reversal (FPS)

Following a FasterPayments reversal three TransactionSettled webhooks can be received (matched by the EndtoEndTransactionID in ClearBank). One for each of the following stages:

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

After an inbound payment is sent and TransactionSettled (First Credit -> isReturn:false) webhook is acknowledged and the Inbound flow was successfully executed - a Deposit transaction is created in Mambu, if the FasterPayments scheme does not respond in less than 30 sec the transaction will be automatically reversed by the scheme. This action is reflected by receiving in MPO the second TransactionSettled (Debit -> isReturn:true) webhook. This second wehbook is stored in MPO process Inbound Payment Webhook for 30 min.

If the reversal scheme process is:

  • successful then FPS scheme retry will be triggered which implies that the third TransactionSettled (Second Credit - isReturn:false) webhook is sent by ClearBank. This third webhook will be acknowledged and stored in Inbound Payment Webhook since no action is required..
  • unsuccessful then after 30 min since the third webhook was not sent, the reversal process will automatically be triggered, by adjusting the Deposit transaction in Mambu, since the Inbound payment in ClearBank is already reversed.

Notes:

  • Inbound Reversal applies only for FasterPayments scheme.
  • If the FPS scheme sends the third TransactionSettled (Second Credit - isReturn:false) webhook after 30 min, this webhook is stored in Inbound Payment Webhook MPO state diagram and then a notification is sent, since manual reconciliation is needed - manually posting a Deposit transaction in Mambu using the payment details from ClearBank and as transaction channel MBU_Deposit_FPS since the payment already exists in ClearBank.
  • The third TransactionSettled webhook (Second Credit - isReturn:false) it might be a Single Immediate Payment (suffix: 10) and in this case it will be sent almost immediately, or a Forward Dated Payment (suffix: 40) and in this case it can be sent in hours or days.

International Inbound Payment (CHAPS)

Inbound CHAPS payments which have originated overseas can be received. These payments will be received in GBP from the originating bank’s correspondent in the UK. In Inbound Payment Webhook MPO process is decided if the inbound payment is a domestic or international one.

International CHAPS payments cannot be automatically reversed, therefore a notification is sent and ClearBank needs to be contacted for more details, since the Customer Care team will need to return the funds manually on client behalf.

Notes:

  • When config parameter clearBankAccountSetup has the value singleRA the Creditor Reference must contain the Mambu Deposit Account, otherwise the payment will fail.
  • When Supplementary Data is enabled on ClearBank environment and config property isSupplementaryDataUsed is set on true in case debtor IBAN is not sent in TransactionSettled webhook (CounterpartAccount), the concatenated values of BIC and Account Number will be mapped into Mambu custom field debtorIBAN, instead of default text NOT PROVIDED. These values are read from TransactionSettled webhook Supplementary Data object (with/without AML extension). In case Account Number cannot be extracted from CHAPS supplementary data field because it was not sent, only BIC will be mapped into debtorIBAN field.

Outbound payment

This template allows initiating outbound transactions using an external account for existing Mambu clients that have Mambu deposit accounts, using 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 and TransactionRejected.

Sequence diagram

ClearBank Retail Banking: Outbound Payment

Withdrawal Scheme Router [link to Mambu webhook] process is automatically triggered when a Withdrawal transaction is initiated from Mambu using dedicated a Transaction Channel based on the payment scheme: MBU_Withdrawal_FPS or MBU_Withdrawal_CHAPS, and Withdrawal webhook is sent to MPO.

The purpose of Withdrawal Scheme Router [link to Mambu webhook] main process is to decide if the payment meets the following conditions based on the value stored in ClearBank config for parameter clearBankAccountSetup as follows:

  • for VA value an IBAN must be mapped to deposit account, payment scheme is FPS/CHAPS, deposit account currency is GBP. If the conditions are not met then the Withdrawal is Adjusted in Mambu and a notification is sent based on the Notification Setup configuration.
  • for singleRA the payment reference must contain the debtor deposit account ID from Mambu. Payment reference field is automatically populated with Mambu Deposit Account value sent from the Withdrawal webhook details if is sent empty.

Once the payment scheme is known and IBAN linkage is verified, then Withdrawal [Outbound Payment] process is triggered. Only when Deposit Account, Mambu client details and ClearBank Virtual Account are validated using the IBAN provided in the Withdrawal webhook details ClearBank [Outbound Payment] process is triggered. Based on the payment status ClearBank can send one of the following webhooks as response:

  • accepted in ClearBank TransactionSettled
  • rejected in ClearBank TransactionRejected
  • held in ClearBank OutboundHeldTransaction
  • payment details validation fails in ClearBank PaymentMessageAssesmentFailed or PaymentValidationAssesmentFailed

ClearBank Virtual Account validation using the IBAN provided in the Withdrawal webhook details is skipped when singleRA is used for all the transactions, since Virtual Account feature is not used.

The initial transactionStatus value after the Withdrawal webhook was sent is Pending. Once the payment is processed in ClearBank, based on the ClearBank webhook type the transactionStatus can transition to one of the following statuses:

  • TransactionSettled webhook = transactionStatus = Settled
  • TransactionRejected webhook = transactionStatus = Rejected
  • OutboundHeldTransaction webhook = transactionStatus = Held
  • PaymentMessageAssesmentFailed or PaymentValidationAssesmentFailed webhook = transactionStatus = Failed
  • payment is rejected at API level (didn’t reached ClearBank) = transactionStatus = API_Rejected

If the amount requested to be withdrawn is greater than £250k and the payment scheme used is FPS, the request will be rejected by the MPO router Withdrawal Scheme Router [link to Mambu webhook] since the maximum allowed amount for FPS was exceeded. In this case the Withdrawal transaction will be Adjusted in Mambu.

Notes:

  • Minimum fields that need to be send when Withdrawal transaction is initiated in order to have a successful Outbound payment: creditorIBAN & creditorName. paymentReference is optional in ClearBank. debtorIBAN and debtorName are optional since they will be automatically populated with Mambu client details once the Withdrawal webhooks is received in MPO.
  • If the Withdrawal transaction is not posted using the correct transaction channel the MPO process will not be triggered.
  • If the Adjusted Withdrawal fails a notification is sent based on the Notification Setup configuration. After the root cause of the failure is known and the payment is identified in ClearBank the Adjust needs to be manually performed in Mambu.
  • Chaps payments which use numbers into the Reference field will be automatically Held in ClearBank in order to be analysed and released by ClearBank once the analysis is finished (see Outbound Held Payment flow).
  • Accepted values for creditorIBAN field: UK IBAN default format (GB68HBUK40478470872490), country specific IBAN (GBR40478470872491) or sort code and account number (40478470872490).
  • When key monitorOutboundTransaction is set to true the transaction will be monitored and posted also in FinCrime module.
  • When singleRA is used all the outbound transactions are stored first in Webhook Retailers for Transaction Rejected Receiver SD state diagram in order to be able to identify the deposit account ID for Rejected transactions by ClearBank (Payment reference field is not sent in TransactionRejected webhook sent by ClearBank).

Outbound Held Payment

Following an Outbound Held payment two webhooks can be sent by ClearBank: TransactionSettled or TransactionRejected based on the ClearBank sanction screening check result.

  • OutboundHeldTransaction:
    • False Positive -> payment released
    • True Positive -> payment remains under investigation

Webhook OutboundHeldTransaction is triggered only when a payment is suspended in ClearBank and an analysis is required. The payment payload is stored in Outbound Payment Webhook MPO state diagram. transactionStatus custom field value is updated from Pending to Held for Mambu Withdrawal transaction, and an Info notification is sent based on the Notification Setup configuration with a specific message regarding the held payment in ClearBank.

If after the analysis the result is False Positive then the payment is released by ClearBank and a TransactionSettled webhook is sent, which is processed in Outbound Payment Webhook MPO process. transactionStatus custom field value is updated from Held to Settled for Mambu Withdrawal transaction.

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

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

Outbound Reversal (FPS)

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

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

After an outbound payment is sent and webhook TransactionSettled (First Debit -> isReturn:false) is acknowledged and the Outbound flow was successfully executed - transaction exists in ClearBank, if the FasterPayments scheme does not respond in less than 30 sec the transaction will be automatically reversed by the scheme. This action is reflected by receiving in MPO the second TransactionSettled (Credit -> isReturn:true) webhook. This second webhook is stored in MPO process Outbound Payment Webhook for 30 min.

If the reversal scheme process is:

  • successful then FPS scheme retry will be triggered which implies that a third TransactionSettled (Second Debit - isReturn:false) webhook is sent by ClearBank. This third webhook is acknowledged and stored in Outbound Payment Webhook since no action is required.
  • unsuccessful then after 30 min since the third webhook was not sent, the reversal process will automatically be triggered, by adjusting the Withdrawal transaction in Mambu, since the Outbound payment in ClearBank is already reversed.

Notes:

  • Outbound Reversal applies only for FasterPayments scheme.
  • If the FPS scheme sends the third TransactionSettled (Second Debit - isReturn:false) webhook after 30 min, this webhook is stored in Outbound Payment Webhook MPO state diagram and then a notification is sent, since manual reconciliation is needed - Withdrawal transaction needs to be manually posted in Mambu using the payment details from ClearBank and as transaction channel CB_Deposit_FPS since the payment already exists in ClearBank.
  • The third TransactionSettled (Second Debit - isReturn:false) webhook it might be a Single Immediate Payment (suffix: 10) and in this case it will be sent almost immediately, or a Forward Dated Payment (suffix: 40) and in this case it can be sent in hours or days.
  • The pooling mechanism from Outbound Payment Webhook is triggered as follows:
    • if a payment is stored in Held state for more than 24h.
    • if an FPS reversal was triggered and the thrid webhook (Retry) was not sent in 30 min.
    • if no webhook arrived in MPO after 30 min of waiting for an outbound payment after the initiation was made.
    • when option VA is used - transactions are searched for a specific Virtual Account and if ClearBank identifier matches the Mambu transaction encoded key then the transaction is considered as found, details are retrieved and the flow continues. Applies for use cases Held, FPS reversal, Settled and Rejected transactions - CHAPS & FPS schemes. If the transaction is not found in ClearBank then the flow will stop, reversal will be triggered and a notification is sent.
    • when option singleRA is used - transactions are searched by Operating Account/Client Money Account and if the identifier matched the Mambu transaction encoded key then the transaction is considered as found, details are retrieved and the flow continues. Use cases Held, FPS reversal, Settled and Rejected transactions. If the transaction is not found in ClearBank then the flow will stop, reversal will be triggered and a notification is sent.

Transfer payment

This template applies for Transfer payments inter-bank (different ClearBank sort codes but same institution) initiated as outbound and inbound transaction and intra-bank (same ClearBank sort codes) initiated as outbound transaction, using UK payment schemes: Faster Payments (FPS) and The Clearing House Automated Payment System (CHAPS).

Intrabank payment

Sequence diagram

ClearBank Retail Banking: Intrabank Transfer

When a Withdrawal transaction is initiated from Mambu using the Transaction Channel MBU_Transfer and the creditor IBAN has the same sort code, same bank branch (ClearBank) and belongs to another Mambu client that also has an IBAN linked to ClearBank, a Transfer is posted in ClearBank.

The purpose of Withdrawal Scheme Router [link to Mambu webhook] main process is to decide if the payment meets the following conditions based on the value stored in ClearBank config for parameter clearBankAccountSetup as follows:

  • for VA value an IBAN must be mapped to deposit account.
  • for singleRA the payment reference must contain the debtor deposit account ID the debtor deposit account ID and creditor deposit account ID (both from Mambu) separated by - (hyphen): {debtorDepositAccountId}-{creditorDepositAccountId}. Since there is no linkage with any ClearBank IBAN, all the transactions will be made using the same debtor IBAN based on the value stored in field transactionSingleAccount- OA (Operating Account) or CMA (Client Money Account).

After payment details are validated, ClearBank will sent two TransactionSettled webhooks which are matched by the EndtoEndTransactionID in ClearBank: one Debit and one Credit. TransactionSettled (Debit) will be stored in [Outbound Payment Webhook] and Withdrawal transactionStatus custom field value is updated from Pending to Settled.TransactionSettled (Credit) webhook, will be processed further for the Transfer flow by searching first that the creditor details are valid and ending in posting a Deposit transaction in Mambu using as Transaction Channel CB_Transfer(transactionStatus= Settled).

Both Mambu transactions Withdrawal and Deposit will have the same transactionStatus and transactionEndToEndId values. In case the beneficary account is Closed/Disabled, ClearBank will send one PaymentMessageValidationFailed webhook, the Withdrawal in Mambu will be Adjusted and the transactionStatus will be updated from Pending to Failed.

Notes:

  1. An Intrabank transfer can be held in ClearBank (see Outbound Held Payment flow).
  2. If an Intrabank transfer was held and released as rejected, then only one TransactionRejected webhook will be sent.
  3. If the Deposit transaction fails, then the Withdrawal transaction will be Adjusted in Mambu and in ClearBank the Adjust needs to be manually done for Transfer payment.
  4. When the monitorIntraBankTransferTransaction key is set to true the transaction will be monitored and also posted to the FinCrime module (this also applies to Interbank Transfer).

Outbound Interbank payment

When a Withdrawal transaction is initiated from Mambu using a as Transaction Channel: MBU_Transfer and the creditor IBAN has a different sort code but same bank branch (ClearBank), a Transfer is posted in ClearBank.

Based on the value of parameter clearBankAccountSetup from ClearBank config the following logic applies:

  • for VA value an IBAN must be mapped to deposit account.
  • for singleRA the payment reference must contain the debtor deposit account ID from Mambu. If the payment scheme is MBU_Transfer, the payment reference must also contain the creditor deposit account ID from Mambu.

After payment details are validated, ClearBank will sent one TransactionSettled webhook for Debit which will be stored in Outbound Payment Webhook MPO process, and the transactionStatus will be updated from Pending to Settled.

In case the beneficiary account is Closed/Disabled ClearBank will sent one TransactionRejected webhook and the Withdrawal in Mambu will be Adjusted.

Inbound Interbank payment

When an Inbound payment is initiated from a different ClearBank institution and the debtor IBAN has a different sort code but same bank branch (ClearBank), a Transfer is posted in ClearBank.

After payment details are validated, ClearBank will sent one TransactionSettled webhook for Credit which will be stored in Inbound Payment Webhook MPO process, and the transactionStatus will be updated from Pending to Settled. A Deposit transaction is posted in Mambu using as Transaction Channel: CB_Transfer.

In case the beneficiary account is Closed/Disabled ClearBank will sent one TransactionRejected webhook and the Deposit transaction in Mambu will not be posted.

When Supplementary Data is enabled on ClearBank environment and config property isSupplementaryDataUsed is set on true in case debtor IBAN is not sent in TransactionSettled webhook (CounterpartAccount), the concatenated values of BIC and Account Number will be mapped into Mambu custom field debtorIBAN, instead of default text NOT PROVIDED. These values are read from TransactionSettled webhook Supplementary Data object (with/without AML extension). In case Account Number cannot be extracted from CHAPS supplementary data field because it was not sent, only BIC will be mapped into debtorIBAN field.

Notes:

  1. Sequence diagram from Outbound flow is applicable for Interbank transfer.
  2. When the monitorOutboundTransaction key is set to true, the outbound interbank transaction will be monitored and posted to the FinCrime module.
  3. If the Adjusted Withdrawal fails a notification is sent based on the Notification Setup configuration. After the root cause of the failure is known and the payment is identified in ClearBank the Adjust needs to be manually done in Mambu.
  4. An Interbank transfer can be Held in ClearBank (see Outbound/Inbound Held Payment flow).
  5. Sequence diagram from Inbound flow is applicable for Interbank transfer.
  6. When the monitorInboundTransaction key is set to true, the inbound interbank transaction will be monitored and posted to the FinCrime module.