Local Payments
This connector handles two types of local payments:
- Interbank Local payments, which are implemented through the Currencycloud system.
- Intrabank Local payments, which are implemented through Mambu transfers.
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 refer 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 local payments flow
For starting the payment flow the client provides all the required data via digital channels or the banking UI.
Withdrawal and AML extension (optional)
The 1.1. [Entry Point] LOCAL Payment (Withdrawal + AML)
Mambu Process Orchestrator (MPO) process starts with gathering details about the deposit account and client in Mambu, and the 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, is the withdrawal is started in Mambu. Based on the value of the Currencycloud configuration property subAccountEnabledInCC
, the beneficiary details are retrieved with or without the on_behalf_of
parameter, as follows:
- When
subAccountEnabledInCC
istrue
: beneficiary details will be retrieved with theon_behalf_of
parameter that stores the value of Currencycloud contact ID, only if a valid link exists between the Mambu client and Currencycloud contact ID. In case no link is found on the client level - for example, if the contact ID custom field does not exist or is empty - an error is thrown and a notification is sent. - When
subAccountEnabledInCC
isfalse
: beneficiary details will be retrieved without theon_behalf_of
parameter and there is no link between the Currencycloud contact ID and the 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 multi-currency. The next step depends on the amlExtensionUsed
and checkThreshold
parameter:
- If
amlExtensionUsed
is set tofalse
: 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 totrue
andenableTransactionMonitoring
is set totrue
: the transaction will be monitored using the Generic FinCrime extension. If thecheckThreshold
parameter is set totrue
, then the transaction calculation threshold is compared with the value stored in Mambu configuration for thethreshold
parameter. If the threshold calculated value is:less
than orequal
to the home base currency threshold amount then the transaction will not be sent to be monitored.greater
than the home base currency threshold amount then transaction will be monitored.- When
checkThreshold
parameter is set totrue
and the value ofthreshold
parameter is an empty string ("") or0
(number), or/and the value ofmambuHomeCurrency
is an empty string ("") then all transactions will be monitored.
- If
amlExtensionUsed
is set totrue
andenableTransactionMonitoring
is set tofalse
: 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 is posted in Mambu and the transaction is Accepted
by the AML system, the MPO process 1.2. LOCAL Payment (CCy Payment + Transfer)
is triggered automatically if it is being used. Based on the value of the Currencycloud configuration property subAccountEnabledInCC
, the payment is created in Currencycloud as follows with the currency
amount:
- When
subAccountEnabledInCC
istrue
in the payment creation: theon_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
isfalse
in the payment creation: theon_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": "Travis",
"payer_last_name": "Earl",
"payer_date_of_birth": "1979-11-28",
"payer_country": "DE",
"payer_city": "Berlin",
"payer_address": "Karl-Liebknect Straße 5"
}
The following payer details should be sent for a group entity:
{
"payer_entity_type": "company",
"payer_company_name": "MyGroup",
"payer_country": "LT",
"payer_city": "Vilinius",
"payer_address": "Konstitucijos pr. 21b",
"payer_identification_type": "incorporation_number",
"payer_identification_value": "45RTFVHYN"
}
Parameter | Type | Description | Required |
---|---|---|---|
payer_entity_type | string | The entity type, which may be individual for client entries and company for group entities. | YES |
payer_first_name | string | The first name of the Mambu client. | YES |
payer_last_name | string | The last name of the Mambu client. | YES |
payer_date_of_birth | string | The date of birth of the Mambu client in the format YYYY-MM-DD . | YES |
payer_city | string | The city name of the client or group. | NO |
payer_address | The first line of the Mambu client or group’s address. | NO | |
payer_company_name | string | The name of the Mambu group. | YES |
payer_country | string | The country of the Mambu group or client. | NO |
payer_identification_type | string | This field is needed if the entity type is company and its value is incorporation_number . | YES, for payment_type: priority |
payer_identification_value | string | This field is needed if the entity type is company and its value is the client ID. | YES, 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. Both Transit GL
and CC Settlement GL
prefixes should be defined in your Mambu configuration. 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 subAccountEnabledInCC
Currencycloud configuration property. The purpose of the transfer transaction is to move funds from the house account to a sub-account:
- When
subAccountEnabledInCC
istrue
: A transfer will be created with the Currencycloud contact ID as adestination_account_id
, Currencycloud House Account ID as thesource_account_id
, and thesell_currency
amount. - When
subAccountEnabledInCC
isfalse
: 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 the 3. [COMMON] Currency Cloud WEBHOOK receiver for PAYMENTS [Linked to CCy webhook]
process, which updates the payment status of the associated Mambu withdrawal transaction.
Payment status | Action |
---|---|
ready_to_send | Update the payment status in Mambu on the withdrawal transaction. |
completed | Update the payment status in Mambu on the withdrawal transaction. |
failed | Update the payment status in Mambu on the withdrawal transaction. Refund process is triggered. |
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. For this flow the refunded amount (deposit transaction in Mambu) will have the value of the failure_returned_amount
field, not the initial amount of the withdrawal and the transaction will not be monitored. In case the value in failure_returned_amount
is empty or 0
the original withdrawal amount will be used for the refund. The linkage between the deposit transaction and withdrawal is done by two custom fields CCy Original Transaction Id
and CCy Original Transaction Amount
. On the same deposit transaction the reason for the rejection will be saved in a new custom field CCy Reason
.
Applying fees
The connector supports two types of fees which can be applied when a local payment is initiated:
- Arbitrary fees.
- Manual fees with no amount defined.
Manual fees are charged under the fee encodedKey
specified in the config
object productFee
, corresponding to the transaction currency. If no fee encodedKey
is mentioned for the transaction currency then the fee will be charged as an arbitrary fee.
If a manual fee is used then all the deposit accounts from where the local payments are initiated must be of the same deposit product under which the fee, with the encodedKey
specified in the config
, is defined. The same type of fee will be applied to all the transaction types in a specific currency.
The fee amount is calculated using the formula feeAmount = fixed_amt + (variable_percent * transferred_amount / 100)
. The fixed amount and the variable amount are specified as values for the corresponding properties fixed_amt
and variable_percent
, which are defined under the required fees
input object.
If the fees
object is empty, or properties fixed_amt
and variable_percent
have zeros as values then no fee is charged. Negative values are not valid values for properties fixed_amt
and variable_percent
. If a property has a negative value then a notification with specific details will be created and the fee will not be applied.
At the fee transaction level the withdrawal transaction id
is detailed in the notes
field. The fee amount is specified at withdrawal transaction level in a dedicated custom field. If a fee cannot be posted, due to an MPO error or insufficient funds, a notification is created and the error details are saved in a dedicated state diagram. The fee transaction then needs to be manually applied.
In case failed
status is received for a local payment transaction for which a fee was applied then the fee transaction is adjusted as part of the refund flow.
Interbank local payment payload
{
"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",
"fees": {
"fixed_amt": 10,
"variable_percent": 0.33
}
}
Key | Type | Description | Required |
---|---|---|---|
amount | number | Amount of the fixed buy or sell currency. | YES |
beneficiaryId | string | The ID of the beneficiary. | YES |
currency | string | Currency used for the transaction as a three-digit code ISO code. | YES |
depositAccountId | string | The Mambu debit account. | YES |
payment_type | string | This value can be either priority or regular . | YES |
reference | string | A reference for the payment. | YES |
reason | string | The client-generated reason for payment. This field is free-form text. | YES |
term_agreement | boolean | TRUE if the client agrees agrees to the terms and conditions, FALSE otherwise. | YES |
purpose_code | string | The purpose code used for the payment. Required only for certain counterparty bank countries. Read more in the CurrencyCloud Help Center. | NO |
charge_type | string | The 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. | NO |
fees | object | Specifies the fees details being charged. | YES |
fees.fixed_amt | number | A fixed, flat amount that will be charged as the fee for the local payment transaction. | NO |
fees.variable_percent | number | A variable amount in % of the local payment transaction amount, which will be applied as a fee. | NO |
Webhooks
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.
Step | Point of failure | Actions |
---|---|---|
1 | Get Mambu deposit account details | The error is registered in the Error Handling for 1.1. LOCAL Payment state diagram and a notification is sent.Stop flow. |
1 | Validate deposit account currency and transaction currency | The error is registered in the Error Handling for 1.1. LOCAL Payment state diagram and a notification is sent.Stop flow. |
1 | Get Mambu client or group account details | The error is registered in the Error Handling for 1.1. LOCAL Payment state diagram and a notification is sent.Stop flow. |
1 | Get Currencycloud beneficiary details | The error is registered in the Error Handling for 1.1. LOCAL Payment state diagram and a notification is sent.Stop flow. |
1 | Create withdrawal transaction - debit client Deposit Account in Mambu | The error is registered in the Error Handling for 1.1. LOCAL Payment state diagram and a notification is sent.Stop flow. |
1 | Update counterparty details at the Mambu Withdrawal transaction level | The error is registered in the Error Handling for 1.1. LOCAL Payment state diagram and a notification is sent.Stop flow. |
1 | Send 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. |
1 | Continue 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. |
2 | Create payment transaction in Currencycloud | The 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. |
2 | Create manual journal entries in Mambu | The error is registered in the Error Handling SD (LOCAL payments) state diagram and a notification is sent.The process continues. |
2 | Copy Currencycloud payment details to payments state diagram | The error is registered in the Error Handling SD (LOCAL payments) state diagram and a notification is sent.The process continues. |
2 | Update Mambu custom fields at Withdrawal transaction with Currencycloud payment details | The error is registered in the Error Handling SD (LOCAL payments) state diagram and a notification is sent.The process continues. |
2 | Create transfer in Currencycloud | The error is registered in the Error Handling SD (LOCAL payments) state diagram and a notification is sent.The process continues. |
2 | Apply fee transaction | The error is registered in the Error Handling SD (LOCAL payments) state diagram and a notification is sent.The process continues. |
2 | Copy Currencycloud transfer details to payments state diagram | The error is registered in the Error Handling SD (LOCAL payments) state diagram and a notification is sent.The process continues. |
2 | MPO receives a failed payment status from a Currencycloud webhook | The [common] Refund flow router process is triggered.The Mambu transaction is updated with the failed payment status.A deposit transaction is posted as a refund having as value the withdrawal transaction amount in case failure_returned_amount is empty or 0 otherwise the value of the failure_returned_amount .The logged manual entries are adjusted and the Currencycloud transfer is reversed or cancelled. |
2 | The refund process fails | The 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)
process, which is in the [COMMON] processes
folder. This part can be triggered by a Sync API call corresponding to the CurrencyCloud_Vx.y.z
> [PREFUND] LOCAL Payment
> Local - INTRAbank payment
> [Entry Point] INTRAbank transfer
process.
Intrabank Local Payments payload
Data required for executing the MPO process for Local Intrabank Payment
:
{
"amount": 46290.50,
"debitAccountId": "ABC123",
"creditAccountId": "DEF456",
"reason": "handing over some cash"
}
Key | Type | Description |
---|---|---|
amount | number | Amount of the payment. |
debitAccountId | string | The Mambu debit account ID. |
creditAccountId | string | The Mambu credit account ID. |
reason | string | The client-generated reason for payment. This field is free-form text. |
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.
Point of failure | Actions |
---|---|
Create Transfer transaction in Mambu | The error is registered in the Error Handling SD (LOCAL payments) state diagram and a notification is sent.Stop flow. |
Anti-Money Laundering monitoring integration for interbank local payments
The Currencycloud connector can be integrated with external anti-money laundering (AML) monitoring systems such as the 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.
The Generic FinCrime connector should be installed and configured separately following its own documentation. Make sure that under the transaction mapping
object, the payment source outgoinglocalInterbankCCY
object contains the corresponding mapping parameters.
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
- Retrieval of the deposit and client accounts from Mambu.
- Retrieval of the beneficiary from Currencycloud.
- Withdrawal transaction in Mambu.
- 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 theSuspended State Diagram (Local Outbound)
and the AML status custom field value for withdrawal transaction is updated with the valueRejected
, followed by stopping the payment flow. - If the transaction is
Suspended
, it is stored in theSuspended State Diagram (Local Outbound)
and the AML status custom field value for withdrawal transaction is updated with the valueSuspended
, 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 valueError
, 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 valueUnknown
.
- If the transaction is
- Create Payment in Currencycloud.
- Post manual journal entries in Mambu.
- Update withdrawal custom fields transaction in Mambu with Currencycloud Payment details.
- Create Transfer in Currencycloud (if applicable).
- Update withdrawal custom fields transaction in Mambu with Currencycloud Transfer details (if applicable)
Link between local payment and Generic FinCrime
In the AML Adapter 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.
Anti-Money Laundering 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 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
orUnknown
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
If 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:
- Go to your MPO environment and select Aliases from the top-right menu.
- Search for
CCy_FinCrime_Entry_Point
andCCy_FinCrime_Reverse_Listener
. - Right click the specific row and select Edit.
- Change the Select process field.
Additional details
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. The last step of a payment - moving the money from the Currencycloud Collector account to the beneficiary - is handled exclusively by Currencycloud.
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. For more information about local payments in Currencycloud, check the documentation available in the Currencycloud Developer Center.