Smart Date Service Integration Phase B

This RFC describes the solution for implementing Phase B of Smart Date Service Integration into the multi payment workflow.

Background

Integration of the Smart Date Service into Mass Payments multi payment workflow has been divided into several phases, as noted in the RFC Smart Payment Execution Date Integration MVP:

  1. Phase A, which includes adjustments in BOS and EBO to calculate execution date for given parameters based on the rules as defined in Smart Payment Execution Date - Mass Payments Requirements RFC

    During this phase, information about delivery date will be displayed on the EBO screens only during multi payment creation.

  2. Phase B, which includes adjustment of BOS and EBO, as well as implementation of new Payment Query Service to display expected delivery date on all relevant payment screens and reports in EBO.

This RFC describes a solution for Phase B.

Problem Description

When uploading payments via multi payment file in EBO, if the user defines the date in a multi payment file as expected delivery date, the user will expect to see defined delivery date on relevant payment screens and reports once the payments are created.

We have identified following locations in EBO where expected delivery date needs to be displayed:

  1. Dashboard page

  2. Multi payments page

  3. Individual multi payment page

  4. Payments page

  5. Exporting valid and invalid payments to csv

  6. Payment Instructions PDF file

  7. Payment Receipt PDF file

All locations in EBO, noted above, retrieve payment data from BOS, with following specifics:

  • Data to feed multi payment page, payments page and for generating csv files are retrieved from BOS in json format

  • Payment Instruction and Receipt PDF files are generated in BOS and sent to EBO in pdf format

The scope of Phase B is to provide payment raw data via APIs and should not include pdf file generation.

Data that is currently being retrieved from BOS to provide information about payments include following data sets:

  • Data about payment, which is changing over the time throughout the payment life cycle (e.g. payment status, payment fully paid etc.)

  • Data about beneficiary, which is changing over the time throughout payment life cycle (e.g. authorized)

  • Data about beneficiary bank account, which will probably not change throughout payment life cycle

Those data sets are constructed by:

  • Retrieving data from around 30 tables as noted in this document

  • Performing different complex calculations to derive the current state of payment. Calculations can be found under Mapping section of the document

Given the complexity of the work needed for extracting data from tables BOS and calculations from the BOS codebase, as well as the timeframe and deadlines to deliver this phase, we suggest a hybrid approach that would:

  • Minimise adjustments in BOS

  • Give the opportunity to progress with the solutions that follows Ebury 2.0 vision

Solution

We propose to implement a solution that:

  • Extracts a minimum set of data from BOS into Payment Query Service (PQS), which is needed to display expected delivery date in all locations in EBO noted above

  • Requires minimum adjustments in BOS to include expected delivery date in PDF file generation

  • Uses EBO to collect and combine all payment information from BOS and PQS

Diagram of the proposed solution is given below.

Smart Date Service Integration Phase B

Payment Query Service Architecture

Proposed architecture for Payment Query Service is given below.

  1. All information about payments, including expected delivery date, are stored in BOS.

    We need to capture two sets of information:

    • Information about created payments that have an expected delivery date set (payment id and expected delivery date)

    • Information about valid and invalid payments to create corresponding csv files (multi payment id and raw data)

    Information about expected delivery date is not stored in the “main” BeneficiaryPayment model, but in a separate one: PaymentDelivery. Whenever payment is created via a new multi payment workflow that includes expected delivery date, a new entry will be added to PaymentDelivery. BOS Outbound Gateway will capture new entries in PaymentDelivery model and publish payment delivery CDC (Change Data Capture) events via Kafka Connect.

    Information about valid and invalid payments, as entered in multi payment file, are stored in Multipayment model. Whenever a new multi payment file is uploaded and multi payment entry added to the table, BOS Outbound Gateway will capture new entries and publish multi payment CDC (Change Data Capture) events via Kafka Connect.

  2. CDC events will be consumed by the Payment Query Service Data Aggregation component, that will process them and store data in local database

  3. Additionally, domain events related to the clients and their users, published by Beneficiary Command Service, will be consumed by Payment Query Service to store information about clients needed to verify ability to access requested data from API. When EBO requests payment data from BOS, it passes information about client id and client contact id. These ids are taken into consideration when retrieving multi payment information. By including this check, the system ensures that clients can retrieve only their payment information and not the ones belonging to other clients.

  4. Payment Query Service API component will expose endpoints for retrieving:

  5. Expected delivery dates for the created payments

  6. Valid and invalid payments for a given multi payment

Adjusting BOS

Adjustments in BOS are needed for following two endpoints that handle Payment Instruction and Payment Receipt generation in pdf file, to include expected delivery date, when applicable.

Adjusting existing endpoints requires including querying the PaymentDelivery model and including expected delivery date in the PDF file.

Adjusting EBO

Adjustments to EBO includes:

  • EBO backend changes

  • EBO frontend (UI) changes

EBO backend changes

Backend changes are needed to collect:

  • Information about expected delivery dates from PQS to include them in payment and multi payment screens

    Existing procedures that are currently retrieving payments data from BOS need to be adjusted to include retrieving expected delivery date from PQS for the payment ids retrieved from BOS and merging received dates with the rest of payments information.

  • Valid and invalid payments from PQS to display them on multi payment screen and for downloading csv file

    New procedures need to be implemented to enable communication with PQS and retrieving information about valid and invalid payments from. Existing procedures that currently call BOS for retrieving those information need to be adjusted to use PQS instead.

EBO frontend (UI) changes

UI changes include adjusting screens noted above to conditionally add expected delivery date within the relevant payments sections.

Caveats

Proposed solution includes adjustments in legacy services, BOS and EBO. While the proposed solution may be appropriate regarding expected timeframes, we will be adding more tech debt that should be addressed at a later stage.

Payment Query Service follows the design of Beneficiary Query Service, which was envisioned as proof of concept and reference for future services. It assumes (re)use of the knowledge, standards, libraries, etc. acquired and implemented during implementation of Beneficiary Query Service.

However, the Beneficiary Query Service hasn’t been deployed and tested on Staging or Production environment, at the time of writing this RFC. Any issues or discrepancies from desired solution identified during testing or exploitation phase may be reflected in Payment Query Service as well, depending on the nature of the issue (e.g. issue with library, underlying infrastructure, unacceptable latency).

It is most likely that Beneficiary Services will not be deployed on Production significantly earlier than Payment Query Service, which means that time to observe how Beneficiary Services are behaving before we rollout Payment Query Service will be minimal, if any.

Security Impact

The Kafka events are encrypted in-transit (TLS) and at rest (MSK). The read model database is also encrypted at rest.

Authentication and authorisation against Payment Query Service API is still subject to be discussed. Once an agreement is reached on how to protect internal APIs, the proposed solution will be implemented for all relevant services, including Payment Query Service.

Performance Impact

For capturing CDC events in BOS, Debezium and Kafka Connect are already in use. It is not expected that additional use of CDC stream will affect current performance.

Payment Query Service read models will be optimised for the multi payment delivery workflow use case. It is expected to provide better performance than BOS endpoints.

On the other hand, adjustment to BOS endpoints will include querying additional model. Solution should optimize additional data retrieval to minimize impact on performance.

The biggest performance impact is expected on EBO side due to the sequential process of retrieving payments first from BOS, extracting payment ids from the response, retrieving expected delivery dates from PQS and finally merging all data together.

Deployment

For deploying required infrastructure, we will use Kubernetes.

For deploying the code we will use Jenkins CI.

Dependencies

Payment Query Service is dependent on the Debezium, Kafka Connect CDC stream and libraries developed during implementation of Beneficiary Query Service. It also requires reliable infrastructure based on Kubernetes.