Connector Architecture

The Currencycloud connector is divided into two main phases. The first is linking the Mambu client with the Currencycloud sub-account. The second is invoked when a new payment is initiated using one of the following flows: FX Transfers, House Transfers, Local Payments (intra & inter bank), or Incoming Payments using dedicated transaction channels.

The communication between the systems - Mambu - MPO - Currencycloud is made via webhooks. All endpoints in the Currencycloud API require authentication to be provided as a header parameter. Rather than providing a username and API key with every request, the sign in process is required once to get a temporary authentication token. The authentication token will be used as a proxy for the login credentials. The authentication token will be included with API calls on the X-Auth-Token header. Authentication tokens expire after 30 minutes of inactivity. When the authentication token has expired, a new one will be generated automatically.

The Currencycloud integration handles collect, convert, and pay use cases for sub-accounts and also for house accounts or payment aggregators.

The House Account refers to a client’s Currencycloud Account or Master Account - a multi-currency eWallet available in all currencies supported by Currencycloud. The Sub-account refers to the capability of creating multi-currency eWallets for the client, which sit within the House Account.

The on behalf of refers to the capability to execute transactions on behalf of the client. A contact needs to be created before any activity is undertaken on the sub-account. See the Link Clients flow for more information on the conditions under which a new contact will be created automatically. Once a contact is created, the on_behalf_of parameter is used in the transactional events - conversion, payment, transactions, searching - at the sub-account level.

From an architectural point of view, the Currencycloud connector has two main areas: Payment router and State diagrams.

Payment router

The Payment router process is the single point of entry for all outgoing, pending, and completed payments. The router supports the following payment types:

• Pre-fund FX transfer: Cross-border payments using pre-funded foreign currency accounts.
• House Transfer: Transfers between accounts owned by the same client but in different currencies.
• Local Payment - interbank: Payments to accounts in another financial institution being made across local payment networks.
• Local Payment - intrabank: Payments to another account in your Mambu tenant made using standard Mambu transfer capabilities.

The architecture of the Currencycloud payment is displayed in the below diagram:

A different payload provides the input data for each transaction type. See the relevant article in the Business Flows section for more details.

Incoming payments are routed to a different process which acts like a webhook receiver and is linked to the Currencycloud Funding Transactions webhook.

State diagrams

State diagrams are used to hold payment and conversion states due to the asynchronous and distributed architecture of the connector.

The connector uses the following state diagrams:

• Conversions state diagram: Stores details of currency conversions until their status changes to trade_settled or closed. The pre-fund FX transfer and pre-fund house transfers flows rely on the Conversions state diagram.
• Payments state diagram: Stores all payments until their status changes to completed or failed.
• Completed payments state diagrams: Stores completed payments for a configurable number of days. Payments are held in this state diagram in case a rejection comes later from the beneficiary bank. In this case, an incoming webhook would trigger a completed payment to be marked as failed, initiating a refund flow.
• Errors state diagram: Stores any errors which have occurred in common processes for a configurable number of days.

The architecture of the Currencycloud payments state diagram is displayed in the below diagram: