Change Request: Settlement API Participant Identifier is not compatible with FSPIOP Identifiers

[mdebarros]

Open API for FSP Interoperability - Change Request

Table of Contents

• 1. Preface
  • 1.1 Change Request Information
  • 1.2 Document Version Information
• 2. Problem Description
  • 2.1 Background
  • 2.2 Current Behaviour
  • 2.3 Requested Behaviour
• 3 Proposed Solution Options

1. Preface

1.1 Change Request Information

Info	Details
Requested By	Miguel de Barros, ModusBox
Change Request Status	In review ☒ / Approved ☐ / Rejected ☐
Approved/Rejected Date

1.2 Document Version Information

Version	Date	Author	Change Description
1.0	2021-08-23	Miguel de Barros	Initial version of Change Request.

2. Problem Description

2.1 Background

The Settlement API currently returns the Participant Model with the Datastore Identifier.

This can be used to interact with the Settlement API, like acknowledge Settlement requests per Participant.

However, this means that there is no clear way from a Functional perspective to identify the Participant as Mojaloop uses the Participant Name as the identifier in the FSPIOP, and as such, it is difficult to correlate the Participant via the Datastore Identifier as there is no Functional link.

In addition, this Datastore Identifier is not compatible with other Mojaloop APIs. One such example being the Admin API uses the Participant Name and not the Datastore Identifier.

2.2 Current Behaviour

When calling the GET /settlements (getSettlementsByParams) operation, the following response is returned:

[
  {
    "id": 0,
    "state": "string",
    "settlementWindows": [
      [
        {
          "id": 0,
          ...
        }
      ]
    ],
    "participants": [
      {
        "id": 0, <-- This is the Datastore Identifier
        "accounts": [
          {
            "id": 0, <-- This is the ParticipantCurrenty (i.e. Account) Identifier
            "reason": "string",
            "state": "PENDING_SETTLEMENT",
            "netSettlementAmount": {
              "amount": 0,
              "currency": "string"
            }
          }
        ]
      }
    ]
  }
]

As per the background, it is not easy to identify the Participant from a functional perspective. It is also not possible to easily link a Participant from the Settlement API to the Participant operations on the other Mojaloop APIs, such as the Admin API which requires the Participant Name as the identifier.

2.3 Requested Behaviour

All Participant Entities returned by the Settlement API that includes the Datastore Identifier should also include the Participant Name as per the following example:

[
  {
    "id": 0,
    "state": "string",
    "settlementWindows": [
      [
        {
          "id": 0,
          ...
        }
      ]
    ],
    "participants": [
      {
        "id": 0, <-- This is the Datastore Identifier
        "accounts": [
          {
            "id": 0, <-- This is the ParticipantCurrenty (i.e. Account) Identifier
            "name": "DFSP1", <-- Unique Name identifier for the Participant
            "reason": "string",
            "state": "PENDING_SETTLEMENT",
            "netSettlementAmount": {
              "amount": 0,
              "currency": "string"
            }
          }
        ]
      }
    ]
  }
]

This is a minor update to the existing API, and it should have no "breaking" impact on the existing API Specification or the current consumers of the Settlements API.

Pull Request: central-settlement/pull/371

3. Proposed Solution Options

1. All Participant Entities returned by the Settlement API that includes the Datastore Identifier should also include the Participant Name. <-- Non-breaking change, with minimal or no impact to existing API Consumers.
2. Refactor the Settlement API to solely use the Participant Name for both API Operations and Participant Entities. <-- Breaking change. This is the most correct solution but will impact existing API Consumers. However, I believe switching identifiers from the Datastore ID to the Participant Name will not prove to be very difficult as the API and its interactions will function identically. As such this option could be easily adopted by existing API Consumers.

[mdebarros]

Decision made to accept this CR and the following proposal: #94

Attendees:

• @elnyry-sam-k
• @PaulGregoryBaker
• @mdebarros