E2E shareable payment tracking - Phase 1 (UETR)

Prerequisites

N/A

Reference Documents

The reference document table contains links to information relevant to the RFC, a link to the referenced document is also required. Here is an example:

Reference Document Location
PRD Payment tracking Product requirement document
ISO Migration Epic ISO migration
SEPA outgoing SEPA outgoing RFC
SWIFT GPI tracker confirmation SWIFT GPI tracker confirmation

Problem Description

Our clients need to know the payment status to provide an update to the beneficiary. In most cases, suppliers do not release shipments until a proof of payment is provided. Our clients also want to know the reason for payment delays, rejections, and intermediary fees charged to share this information with the beneficiary.

Being able to track things is a part of people's daily routines nowadays. We can track a car ride from request to arrival for pick-up; or we can track a parcel from a supplier until it arrives, with a simple tracking ID.

To find out about the status of a payment, the customer has the possibility to contact Ebury. The Operations team must take manual steps using Swift GPI tracker (offered to Ebury back office team via the Santander API), or by contacting banks in case of non-swift payments, to retrieve the data and return the requested information.

After conducting 16 interviews with the FO and Ops teams and analysing the queries, the main conclusions are:

  • Top 3 countries requesting are Spain, UK, and UAE. They account for 46.52% of the request. UAE clients are mostly importers and they request a payment confirmation to get their shipments released. They also expect payments in local CCY to be instant.
  • 80% of the requests relate to SWIFT GPI. These correspond to the Benes contacting our client to know the payment status. They request the UETR (Unique End-To-End Transaction Reference) to provide it to their bank to locate the payment and get assurance that the funds are on the way, as they can contact their bank (bene’s bank) to get that assurance.
  • MT103s requests corresponde to 15%. Clients request them as more official proof payments to encourage the release of goods.
  • The material cases relate to the combination of USD/CNY to HK/CH.

Background

The UETR is part of the file headers in the MT103 files and we generate them using the UUID v4 random value.

Nowadays, UETR are generated in two different places:

  • All payments arriving at FXSuite (so all payments with automatic external execution) stored in the FXSuite database have a UUID v4 generated in the BeneficiaryPayment table gpi_uetr field. The legacy MT103 generator in FXSuite uses this value.
  • In the Transformer response. Each time Swift-Service calls Transformer, Transformer returns a UUID v4 generated in the MT103 header. Note, this is randomly generated for each request, the value generated in FXS is not passed so ignored.

Current implementation

These UETRs are not communicated to BOS. Even more, the values generated in Swift-Service and Transformer are not stored anywhere, but the S3 MT103 files backups.

An email communication with payment information is sent to clients from BOS when we update the payment routing selected. This email is named “Payment receipt”.

Solution

The ultimate goal is to build a transparent way for our client to track their payments without requiring Ops’s assistance.

Based on the client discovery, hypothesis are as follows: By providing the UETR to the clients, we will be able to reduce the queries for cross border payments as clients will provide that information to third parties providing an official record of the payments; By providing an expected delivery date for all payments, we will be able to attract more clients online and reduce uncertainty to clients and all payments (and subsequently queries to Ops). Note: SWIFT is only an option for Cross border, not local payments; By reflecting the GPI tracker on EBO, we will increase online use and reduce queries from Ops even further;

The first phase of this project will be sharing the UETR to clients. This document focuses on that:

  • Show UETR in Payment receipt.

Current implementation

  • Show the UETR in EBO payment details.

Current implementation

After that, the product will analyse the usage of the UETR by the clients (clicks on copy to clipboard button) and decide if to continue with next phases.

The solution proposal is: Generate a unique UUID at payment initiation and then pass it through all system.

Benefits of this solution:

  • We have the value from the beginning of the payment creation, so it can be used at any point in the payment lifecycle.
  • It can be used for other purposes than UETR.
  • UUID is starting to be very commonly used as a standard identifier for entities.
  • It is simpler to explain and understand.

To achieve the phase 1 of the project, we propose a tactical solution:

Tactical solution diagram

  • Add a new field in BOS payment model and fill it with a UUID v4 algorithm.
  • Pass the new field along all the events and messages.
  • Use this new field in MT103 generation as UETR.
  • Print this new field in the payment receipt in BOS.
  • Pass back to EBO the routing information + UUID.
  • Write some basic logic to show the UETR to clients in the EBO details view.

An Ebury 2.0 solution (not tactical) will look something like:

Tactical solution diagram

Note: Do not focus on details in this diagram, this is just for illustrative purposes not a proposal.

The idea in the future is to aggregate all the events relevant for this feature in a service (Query Service in the diagram) and have a payment service initiator, which will be publishing the creation event with the UUID information.

So, the tactical solution will actually be a first step on the refactors to a Ebury 2.0 architecture: We generate the UUID in payment creation and we pass it everywhere as part of the main payment information.

Reasoning for the tactical solution:

  • This solution brings value in tech terms as make new services to be able to use a UUID for their use case. Example: New MX fields in ISO migration can use this new field as UETR, FPS can use it as his unique identifier in Form3.
  • There are more initiatives at the same time (ISO migration and SEPA outgoing) that will be replacing current services. If we wait, we will avoid block dependencies between projects going on. Also, the other initiatives will deprecate service and build service willing Ebury 2.0, so we can take advantage of it.
  • Business Agility: We want to analyse the usage of the UETR and understand the user usage of it before continuing with the next phase.

Service Ownership

N/A

Alternatives

Option 1

Keep generating the UETR in FXSuite.

We generate the UETR in the FXSuite payment creation and then we pass it to MT generating services and use it. At the same time. FXSuite will publish the UETR once the payment is saved in the fxs db. All payments executed outside Ebury will have an UETR no matter the routing selected for them. So for example, FPS payments will have an UETR when in FPS direct this connection does not exist.

Tactical solution diagram

Pros

  • Is the simplest and quickest to implement. We only need to pass the UETR to swift service and publish the event from FXS.

Cons

  • Continues with the concept of generating UETR for all payments needing external execution.
  • Implies tactical solution as we will be extending FXSuite.
  • BOS won’t have this information. So we will need to subscribe BOS to it or create new services to query payment information.

Option 2

We generate the UETR in the FXSuite, but we change when generating the payment to the moment of sending. Then, we only generate it for the ones sent to the SWIFT network. In that step will publish the event with the UETR.

Tactical solution diagram

A variant of this same solution can be publishing the UETR in the moment of the MT file generation.

Tactical solution diagram

Pros

  • The UETR is generated only when needed.

Cons

  • Implies tactical solution as we will be extending FXSuite.
  • We need to deprecate current implementation.
  • BOS won’t have this information. So we will need to subscribe BOS to it or create new services to query payment information.
  • We will add complexity to the “sending” or MT generation processes.

Option 3

Deterministic UETR generation from PID with UUID v5.

This solution is using the current PID as the source of UUID v5 algorithm . Ex: uuid5(namespace='somethingDifferentPerEnvironment', seed=payment.PID).

Pros

  • We don’t need to stream the UETR all around, will be implicit within PID.
  • We won’t need to store a new field for a payment.

Cons

  • We may have collisions and the system won’t be able to do something about it (in creating random UUID generation we can have retries to avoid this) . Perhaps, practically impossible.
  • The UETR will be as limited as the PID in terms of getting out of space for generating news.
  • We still need to perform changes in the current implementations.

Caveats

  • Imply extending legacy services.
  • Imply changes all around BOS, FXSuite, Swift-service and Transformer which are meant to be deprecated with ISO migration.
  • Adding new fields in BOS models is problematic.
  • We will need to deprecate current implementation once moving to Ebury 2.0 solution.

Operation

Requests about providing the UETR will be reduced as clients will have the UETR available in EBO UI.

Security Impact

N/A

Performance Impact

Adding new fields in BeneficiaryPayment model in BOS creates memory issues when Django ORM retrieving objects. So, adding this new UUID field will imply adding 1 to 1 relationship for it.

Developer Impact

The new UUID can extend for usage more than UETR. Affected messages and events consumers will need to be backward compatible for consuming this new field.

Data Contracts

Kafka events

Event pre-execution-check-complete:

  • Backwards compatible: Adding a new field to the schema.
  • Current consumers:
  • FXSuite: The ambassador ebury-http-kafka-connector is converting the events data into HTTP requests to FXSuite.
  • Outgoing payment service: This service is WIP project. We may need coordination about this with PAY team in SEPA outgoing project).

SQS/SNS messages

The messages passed to Swift-service are actually message passing only consumed by swift-service. All changes are meant to be backwards compatible.

API

EBO and API are using same payment endpoint in BOS to retrieve data. If we decide to extend this response, we will need to change the current response including this new field in docs and client communications.

Data Sources

BOS will be upgraded adding a new field containing a unique UUID. In this phase 1 BOS will be the datasource for this new id. In further phase will be moved to a new defined service in charge of payment creation.

Deployment

N/A

Dependencies

N/A



Based on RFC Template Version 1.1