Bexs Gateway

The target of this RFC is to provide an overview of the solution design to develop a backend solution that will be responsible for handling interaction with Ebury internal systems and Bexs' APIs.

Reference Documents

Reference Document Location
Product Document New Product Design Committee - EBO for Brazilian Clients
Technical Document MVP Phase A - Technical Plan Document

Problem Description

The vision for Ebury in Brazil is to offer Brazilian clients similar products and services that Ebury offers to any of the other onboarded clients around the world, while also complying with the local regulatory requirements.

Since the Brazilian FX Market is unique and very regulated, increasing the overall complexity for all participants, the recent Bexs acquisition will allow Ebury to leverage a local license and infrastructure to be able to comply with regulatory requirements and operate with almost no volume or trade type constraints.

In order to provide customers with a homogeneous experience, some integration work is required as described in the next sections.

Functional Requirements

After the implementation of the solution presented in this RFC, Brazilian Clients should be able to create BRL trades as follows:

  • Trades should be created on Bexs via its REST API.
  • Trades should contain one or more Payment relation - convert without payment is not permitted.
  • Trades should store their Bexs identifiers (references) on them.

For more details on the long-term solution requirements check the PDC document.

Background

For the long-term solution, Ebury Brazilian clients will have access to EBO where they can access different currency accounts, visualize their funds, request the conversion between different currencies, see the status of trades, upload trade documents online where needed, etc.

Considering the complexity and amount of work required to achieve the long-term solution, this RFC is the first one of a series, and it is only focused on the creation of a gateway solution intended to intermediate and manage the BRL trades created with Bexs.

The goal is to allow Brazilian customers to have access to Ebury Online (EBO) in order to self-serve in BRL trades. In order to achieve that, the plan is to leverage the existing Ebury Core Infrastructure as much as possible, using Bexs' APIs to tap into necessary Brazilian infrastructure.

Solution

The main design principle is to replicate the experience that Ebury offers in other countries to Brazilian clients, adapting only what is strictly necessary for complying with local requirements/regulations while integrating with Bexs.

This RFC is focused on the first deliverable as the new Gateway only for Bexs operations. It is focused on delivering a solution for trading operations as a component inside of Bexs Gateway (BGW).

This RFC does not describe:

  • Quoting & Price calculations (Rate & Spread)
  • Client Management (Onboarding)
  • Reason for Trades (Bexs Reason Codes)
  • Outbound Gateway for 3rd Party Webhooks

The topics mentioned above will have their own RFC's. The gateway will have its seperate component implementations based on capabilities & domains, which could be easily de-coupled if needed in future iterations.

General Approach

The Bexs Gateway will have its own repository, and its own deployment lifecycle. It will cover business requirements mentioned in the Problem Description section. This new gateway consists of a web application and database components.

It will be an internal component for Ebury systems, so it will separate the conditional business logic from existing main products (BOS & FXSuite) and will be the main integration point of the Bexs system.

  • BGW service sits between Ebury Online (EBO) and Bexs systems.
  • For Brazilian companies (Bexs clients) business operations are handled only by the gateway itself.
  • BGW contains all Bexs integration codes and responsibilities
  • BGW stores:
  • Trade
  • Quote
  • Client Mapping (Ebury <-> Bexs)
  • Beneficiary & Bexs Counterparty relation
  • Spread & Fee configurations
  • EBO displays a separate page (group of sections) for Brazilian accounts, which are directly connected with Bexs business logic via BGW.
  • Custom validations (like convert without pay operations are not permitted for Brazilian companies) are handled on BGW.

Pros: - The proposed solution presented on this RFC does not add extra logic to BOS. This means that it's low risk to deploy new features for Brazilian clients. - Bexs integration will be handled by LMI team members, so it can ship easily & frequently. - MVP solution requires some steps (phases), starting small is easy with a separate solution rather than calculating all responsibilities of all systems that are going to play a role in Brazil Companies' trades. - Time management/calculation/estimations will be more accurate than approach B because of the reduced interaction of other teams on Ebury. (In terms of BOS & FXSuite submodules & code owners) - Source of truth for the Quotes & Trades will be the BGW & Bexs itself, which means any customization on Bexs side will not affect BOS in the future. Bexs-related concerns will be separated from many Ebury services. - Reduced transaction complexity. (Bexs transactions only)

Cons: - System does not create (duplicate) trades on BOS, some of BOS features will not be available for Brazil Clients. (reports & etc.) - Re-Implement spread calculation on the gateway (just like BOS) - Reroute/Display new page for Brazil Companies on EburyOnline (Frontend related tasks going to be created)

Use cases

New permission to enable EBO for Brazilian Clients

For the onboarding of a new Brazilian Company, a custom permission should be added to BOS. This permission will activate Bexs features on the Ebury Online platform.

BOS Permission Strategy

The current business operation flow to onboarding new clients can be checked in this document.

Creating a Trade

Create a Trade

Note: At this stage, the quotes will be retrieved using the regular pricing workflow. [eventually the trade reasons and quoting strategy are going to be addressed in separate RFCs].

  1. After receiving a rate for a trade, the user can confirm it or not, if the action takes too long a rate expiration message will be displayed.
  2. When the user confirms the rate, EBO backends will request the creation of a new trade in the BGW API.
  3. The BGW validates the quote request and beneficiaries. [In case the beneficiaries are new, register them into Bexs through its API]
  4. Then, the BGW requests Bexs API for the exchange creation and stores it in the BGW DB.
  5. Finally, the trade confirmation is displayed to the client in the EBO front end.

Service Ownership

New Service Service Name Service Owner
Yes Bexs Gateway LMI Team
No API WebApp API Team
No BOS TFT Team
No EBO ONL Team

Alternatives

Approach B:

  • Update the conditional logic inside of BOS in order to validate the request for quote action of Brazil Companies:
  • Check limit conditions → check_credit_limit_wont_exceed
  • Update the validation logic inside of BOS in order to prevent creating trades which do not have payments
  • client & trade permission check → confirm_and_complete_new_trade_of_client
  • Store Bexs Quote information on BOS (or a new Ebury Service for Bexs)
  • It can be stored on some other system like the gateway itself and can be used as a mapping data container (trade & quote & beneficiary | integration mapping records)
  • Use Bexs Quote information while creating a new Trade on BOS (specifically for the Bexs clients)
  • Update Beneficiary controllers on BOS in order to manage synchronization between BOS & Bexs records. (CREATE - UPDATE - DELETE? actions)

Pros: - Source of truth for Quotes & Trades will be BOS itself. All trades will be available on BOS. - No need to create a separate section on EBO, but business requirements like conditional validations should be added in the current EBO frontend.

Cons: - Too much change on different projects. This adds more complexity than the first approach. - Leads to increasing review times (because of risky updates on legacy systems), and reduces the release frequency. - New domain information will be added to BOS, this will increase the responsibility of these projects while Ebury trying to separate current responsibilities into new services. - Bexs related data (quote id , trade id. counterparty etc) will be used inside of BOS, hard to traceback errors & difficult to monitor. - Ticket/feature implementation time estimations will vary because of the coupling between BGW & BOS actions.

Caveats

  • BOS does not contain Trade records for Brazilian Companies.
  • There is a one time operation which is going to be held by the Bexs & LMI team, which is importing the legacy clients. Once the BGW DB is defined and deployed, two extractions will be needed:
  • Bexs side - Extract all the clients onboarded through Ebury and provide client_id + information needed to filter BOS registers.
  • Ebury side - Extract all Brazilian clients onboarded with BEX and provide bos_client_id + information needed to filter each register with a unique Bexs register.

With the help of extracted sets, we should be able to match each legacy client record (Bexs → BOS) and load the necessary data in the BGW database manually.

Operation

Bexs Gateway will provide protobuf schemas in order to expose its services to internal usage, according to previous definitions of Ebury 2.0 architecture. EBO will have an autogenerated gRPC client for calling these endpoints.

BGW will use Ebury's de-facto solution for asynchronous communications (Kafka), possibly for synchronization between Ebury's & Bexs client entities and this will be described in its own subsequent RFC.

BGW will implement an integration client for consuming Bexs REST API, in order to create trades, quotes, beneficiaries on Bexs system.

This project is a gateway service that will be published to Ebury's k8s clusters (dxp, staging and prod). The Local Market Infrastructure team is responsible for developing & maintaining it. There is no strict role for deployment & maintenance operations, the team itself will be the responsible for any type of operation with the assistance of SRE team.

Security Impact

The services provided by the BGW will be management & integration services between two business systems Ebury & Bexs, and the direction for the integration messages will be from BGW to BOS, BGW to Bexs, and EBO to BGW. This will cover all direct communication (synchronous) requirements of the services. Still, when there is a need for asynchronous communication which can carry client or trade record data from Bexs to Ebury services, we are planning to use the outbound gateway pattern which will be seperated from the business services and it will only be responsible for producing Kafka Events with the webwook contents.

A seperated RFC is going to describe the strategy we intent to implement for the webhooks and outbound gateway, in which we will use the common Kafka pattern. Although in this very first deliverable we are not going to provide the implementation of this strategy, we have to mention that it will reduce the security impact as it isolates business and 3rd party webhook handling services.

Additionally, the BGW does not alter any existing token or create a new one that can affect BOS/EBO or any existing product.

The BGW will store superficial trade information & relational entity mappings between Ebury & Bexs systems, which means that the client's sensitive data will not be stored inside the BGW and, after the unique mapping action, there shouldn't be any sensitive data flow. The mapping strategy will be discussed in a subsequent RFC as well.

Performance Impact

The critical operations of this business will be creating and managing Quote & Trade entities. In order to provide consistency to these domain objects & their operational results, we are going to use atomic operations when it is possible. When it is required for handling possible race conditions, optimistic locking will be preferred.

Timeout exceptions could be handled while creating trade entities, and Bexs should be providing idempotent endpoints for these type of scenarios.

Other than that, response time of the API services which will be used by the EBO will be very important, because it will affect the user experience of EBO users finally. The BGW will collect metrics of its internal & external functionalities using recommended methods.

Developer Impact

Ebury online will have new (seperate) pages / sections for Brazilian accounts, and these pages are not going to be visible by default. They will be activated/inactivated with a configuration and this will impact frontend development and testing.

Data Contracts

In the first stage, the BGW will not use event/Kafka system. We will create a new data source that will store Brazilian Trades, it's important to state that this database will only be accessible via BGW's REST API.

Data Sources

The main data source used in the project will be Bexs's API.

Business Metrics

Aiming to support business analysis and assessment, we intend to use Prometheus to collect significant metrics and allow the creation of domain-friendly dashboards in Grafana.

Initially, the idea is to provide a high-level business impact analysis of the service every time a new transaction occurs between the BGW and Bexs. For example, displaying the number of trades per a given period and the corresponding amount of money transacted. As the project grows, new metrics could be demanded and implemented to support the Business needs.

Deployment

The first step is to create the new permission entry in the BOS database. Simple DB migration, no downtime.

Then, following the current deployment process, deploy the minor changes in EBO and BOS.

The DevOps team will be needed to help structure the Jenkins CI/CD for the BGW. As this is a new project, there shall be no impacts or downtime in the PROD environment.

Dependencies

N/A