Smart Payment Execution Date Integration MVP

This RFC describes the solution for integrating Smart Payment Execution Date service into the multi payment workflow.

Abbreviations, acronyms, and definitions

  • execution date: a date on which a payment is actually sent towards its beneficiary via an intermediary bank
  • delivery date: a date on which a payment actually arrives to the beneficiary's account
  • SDS. Smart Payment Execution Date Service, or Smart Date Service: a service which is able to calculate either an execution date or a delivery date, based on the other (i.e. execution from delivery, and delivery from execution)
  • MP, multi payment, or mass payment: a trade which can contain more than one payment for multiple beneficiaries. For example, a payroll multi payment is when a company sends the salaries of employees in one transaction.

Problem Description

Some mass payment (a.k.a. multi payment) clients are using multi payments for payrolls. Due to the legislation reasons, these payments must be delivered to the beneficiary at a given date (e.g. the last day of the month). The current multi payment workflow expects the execution date in the multi payment file and not delivery date. We are proposing solution that will enable calculation of execution date based on the delivery date provided in the multi payment file through the integration with existing Smart Date service.

Background

Typically Mass Payments customers use our service to transfer the salary of several employees in one trade. The current workflow consists of following steps:

  1. Client uploads a multi payment file to EBO.

  2. Operations team is waiting until the client send the funds and wait for the n-eyes verification (from client side).

  3. Mass payments team adjust manually (or contacting support) the value dates, so they can anticipate both the trade and payments dates to pass the AML checks and all the needed verifications.

  4. Once all preconditions to release the payments are met, they readjust the value dates to today's, so they appear in the pre execution page, otherwise they cannot generate the SIF file.

  5. They generate the SIF file with all the payments for a certain date and currency.

  6. They again adjust the generated file to have the execution date, so the payments will be delivered on the multi payment file specified value date.

  7. They upload the file to the payments platform.

The above procedure is time and resource consuming, therefore we need an automated way of executing steps above.

A new service Smart Date Service has been developed for calculating the date when payment should be executed to meet the delivery date expectations. We want to integrate the service into existing multi payment process, and precede the manual part.

Solution

The solution we propose is to insert a new conditional step into the current workflow of multi payment file processing. Depending on the date present in the multi payment file (execution or delivery date), this new step may be executed. If the multi payment file contains delivery date, then new step will be executed. During this step, Smart Date service will be queried for the execution date of payment based on the provided delivery date. If the multi payment file contains execution date, then new step will be omitted.

The information weather the file contains execution or delivery date will be selected by the client in the multi payment user interface (EBO) when uploading the file. That information will be passed to BOS together with the file for further processing. If the information about type of date is not provided to BOS, execution date will be assumed. This will allow compatibility with API without introducing changes in API in this stage.

Information about payment delivery date and execution date needs to be stored, so it can later be retrieved and displayed. Instead of storing the information with the payment in BOS, we will store the information in the new service (Payment Query Service) read model. Payment Query Service read model will be built based on the payment events published on the Event Bus. So, once the multi payment is accepted and confirmed by the client, payment information containing execution and delivery date will be published to Event Bus, which will then be consumed by the Payment Query Service to update its read model.

The solution (high level architecture) is displayed in the image below.

Smart Date service integration Diagram

The current solution requires following work to be done:

  • Adjustments in BOS multi payment file processing

  • Adjustments in EBO multi payment related screens and endpoints

  • Publishing payment event via Kafka Connect to Event Bus

  • Implementation of new service, Payment Query Service, for consuming payment events and building read model

Solution will be implemented in three phases:

  1. Phase A, which includes adjustments in BOS and EBO. During this phase, information about delivery date will be displayed on EBO screen only during multi payment creation. Solution will be available only in both platforms (Ebury Core and FrontierPay) but exposed only to clients that are in a trial/beta testing programme.

  2. Phase B, which contains implementation of Payment Query Service and publishing payment event

  3. Phase C, which contains adjustments of EBO screens to display delivery date on all relevant multi payment screens.

Phases 2 and 3 will be available in Ebury Core platform.

Adjustments in BOS

There are couple of adjustments that needs to be done in BOS:

  1. Introduce acceptance of the new parameter specifying if the multi payment file contains execution or delivery date. This parameter is optional (that way we avoid adjustments in API). If it is omitted, execution date is assumed.

  2. Adjusting process of multi payment file processing. After the multi payment file has been uploaded and parsed, if the file contains delivery date, BOS will need to iterate through the payments, query the Smart Date service for the execution date and replace the delivery dates from the file with calculated execution dates. This step happens before validation, so all the validations concerning execution date apply to the value received from Smart Date Service. The output of the process, sent back to EBO, should be payments containing both execution and delivery date. Information about delivery date should be stored within multi payment raw data, so it can later be used to publish payment event to the Event Bus.

Changes in EBO

When a multi payment is being created, on the Deal tab a new radio button will be added to determine whether the date specified in the file is an execution date or delivery date. After submitting file to BOS, if the file contains delivery date, EBO expects to receive back both execution and delivery date, so they can be displayed on the Payments tab for review before accepting and confirming multi payment.

Publishing payment event to Event Bus

Once the multi payment is confirmed, individual payment information containing delivery data from multi payment raw data will be extracted by the Kafka Connect and published to Event Bus.

Implementation details how to publish payment events are out of te scope of this RFC.

Payment Query Service implementation

Payment Query Service consists of three components:

  1. Data aggregation component, which consumes payment events from Event Bus and updates read model

  2. Read model that stores payment information

  3. API, which provides querying read model by other services

Implementation details of Payment Query Service are out of te scope of this RFC.

Caveats

  • The call to the Smart Date Service has an impact on the processing time of the multi payment file. The current goal is to handle 12K payments a day, the current peak is around 6K payments per day in around 100-120 multi payment files, but given that these are tied to payrolls, the load is distributed very unevenly. With the current size of the database behind Smart Date Service, and not taking network latency into account, it takes less than 10 milliseconds to calculate an execution date based on a desired delivery date. This by itself is not too dangerous, however, it is a noticeable amount, and if processing time or network latency increases, it can compromise the goal of 12K payments a day. Smart Date Service is monitored for response times, but network latency is not.

Operation

New workflow will be enabled in both platforms (Ebury Core and FrontierPay) on a client level in the first stage. So, there will be an option to define which clients participate in the trial/beta testing programme.

Security Impact

Payment data will be encrypted both in transit and at rest within Kafka events and read model database.

Payment Query service API will be accessed from internal services (and networks) and not exposed publicly. At first stage there will be no authentication and authorization mechanism in place, since that will part of the overall strategy and will be defined separately out of the scope of this RFC.

Performance Impact

This is the most critical part of the implementation. According to the calculations made, the creation of one payment should not take more than 120 milliseconds. The Smart Date Service takes less than 10 milliseconds to perform a calculation. This means that currently the execution date calculation is responsible for somewhere between 6% and 9% of the total payment creating time. However, this calculation is not taking network latency into account, because we don't have that measurements. Smart Date Service is not expected to have a significant amount of data to process, and it also uses Redis, so it is safe to assume that its performance will not deteriorate over time. Should we see decrease in the performances, we can deploy various adjustments in the process to overcome the issue.

Developer Impact

Smart Date Service is based on FastAPI, so it has an autogenerated client that gets automatically updated upon each release. This is used for querying the execution date, so the developer impact is minimal: this client library is a requirement of the project, gets installed upon container building, and at a single point it will be used to call Smart Date Service.

Data Consumer Impact

With the proposed solution, we do not change the format of the multi payment file to be processed. However, we are introducing new parameter that clients need to set to define whether the file contains execution or delivery date. As this change is introduced on the user interface, a proper communication to the clients to explain the adjustments to the workflow needs to be done before releasing the solution. The remaining steps are the same, so there is no further data consumption impact.

Deployment

For deploying required infrastructure, we will use Terraform. New services (Payment Query Service and Smart Date Service) will be deployed in terraform-natonly.

For deploying the code we will use Jenkins CI.