Money Movements Service

Proposal of a design for a new service in charge of processing a request and is able to generate the according money movements in BOS and returns a success / error message plus the movement information if needed.

The request origin must be a Kafka topic the service is able to digest and proceed accordingly.

Reference Documents

The reference document table contains links to relevant information for the RFC:

Reference Document Location
BPCCS01 Cards service
BPAQT01 Aggregated Quantum reporting
BPAEB01 Ebury 2.0
BPACIP01 Asynchronous Command Interface Pattern

Problem Description

As part of the MEGA Product Strategy, we would want to provide our clients capability to issue a card and make payments online. In the scope of the MVP we will be issuing reloadable multi-currency debit cards. This way, clients will have the ability to issue cards, block / unblock, close the card, top up and defund the card and finally make payments.

We are implementing Cards Service whose responsibility is to integrate with card providers and internal systems.

From the BOS ledger perspective, we need to record the financial movements according to the following actions:

Card top up

The goal of this is to fund the card on the provider side. This means that in BOS side, we need to perform the movements to re-allocate the balance from the client's balance to a new type of balance.

This translates into something like the following: Top-up

Card defund

The aim of this action is to withdraw an available amount from the card balance. In BOS, this would mean we need to perform the movements to return some (or all) balance on the card's balance to the client's balance.

This would be represented in the BOS balances close to this: Defund

We do not need to record all individual transactions a client can make by using their card to make purchases within the BOS ledger, only the cash movement involved in the card top-up and defund.

Background

Currently, there is no way to initiate a money movement between BOS ledgers, and, for some future projects to be complete on BOS side, that would be required.

As per the different financial movements mentioned before, we would need to generate credit / debit movements in BOS whenever any service requires so. This way we will have a generic service to initiate a money movement between BOS ledgers.

As part of this development we will also take care of some complementary work around it in order to make a clear differentiation of the movements in BOS for the new Cards Service.

We will also have to keep the reporting (Quantum) up-to-date and will have to make sure the Treasury Team gets the proper information around these new movements.

Solution

Create a new microservice that is able to consume Kafka topics with the goal to determine the direction of the movement required (detracting/adding balance) and generate it for a given source and destination, currency, and amount.

Approach

We need this new service to process a Kafka message to extract the currency, amount, the type (e.g. write off, fees, etc.), and the origin and destination of those movements and use this information to interact with BOS.

Ideally we would be reading from Kafka the following information:

  • Currency: not nullable
  • Amount: not nullable
  • Type: nullable. Mainly thought of this based on the current implementation of the 'MoneyWorkflowFacade' in which for the "same" movement (payment -> client, for example) there are different ways of making it depending if it's for a returned payment, intra payment, etc.
  • Origin type: not nullable. E.g., card, client, payment, margin call, etc.
  • Origin ID: not nullable. E.g., card number, client id, payment id, margin call id, etc.
  • Destination type: not nullable. E.g., card, client, payment, margin call, etc.
  • Destination ID: not nullable. E.g., card number, client id, payment id, margin call id, etc.

The message published to Kafka as a response would contain the following (this might change and extended in the future to suit possible future integrations):

  • Status
  • Errors
  • Information of the movements generated (if any): Id, amount, currency, etc.

Both, the message to process and the response, will have to fulfill the Asynchronous Command Interface Pattern, so they will contain any extra information required by the pattern.

In the BOS side, if it's the first movement for the pair client and currency, we will be creating a new type of balance (CurrencyAccountType) to which we will allocate the current movement and future ones.

We might also need to include a new asset type (Asset.asset_type) to be linked to the credit / debit pair in order to flag it to be specifically for the service movements.

Once we have the correct type of balance for the client and currency, we can proceed creating the movement accordingly to the information received in the Kafka message. In order to prevent duplicate movements and keep the data consistency's management BOS, we are going to generate the movements using an implementation that inherits those mechanisms from 'MoneyWorkflowFacade', that is the current solution from BOS to do so. In the early stages, we are most likely going to be using the 'move' functionality, as we are only going to be re-allocating balances.

The two possible scenarios the service will have to handle for each Kafka message consumed are the following:

Detract balance from the client

This service must be able to generate the movements to decrease the client's balance (type = 'Clients') and re-allocate them into a new type of balance (type = TBD).

Example of the flow: Detract balance from the client

Add balance to the client

For this, it must generate the movements to increase the client's balance with the partial or total amount of the new type of balance (type = TBD) back into the client's balance (type = 'Clients').

Example of the flow: Add balance to the client

For further clarification on the interaction with Kafka and its different "layers", we have included the following diagram:

ACIP_interaction

The service must be able to allocate any of those movements taking into account the entry reason mechanism in order to show those properly in the client statements.

The communication process with BOS can be performed through async calls using Kafka. This way, we can use BOS current data consistency solution and the way to generate and assign the reasons mentioned before. In order to do this, we might need to extend the 'EntryReasonFactory' and create a layer below 'MoneyWorkflowFacade' for each service using this new service.

Quantum

As the result of this is some cashflow movements, we need to keep Treasury up-to-date, and for that, we need to consider how Quantum is going to receive this new information.

As per the current BOS behavior to report to Quantum, these new movements would be picked up normally, however, we will have to include a couple of new instruments in order to properly send the information to the Treasury Team for those specific movements.

Service Ownership

New Service Service Name Service Owner
Yes Cards service COP Team
Yes Money Movements Service TRE Team

Alternatives

We might have exposed several endpoints in BOS to receive the different kind of requests from EBO or any other service as we currently do for some other BOS-EBO functionalities.

However, we don't think this would fall under Ebury 2.0, so we have decided to include this new service following said pattern.

Operation

This new service will only consume topics published from internal services and will interact with the BOS database.

Security Impact

The proposed solution will require access to BOS in order to generate the money movements needed. As it requires access to sensitive data, it requires the same access restrictions used on the BOS side.

Performance Impact

The performance impact on BOS should be negligible as the solution will only perform a credit / debit operation. At first, only the Cards Service will be using this, and it will only be required when a client requires a card operation and the client's balance is enough to cover this movement. This new service will be impacted in terms of performance if BOS is having a low performance.

Developer Impact

New services that interact with BOS ledger might have to adapt to go through this new service in order to keep the consistency and stop adding more logic to BOS monolith.

Data Contracts

Not applicable.

Deployment

As there will be no service using this at the very first stage, we can be deploying this incrementally in order to properly test it for every feature / improvement.

Monitoring

This service can integrate with Prometheus and provide metrics on a regular basis. Based on that information, we can create different dashboards and visualizations in order to set alerts over that. Along with the alerts, we will define a 'Monitoring Plan' to notify and proceed accordingly to every scenario described.

We can also send errors and alerts to a Slack channel to have immediate notice of those.

Dependencies

None.