Local Payments

This connector handles two types of local payments:

An Interbank Local payment is a transfer of funds in the same currency, processed via Currencycloud’s connections to the most important national and international payments schemes, such as SEPA for Euro, ACH for US Dollars, or FPS for Pound Sterling.

Check Currencycloud’s documentation for supported currencies.

Local payments also refers to regular payments made using the local bank network. Regular payments are normally received by the beneficiary within five working days of the settlement date.

Interbank local payments

Interbank sequence diagram

Local transfer

Interbank local payments flow breakdown

Payment flow initiation - the client provides all the required data via digital channel.

Withdrawal and AML extension (optional)

The MPO process 1.1. [Entry Point] LOCAL Payment (Withdrawal + AML) starts with gathering details about the deposit account and client in Mambu, and beneficiary in Currencycloud using the ID.

Once the Mambu deposit account is identified and validated and only if the deposit account currency matches the transaction currency, the withdrawal is initiated in Mambu. Based on the value of the Currencycloud config property subAccountEnabledInCC, the beneficiary details are retrieved with or without the on_behalf_of parameter, as follows:

  • When subAccountEnabledInCC = true beneficiary details will be retrieved with the on_behalf_of parameter that stores the value of Currencycloud contact ID, only if a valid linkage exists between the Mambu client and Currencycloud contact ID. In case no linkage is found on the client level, for example the contact ID custom field does not exists or is empty, an error is thrown and a notification is sent.
  • When subAccountEnabledInCC = false beneficiary details will be retrieved without the on_behalf_of parameter and there is no linkage between Currencycloud contact ID and Mambu client.

Once the details for the withdrawal transaction are validated, the Mambu client deposit account is debited with the payment amount using a withdrawal transaction with accounting in multicurrency. The next step depends on the amlExtensionUsed parameter:

  • If amlExtensionUsed is set to false, the transaction will be monitored by using an external AML system, the process ends and the second part of the Local payment flow should be triggered on demand by the client.
  • If amlExtensionUsed is set to true and enableTransactionMonitoring is set to true the transaction will be monitored using the Generic Fincrime extension.
  • If amlExtensionUsed is set to true and enableTransactionMonitoring is set to false no monitoring will be performed on the transaction, and the local payment continues with the second part of the flow.

This first part can be triggered by a Sync API call corresponding to the MPO process: CurrencyCloud_Vx.y.z > [PREFUND] LOCAL Payment > Local - INTERbank payment > 1.1. [Entry Point] LOCAL Payment (Withdrawal + AML).

Create payment and transfer

After the withdrawal transaction was posted in Mambu and the transaction was Accepted by the AML system, if used, the MPO process 1.2. LOCAL Payment (CCy Payment + Transfer) is triggered automatically.

Based on the value of the Currencycloud config property subAccountEnabledInCC, the payment is created in Currencycloud as follows with the currency amount:

  • When subAccountEnabledInCC = true in the payment creation, the on_behalf_of parameter will be used, therefore the payer details parameters should not be sent. These will be populated using the details from the sub-account.
  • When subAccountEnabledInCC = false in the payment creation, the on_behalf_of parameter will not be used, therefore the payer details should be sent, which are mapped from Mambu client or group details.

The following payer details should be sent for a Client entity:

{
        "payer_entity_type": "individual",
        "payer_first_name": "Mambu Client First Name", // -> required
        "payer_last_name": "Mambu Client Last Name", // -> required
        "payer_date_of_birth": "Mambu Client Birth Date",
        "payer_country": "Mambu Client Country",
        "payer_city": "Mambu Client City",
        "payer_address": "Mambu Client Address (line 1)"
}

The following payer details should be sent for a Group entity:

{
        "payer_entity_type": "company",
        "payer_company_name": "Mambu Group name", // -> required
        "payer_country": "Mambu Group Country",
        "payer_city": "Mambu Group City",
        "payer_address": "Mambu Group Address (line 1)",
        "payer_identification_type": "incorporation_number", // -> required for `payment_type`: **priority**,
        "payer_identification_value": "Mambu Group ID" // -> required for `payment_type`: **priority**
}

Once the payment is created in Currencycloud and the manual journal entries are posted in Mambu, the details are stored in the 1. [COMMON] Payments SD state diagram with an intermediate status of ready_to_send. Based on the transaction currency the accounting will be posted on a dedicated transaction channel for that currency (accounting in multicurrencies). Both Transit GL and CC Settlement GL prefixes should be defined in your Mambu config. For example, if the transit GL account reference is 1234, then the transit GL account for payments in Euros will be 1234_EUR.

After the withdrawal transaction custom fields are updated with paymentId and paymentShortRefId values from Currencycloud, a transfer is created in Currencycloud based on the value of the Currencycloud config property subAccountEnabledInCC. The purpose of the transfer transaction is to move funds from House Account to Sub-Account:

  • When subAccountEnabledInCC = true, a transfer will be created having the Currencycloud contact ID as a destination_account_id, Currencycloud House Account ID as source_account_id, and the sell_currency amount.
  • When subAccountEnabledInCC = false the Transfer will be skipped in the Interbank Local payments flow.

Payment status updates

Whenever the status of a payment is changed in Currencycloud, a payment webhook is triggered. The webhook triggers an MPO process, 3. [COMMON] Currency Cloud WEBHOOK receiver for PAYMENTS [Linked to CCy webhook], responsible for updating the payment status of the associated Mambu withdrawal transaction using the appropriate custom field created as part of the initial connector setup.

Payment statusAction
ready_to_sendUpdate payment status in Mambu (on the withdrawal transaction).
completedUpdate payment status in Mambu (on the withdrawal transaction).
failedUpdate payment status in Mambu (on the withdrawal transaction).
Refund process is triggered.

Please Note
A payment that has been marked as completed by Currencycloud can be later rejected by the beneficiary bank. This triggers a failed payment webhook which starts the refund flow in MPO.

Reasons for failure:

  • Rejection by the beneficiary bank.
  • Currencycloud compliance check.

Interbank local payment payload details

Data required for executing the MPO process for Local Interbank Payment:

Structure

KeyTypeDescription
amountnumberAmount of the fixed buy or sell currency.
beneficiaryIdstringThe ID of the beneficiary.
currencystringCurrency used for the transaction. Three-digit code (ISO code).
depositAccountIdstringMambu debit account.
payment_typestringCan be either priority or regular.
referencestringA reference for the payment.
reasonstringClient-generated reason for payment. Free form text.
term_agreementbooleanIndicates agreement to terms and conditions.
purpose_codestring(Optional) Purpose code used for the payment. Required only for certain counterparty bank countries. Read more in the CurrencyCloud Help Center.
charge_typestring(Optional) Charge type used for the payment. Used only for SWIFT payments. Can be either ours or shared. For more information on each charge type, see Selecting payment charges for SWIFT payments in the Currencycloud Help Center.
JSON format for local payment
{
    "amount": <amount>,
    "beneficiaryId": <beneficiary ID>,
    "currency": <currency>,
    "depositAccountId": <deposit account id>,
    "payment_type": <priority / regular>,
    "reason": <payment reason>,
    "reference": <reference>,
    "term_agreement": <term agreement>,
    "purpose_code": <purpose code>,
    "charge_type": <charge type>
}
Example of local payment JSON body
{
    "amount": 11,
    "beneficiaryId": "cabfa20f-6b27-4ff0-a78c-46787920dadc",
    "currency": "EUR",
    "depositAccountId": "XIWF285",
    "payment_type": "priority",
    "reason": "Money to repay my mortgage",
    "reference": "Mortgage",
    "term_agreement": true,
    "purpose_code": "CHC",
    "charge_type": "ours"
}

Webhooks used

  • The Interbank Local payments flow only uses the payments webhook as no conversion is involved in the payment.
  • The payments webhook receiver process is used to update the Mambu withdrawal transaction with the status of the payment changes in Currencycloud.

More information on this webhook can be found in the Payments Webhook receiver section of the connector architecture page.

Failed interbank local payments

Failures are recorded in a state diagram in MPO. Based on the nature of the failure there are different remediation steps to take. In each case, if notifications have been enabled, a notification will be sent to the nominated user. In cases where the notification includes a request for manual intervention, it has been included in the Actions column of the table below.

StepPoint of failureActions
1Get Mambu deposit account detailsThe error is registered in the Error Handling for 1.1. LOCAL Payment state diagram and a notification is sent.
Stop flow.
1Validate deposit account currency and transaction currencyThe error is registered in the Error Handling for 1.1. LOCAL Payment state diagram and a notification is sent.
Stop flow.
1Get Mambu client or group account detailsThe error is registered in the Error Handling for 1.1. LOCAL Payment state diagram and a notification is sent.
Stop flow.
1Get Currencycloud beneficiary detailsThe error is registered in the Error Handling for 1.1. LOCAL Payment state diagram and a notification is sent.
Stop flow.
1Create withdrawal transaction - debit client Deposit Account in MambuThe error is registered in the Error Handling for 1.1. LOCAL Payment state diagram and a notification is sent.
Stop flow.
1Update counterparty details at the Mambu Withdrawal transaction levelThe error is registered in the Error Handling for 1.1. LOCAL Payment state diagram and a notification is sent.
Stop flow.
1Send the transaction to the AML Adaptor (if transaction monitoring is enabled)The process Error Handling for Failed Local Outbound Payments will trigger the refund flow and will adjust the withdrawal transaction in Mambu. The error is registered in Error Handling SD (LOCAL payments) state diagram and a notification is sent.
Stop flow.
1Continue payment flow: 1.2. LOCAL Payment (CCy payment)The process Error Handling for Failed Local Outbound Payments will trigger the refund flow and will adjust the withdrawal transaction in Mambu. The error is registered in Error Handling SD (LOCAL payments) state diagram and a notification is sent.
Stop flow.
2Create payment transaction in CurrencycloudThe process Error Handling for Failed Local Outbound Payments will adjust the withdrawal transaction in Mambu. The error is registered in Error Handling SD (LOCAL payments) state diagram and a notification is sent.
Stop flow.
2Create manual journal entries in MambuThe error is registered in the Error Handling SD (LOCAL payments) state diagram and a notification is sent.
The process continues.
2Copy Currencycloud payment details to payments state diagramThe error is registered in the Error Handling SD (LOCAL payments) state diagram and a notification is sent.
The process continues.
2Update Mambu custom fields at Withdrawal transaction with Currencycloud payment detailsThe error is registered in the Error Handling SD (LOCAL payments) state diagram and a notification is sent.
The process continues.
2Create transfer in CurrencycloudThe error is registered in the Error Handling SD (LOCAL payments) state diagram and a notification is sent.
The process continues.
2Copy Currencycloud transfer details to payments state diagramThe error is registered in the Error Handling SD (LOCAL payments) state diagram and a notification is sent.
The process continues.
2MPO receives a failed payment status from a Currencycloud webhookThe Mambu transaction is updated with the failed paymentStatus.
[common] Refund flow router process is called that: posts a Deposit transaction as a refund of the withdrawal, adjusts the manual journal entries and reverses or cancels the transfer in Currencycloud .
Stop flow.
2The refund process failsThe error is registered in the Error Handling SD (LOCAL payments) state diagram.
A notification is sent for the failed refund process, requesting manual intervention.
Stop flow.

Intrabank Local Payments

The Intrabank Local Payments flow implemented as part of the connector is not routed through the Currencycloud system. Instead, a Mambu transfer is made to move the money from one client to another.

The entry point for these payments is the 1. [COMMON] Payment router (FX, LOCAL (INTER & INTRAbank) & House transfer), found in the [COMMON] processes folder.

This part can be triggered by a Sync API call corresponding to the MPO process: CurrencyCloud_Vx.y.z > [PREFUND] LOCAL Payment > Local - INTRAbank payment > [Entry Point] INTRAbank transfer.

Intrabank sequence diagram

Intrabank Local Transfer

Intrabank Local Payments payload details

Data required for executing the MPO process for Local Intrabank Payment:

Structure

KeyTypeExplanation
amountnumberAmount of the payment.
debitAccountIdstringMambu debit account ID.
creditAccountIdstringMambu credit account ID.
reasonstringClient-generated reason for payment. Freeform text.

Example Intrabank Local Payments JSON body

{
    "amount": 46290.50,
    "debitAccountId": "ABC123",
    "creditAccountId": "DEF456",
    "reason": "handing over some cash"
}

Failed intrabank local payments

Failures are recorded in a state diagram in MPO. If the notification parameter paymentFailedNotification is enabled, a notification will be sent to the nominated user. If the notification includes a request for manual intervention, consult the Actions column in the table below for more information.

Point of failureActions
Create Transfer transaction in MambuThe error is registered in the Error Handling SD (LOCAL payments) state diagram and a notification is sent.
Stop flow.

AML monitoring integration - only for interbank local payments flow

The Currencycloud connector can be integrated with external anti-money laundering monitoring systems such as our Generic FinCrime connector. The outbound transaction is routed through the AML monitoring system to be analyzed and for a decision to be made on whether it should go through.

If using the Generic FinCrime connector, this should be installed and configured separately following its own documentation. Please make sure that under the transaction mapping object, the paymentSource outgoinglocalInterbankCCY object contains the corresponding mapping parameters.

TM option

Where AML fits in the flow

The 1.1. LOCAL Payment (Withdrawal + AML) process is configurable through the option enableTransactionMonitoring. The value of this parameter can be either true or false. It is stored in the Mambu configuration and is used to send the transaction through the AML system.

Interbank Local payment flow when enableTransactionMonitoring is true

  1. Retrieval of the deposit and client accounts from Mambu.
  2. Retrieval of the beneficiary from Currencycloud.
  3. Withdrawal transaction in Mambu.
  4. Generic FinCrime Connector is called (through the “AML Adaptor” process):
    • If the transaction is Accepted, the payment flow continues.
    • If the transaction is Rejected, it is stored in the Suspended State Diagram (Local Outbound) and the AML status custom field value for withdrawal transaction is updated with the value Rejected, followed by stopping the payment flow.
    • If the transaction is Suspended, it is stored in the Suspended State Diagram (Local Outbound) and the AML status custom field value for withdrawal transaction is updated with the value Suspended, followed by stopping the payment flow until further response.
    • If the transaction returned with Error status, the transaction withdrawal is adjusted and the AML status custom field value for withdrawal transaction is updated with the value Error, followed calling the Reverse Listener if needed.
    • If the transaction returned with Unknown status, the transaction withdrawal is adjusted and the AML status custom field value for withdrawal transaction is updated with the value Unknown.
  5. Create Payment in Currencycloud.
  6. Post manual journal entries in Mambu.
  7. Update withdrawal custom fields transaction in Mambu with Currencycloud Payment details.
  8. Create Transfer in Currencycloud (if applicable).
  9. Update withdrawal custom fields transaction in Mambu with Currencycloud Transfer details (if applicable)

Linkage between local payment and Generic FinCrime

In the AML Adaptor process, the FinCrime integration [ENTRY POINT/ To be linked to payment connector] process is called. In case of an error, the Reverse Listener is called, if needed.

AML listener

The AML Listener process is called from the Generic FinCrime connector. Whenever a transaction with the AML status suspended is analyzed in the Generic FinCrime Connector by interpreting the alerts webhook received from ComplyAdvantage and a final status is identified, the AML Listener process is triggered. This process receives the following parameters as input: AMLid, AMLstatus and the paymentSource. Its main purpose is to route the transaction to the Payment Connector’s next steps based on the AML status received.

  • For Accepted status, the process continues with the second process, 1.2. LOCAL Payment (CCy Payment + Transfer), that creates the payment in Currencycloud.
  • For Rejected or Unknown status, the process patches the AML status to the withdrawal transaction in Mambu and the transaction is withheld.
  • For Error status, the process patches the AML status to the withdrawal transaction in Mambu, and the withdrawal transaction is adjusted.

Generic FinCrime redeployment

In case the Currencycloud connector is reuploaded or redeployed, the process linked to the CCy_AML Listener(Local Outbound) alias in the Generic FinCrime connector corresponding to the outgoinglocalInterbankCCY paymentSource must be updated.

The ccy-fincrime-entry-point and ccy-fincrime-reverse-listener linked aliases in the Currencycloud connector must also be updated with their new process IDs by following these steps:

  1. Go to your MPO environment and select Aliases from the top right menu.
  2. Search for CCy_FinCrime_Entry_Point and CCy_FinCrime_Reverse_Listener. Search these aliases
  3. Right click the specific row and select Edit. Click on Edit button
  4. Change the Select process field. Change the process ID

Notes

  1. The data required for Local payment can be provided via your bank’s UI, API calls or by any other means, as long as MPO receives the correct transfer details.
  2. The last step of a payment - moving the money from the Currencycloud Collector account to the final beneficiary - is handled exclusively by Currencycloud.
  3. If the payment is done after cut-off, then it is not performed on the same day. For more information about cut-off, check the documentation available for Currencycloud Payment timelines.
  4. For more information about local payments in Currencycloud, check the documentation available in the Currencycloud Developer Center.