Connector Architecture

The Currencycloud connector has two parts: the first is linking the Mambu client with the Currencycloud sub-account and the second is invoked when a new payment is started. A new payment is started using one of the following Mambu Process Orchestrator (MPO) flows: FX Transfers, House Transfers, Local Payments (intra & inter bank), or Incoming Payments using dedicated transaction channels.

Authentication

Communication between Mambu, MPO, and Currencycloud is done via webhooks. All Currencycloud API endpoints 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 only required once to get a temporary authentication token. The authentication token is then used as a proxy for the login credentials. The authentication token will be included with API calls in the X-Auth-Token header. Authentication tokens expire after 30 minutes of inactivity. When the authentication token has expired, a new one is automatically generated.

How it works

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

The House Account refers to a client’s Currencycloud Account or Master Account, which is a multi-currency eWallet available in all currencies supported by Currencycloud. Sub-account refers to accounts created within the House Account.

A contact needs to be created before any activity is undertaken on a 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 - such as conversion, payment, transactions, and searching - at the sub-account level.

From an architectural perspective, 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 made across local payment networks.
• Local Payment - intrabank: Payments to another account in your Mambu tenant made using standard Mambu transfer capabilities.

A different payload provides the input data for each transaction type. 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 and starting a refund flow.
• Errors state diagram: Stores any errors which have occurred in common processes for 30 days.