Solution Proposal: Settlement API Participant Identifier is not compatible with FSPIOP Identifiers

[mdebarros]

Solution Proposal: 91 -- Settlement API Participant Identifier is not compatible with FSPIOP Identifiers

---

Open API for FSP Interoperability -- Solution Proposal

Table of Contents

• 1. Preface
  • 1.1 Solution Proposal Information
  • 1.2 Document Version Information

• 2. Change Request
  • 2.1 Background
• 3. Proposed Solution
  • 3.1 Specify how IDs can be generated
  • 3.2 Add quote ID to POST /transfers data model
• 4. Other Considered Solutions
  • 4.1 Add transaction ID to the POST /transfers data model
  • 4.2 Force the Payer FSP to use the transaction ID as transfer ID

1. Preface

___

This section contains basic information regarding the solution proposal.

1.1 Solution Proposal Information

Info	Details
Requested By	Miguel de Barros, ModusBox
Solution Proposal Status	In review [X] / Approved [ ] / Rejected [ ]
Approved/Rejected Date

1.2 Document Version Information

Version	Date	Author	Change Description
1.0	2021-09-07	Miguel de Barros	Initial version. Sent out for review.

2. Change Request

2. Change Request

--- Refer to [mojaloop-specification/issue/91](https://github.com//issues/91) for background information.

3. Proposed Solution

___

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
        "name": "DFSP1", <-- Unique Name identifier for the Participant
        "accounts": [
          {
            "id": 0, <-- This is the ParticipantCurrency (i.e. Account) Identifier
            "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.

3.1 Add FSPIOP identifier to the GET /settlements response Participant data model

This change will require a minor version of the settlements
resource, from version 2.0 to version 2.1.

3.1.1 Current Participants data model

Name	Cardinality	Type	Description
id	1	integer	FSP identifier (i.e. datastore)
accounts	0..many	Accounts	List of Participant Accounts.

3.1.2 Proposed Participants data model

Name	Cardinality	Type	Description
id	1	integer	FSP identifier (i.e. datastore identifier)
name	1	FspId	FSPIOP identifier name as defined as per the FSPIOP Specification definition for #/definitions/FspId'
accounts	0..many	Accounts	List of Participant Accounts.

4. Other Considered Solutions

___

4.1 Add transaction ID to the POST /transfers data model

Alternatively we should consider removing the Datastore Identifier entirely from all Settlement API operations and Participant entities. The reason is that we should be utilizing Functional Identifiers similar to the FSPIOP specification going forward instead of using an identifier that is specific to the underlying Datastore. This, however, would be a breaking change and we would need to introduce a strategy on how we can deprecate the current Participant Identifier's appropriately.

This option is preferred but will be differed for a future vNext version of the Central-Settlement API due to its breaking changes.

[PaulGregoryBaker]

I would like to vote for this change.