Settlement Operational Implementation

Introduction

The objective of this design is to provide a solution that links the business process functions with core-settlement operations on the switch.

This design is an example implementation of a Mojaloop settlement for a specific use case and is not meant to be comprehensive or cover all scenarios. This guide outlines the high-level design and explains the thinking that went into the design for a specific use-case chosen.``` Although a version of this design is built and operational, not everything in this design document has been built. This is an example of a settlement implementation design. The benefit of this design & design document is therefore:

to use for demonstration;
to use as an initial version to help 'Getting Started Quickly';
to use as a starting design on which improvements can be made before adopting;
to use as a starting point to elaborate on concepts that are discussed in this design that may need to be addressed in another design.

Core-Settlement Operations

This is the existing Settlement functionality provided by the supporting Central-Settlement Mojaloop Core component. Detailed information can be found in the Mojaloop Technical Overview Documentation.

The Core-Settlement operations support the following capabilities:

Create a Settlement Matrix Report based on a list of Settlement-Windows
Process Settlement Acknowledgements for an existing Settlement Matrix Report
Manage Settlement-Windows (i.e. Create, Close, etc)
Queries for Settlement Matrix Reports, Settlement-Windows, etc

The OpenAPI definition is available at the Mojaloop-Specification repository.

High-level Architecture

Experience layer

The settlement experience layer is a stateless API that exposes the data to be consumed by its intended audience. Currently it's main function is to add the looked up user information into the API which is injected in the request headers by ORY Oathkeeper proxy. This function is expected to become larger as the product develops.

Process layer

Process APIs provide a means of combining data and orchestrating multiple System APIs for a specific business purpose. The mojaloop central-settlement, and central-ledger API are being consumed by this process API.

The Settlement Process API should conform to the Mojaloop naming standards, and as such the following name will be used: settlement-process-svc.

High-level Settlement Business Process

This is a process that relies on the existing core-settlement operations to orchestrate the following capabilities:

Closing a settlement window The current settlement window can be closed manually as if there have been transfers linked to the settlement window. The hub operator can select the current open window, and then choose to close the window.
Settlement Initiation Settlement Initiation is used by the hub operator to create a settlement batch which controls and drives the settlement process. To initiate the settlement process, the hub operator selects :
- a set of settlement windows
- and optionally a settlement currency or a settlement model. (If a settlement currency is provided, then this is used to determine the settlement model.) The position ledgers of the net credit participants are adjusted during Settlement Initiation. Note: It is important to create the batch settlement object in the way that the settlement is to be completed and finalized.
A Settlement initiation report is generated and used to communicated to the settlement bank the requirements of the settlement.
Settlement Finalization & settlement account re-balancing This process needs to occur after the settlement bank has applied the settlement changes. In this step the:
- settlement process is completed and a settlement finalization report has been received from the settlement bank.
- the net debit participants in the settlement have their position ledgers adjusted.
- the settlement ledgers are adjusted for all participants to match the transferred amount for the settlement.
- the settlement ledgers are checked against the real settlement account balances and adjustments processed to ensure that they are aligned.

Re-balancing function - is not best practice

It is worth noting that the re-balancing function that is defined in the above settlement finalization process is not the preferred or best-practice approach. This approach was chosen because of regulatory requirements and limitations of mechanisms available to implement settlement between participants, i.e. it was designed to work on existing in-place financial solutions. Re-balancing has quite a few drawbacks, and is not considered best practice and should be avoided if possible. These drawbacks are:

Out of sequence re-balancing results in incorrect results. This vulnerability therefore requires a business process and supportive management to enforce.
Reconciliation of the Mojaloop Settlement Account and the settlement bank account is difficult and complicated. This is because the re-balancing may not directly reflect the activity in the settlement bank account. The transfer amounts are linked to the timing of when the re-balancing action is applied, and when the reports and statements are generated.

Recommended solutions There are numerous other approaches to implementing settlement that do follow best practice. Please consult one of the experts in the Mojaloop community if you would like to explore this. If your requirement has similar limitations and creating a new mechanism is not an option, then there is a relatively minor adjustment that can be made to improve this solution and should be considered. Replacing re-balancing mechanism with an import of a statement from the settlement bank account's transactions would remove the timing and reconciling problems mentioned above.

Detailed Sequence Diagram

There are a couple of processes in the sequence diagram that are worth elaborating on.

Determining settlement Model

This need to first determine which currencies are involved in the settlement, and then determine the appropriate list of Settlement Models which should be applied. A Settlement will be created for each of these Settlement Models.

Validation of the settlement finalization data

The data that is presented as part of the settlement finalization needs a significant amount of validations on the data. Some validations check integrity of the data, and these check will fail the process if not passed. Other validations do not prevent the process continuing, however will show warnings that need to be presented to the operator. The continuation of the process is only possible once the operator has accepted the confirmed warnings with their resultant effects, and has provided their selected options for how the process should be applied. It is for this reason that the validation of the data is a necessary step, and must be referenced when accepting and proceeding with the process.

Use cases for Finalize Settlement

Validation scenarios

Validation Description

Expected behaviour

Selected settlement ID does not match report settlement ID

Abort finalization with error

Sum of transfers in the report is non-zero

Abort finalization with error

Transfer amount does not match net settlement amount

Abort finalization with error

Balance not modified corresponding to transfer amount

Continue --> Adjust Settlement Account Balance to align

Balance provided in the report is not a positive value

Continue --> Set settlement balance to zero; set NCD = 0; disable participant POSITION account

Accounts in settlement not present in report

Abort finalization with error

Accounts in report not present in settlement

Abort finalization with error

Participant identifiers do not match - participant ID, account ID and participant name must match

Abort finalization with error

Account type should be POSITION

Abort finalization with error

New balance amount not valid for currency

Abort finalization with error

Transfer amount not valid for currency

Abort finalization with error

Account ID does not exist in switch

Abort finalization with error

Attempted to finalize an aborted settlement

Abort finalization with error

Error processing adjustment for participant