As discussed on the CCB call on 19 March:

I propose that we use this issue list as a mechanism fro tracking issues and change requests going forward.

Based upon the current process I recommend the following new process:

1. Any issues with the current API or related documents is logged in this issue list.
2. The issue is discussed on the issue list between all stakeholders and if necessary is added to the agenda of CCB calls for deeper discussion (at the discretion of the chair).
3. If there is consensus that the issue warrants a change to the specification, the change is proposed in the form of a Pull Request
4. Further discussion and updates to the PR will result in the PR being accepted by the CCB (and the changes merged into the repo) or rejected and the PR closed.

This allows future discussions to easily reference past issues and PRs where context is required.

5. I further propose that a continuous integration process is adopted that produces well-formatted human readable documents from the source material (open api specs and related markdown documents) automatically whenever changes are merged into the master branch of this repo.

6. Finally, the master branch should be protected to not allow changes to be merged without approval from at least a majority of the CCB.

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

This section contains basic information regarding the change request.

1.1 Change Request Information

| Requested By | Michael Richards, ModusBox |
| Change Request Status | In review ☒ / Approved ☐ / Rejected ☐ |
| Approved/Rejected Date | |

1.2 Document Version Information

2. Problem Description

2.1 Background

The Mojaloop product is being extended to allow PISPs to become participants in Mojaloop schemes. Although PISPs do not have direct control of accounts, they are allowed, subject to the consent of the account owners, to ask the DFSPs who control the accounts to move funds out of those accounts, subject to confirmation by the account holders. The system is expected to be extended in the future to include additional functions, such as the ability to request an account balance or to ask for a statement, or to retrieve an account's KYC status.

It is expected that this process will consist of two separate phases. In the first phase, the PISP will contact the account-holding institution and request access to an account on behalf of a client. The account-holding insitution will satisfy itself that its customer really has granted permission to the PISP; and, subject to that, it will register the PISP as allowed to make requests to debit the customer's account(s).

The resources required to support this phase are:

Outbound:

1. GET /parties, to return the accounts associated with the customer's identifier
2. POST /consentRequests, to request permission to link with a customer's account(s)
3. GET /consentRequests, to enquire after the statur of a linking request.

Inbound:

1. PUT /parties, to receive information about a customer's accounts.
2. PUT /consentRequests, to receive confirmation that a linking request has been accepted for processing or rejected.
3. PUT /consents, to receive information about the final determination of a linking request

In the second phase, the PISP will request an actual transfer. The DFSP will request a quotation, and will then return the result to the PISP, and ask the PISP to obtain consent to the transfer from its customer. On receipt of the confirmation, the DFSP will action the transfer.

The resources required for this phase are:

Outbound:

1. GET /parties, to identify the DFSP of the payee
2. POST /thirdPartyRequests, to request a payment (assuming different resource name from the current /transactionRequests)
3. GET /thirdPartyRequests, ,to enquire after the status of a transaction request.
4. PUT /authorizations, to respond with a customer's confirmation to go ahead with a transfer.
5. GET /transfers, to enquire after the status of a transfer.

Inbound:

1. PUT /parties, to return the DFSP who owns a payee account.
2. PUT /thirdPartyRequests, to receive the status of a transfer request.
3. POST /authorizations, to receive a request from a DFSP for customer consent to a proposed transfer.
4. PUT /transfers, to receive information about whether a transfer has completed successfully or not.

2.2 Current Behaviour

/consentRequests, /consents and /thirdPartyRequests are new resources which do not exist at present.
/parties and authorizations are resources which already exist, but for which changes are proposed as part of PISP development.
/transfers is an existing resource to which no changes are proposed as part of PISP development.

3. Proposed Solution Options

This is an open question for discussion. No solutions are proposed at present.

The attached is a draft document with proposals for how a multi-API change control board might be organised. Please feel free to comment here.
Multi-API CCB Structure.docx

When a cross-currency payment is routed via and FXP the quote is modified by the FXP.
E.g. The sender quotes a SEND in USD but the FXP quotes a SEND in EUR to the receiver.

The following document describes some of the flows and options for accommodating intermediary fees.

https://github.com/mojaloop/cross-network/blob/master/part2-johannesburg-april-2019/quote-flow.md

Let's use this thread to discuss and pick an approach.

Current list of items for v1.1 of the Mojaloop FSPIOP API

The current API (v1) is aligned with a legacy version of the Interledger protocol (v1). We should align the API to ILPv4, not only for the sake of deprecating what is an outdated implementation, but also to enable us to use the latest open source Interledger components.

FSPIOP API as a "Bilateral Protocol" in ILP

In an Interledger transaction ILP packets are passed between participants with a direct bilateral relationship. The ILP packet headers carry the details of the transfer from the one participant to the other whereas payload of the packet are end-to-end data that is used to convey transaction information from the payer to the payee.

When looking at the API, in the context of the Interledger protocol, we consider a transfer between two DFSPs as analogous to the exchange of ILP packets between nodes. i.e. The /transfer API represents a single "hop".

The end-to-end data is carried in the Transaction object (currently encoded inside the ILPv1 packet payload)

NOTE: In the future we may wish to explore modelling a Mojaloop network such that the switch is also a node and the transfer from DFSP to DFSP is modelled as two "hops" instead of one. This would enable the switch to apply dynamic fees to the transfers.

In ILPv1, the ILP packet was enveloped in what was called a "ledger protocol" message. Ledger protocols were used between nodes and their shared ledger and contained the details of the transfer including the condition, expiry and transfer amount. The ILPv1 packet contained the ILP address of the payee, the destination amount and the end-to-end data payload.

In ILPv4, the protocol was adjusted to be used directly between nodes via a "bilateral protocol". In the bilateral protocol model the detail of the transfer between the the two nodes is now included in the ILPv4 packet headers, including:

• The transfer amount
• The execution condition
• The transfer expiry

The destination amount was dropped from the packet headers as this is sensitive data and is expected to be part of the end-to-end payload.

In Interledger terminology the FSPIOP /transfer API is therefor a bilateral protocol (carrying the details of the transfer between nodes), however it is missing the ILP address of the payee.

The concrete changes proposed are:

1. Remove ilpPacket from the transfer object.
2. Add the Transaction object as a property of the transfer object (previously the payload of the embedded packet).
3. Define a new optional property of the Party data type to carry the address of the party. E.g. Payee.PartyAddress. This data element will be an ASCII string with a length restriction of 1023 characters.

With these changes the /transfer API is now a direct mapping from the ILPv4 packet:

Open API for FSP Interoperability - Change Request

Table of Contents

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

1. Preface

This section contains basic information regarding the change request.

1.1 Change Request Information

2. Problem Description

2.1 Background

The OpenApi definitions of v1.0 and v1.1 of the FSPIOP Specification defines components that are not used.

2.2 Current Behaviour

Current definition has unused components which are redundant or needs updating. Using bundling libraries can lead to unwanted behaviour when rending out a microservice interface.

2.3 Requested Behaviour

References are updated. Redundant components are removed.

3. Proposed Solution Options

Update references in v1.0 and v1.1 document sets.

• https://github.com/mojaloop/mojaloop-specification/blob/master/fspiop-api/documents/v1.0-document-set/fspiop-rest-v1.0-OpenAPI-implementation_openapi3.yaml

• https://github.com/mojaloop/mojaloop-specification/blob/master/fspiop-api/documents/v1.1-document-set/fspiop-v1.1-openapi3.yaml

List of defined but unused components

v1.0

Amount
AmountType
AuthenticationInfo
AuthenticationType
AuthenticationValue
AuthorizationResponse
BalanceOfPayments
BinaryString
BinaryString32
BulkTransferState
Code
CorrelationId
Currency
Date
DateOfBirth
DateTime
ErrorCode
ErrorDescription
ExtensionKey
ExtensionValue
FirstName
FspId
IlpCondition
IlpFulfilment
IlpPacket
IndividualQuote
Integer
LastName
Latitude
Longitude
MerchantClassificationCode
MiddleName
Name
Note
OtpValue
PartyIdentifier
PartyIdType
PartyName
PartySubIdOrType
PersonalIdentifierType
RefundReason
QRCODE
TokenCode
Transaction
TransactionInitiator
TransactionInitiatorType
TransactionRequestState
TransactionScenario
TransactionState
TransactionSubScenario
TransferState
UndefinedEnum

v1.1

BinaryString
BinaryString32
Date
Integer
Name
PersonalIdentifierType
TokenCode
Transaction
UndefinedEnum

TIPS needs to do a more detailed analysis of initiator types than is supported by the current enumeration. We should add the following entries to the list given in Section 7.5.9 of the API specification:

• GOVERNMENT
• NGO

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

This section contains basic information regarding the change request.

1.1 Change Request Information

| Requested By | Michael Richards, ModusBox |
| Change Request Status | In review ☒ / Approved ☐ / Rejected ☐ |
| Approved/Rejected Date | |

1.2 Document Version Information

2. Problem Description

2.1 Background

At present, the Mojaloop switch makes no distinction between the roles that participants can have. It is an implicit assumption that, once a participant is onboarded to a Mojaloop system, it can have access to all of the resources that the API provides; indeed, actual schemes may make it a condition of participation that a DFSP should handle all the resources that the API defines.

The addition of PISP services to the use cases supported by Mojaloop opens a new set of questions about the resources that a participant is allowed to support. A PISP does not offer account services to its users, and therefore ahould not be able to access a relatively large number of API resources: for instance, it should not be able to initiate a quote or a transfer, nor should it be able to respond to them directly. The Mojaloop switch will therefore need to be able to distinguish between participants based on the roles they perform, and to deny access to participants who are attemtoing to use API resources to which their role does not allow them access.

It is not clear how this functionality will, or should, operate in a peer-to-peer environment. Presumably, in a peer-to-peer environment, it would be the responsibility of the recipient of a message to satisfy itself that the sender had a role which allowed it to send that message, and to reject the message if it did not believe that the originator was allowed to send it.

Although the immediate requirement for this functionality is to support PISP, there are other expected types of participation which will also require access to API resources to be restricted for the institutions that fulfil them: FX services and Cross-network services are examples.

There are (at least) two pressing consequences to this requirement.

First, segmenting access to API resources by role type will require the switch (or a participant in a peer-to-peer network) to assess every message which it receives for validity. Depending on implementation, it may be possible to exempt some kinds of resources (e.g. GET /parties) from checking; but, in any case, the check will need to be performed at the message level. There is therefore a significant opportunity for the overall performance of the switch to be impaired if the functionality is not implemented in the most efficient way possible.

Second, there will need to be a method for defining the types of role that a scheme will support, the resources that each role is allowed to access, and the role(s) that any given participant has. This will be relatively slowly changing information, and we may therefore decide that there is no need to extend the API to allow participants to set or get that information. On the other hand, it may be valuable for participants (or a switch) to be able to obtain information about the participants who fulfil a particular role in a scheme: for instance, to be able to find out which participants provide FX services - or, indeed, DFSP services. If these facilities are required, then the API will need to be extended to accommodate them.

2.2 Current Behaviour

This is new functionality. It is not currently covered in the API.

3. Proposed Solution Options

In most cases, it will be clear which resources a PISP is allowed to use. The exception is the /transactionRequests resource. This is used both by a merchant request to pay (which only a DFSP is allowed to issue) and by a PISP request. The only current way of distinguishing between them is by checking the content of the message to see whether the payee DFSP is also the sender of the message. If it is, this is a merchant request to pay; if it isn't, it's a PISP request.

In order to be able to distinguish between these types of request, we could add a new resource (say /thirdPartyRequests, which a PISP would be allowed to use but a DFSP would not. This would allow requests to be sifted efficiently at the API level. We might want to reinforce things further by removing the payee element from the POST /transactionRequests resource: since it would now only be used by MRTP, the payee could only ever be the same as the sending DFSP.

We could assume for the moment that the information required to specify the types of role supported by the system and the assignment of resource access to roles will be managed internally by the switch, without needing to modify the API. Additional services could be added if required to give participants access to the list of participants who fulfilled a given role (or, in a P2P network ti find if a given participant had a given role.)

Current thinking on the assignment of resources to roles is given here: mojaloop/pisp-project@376f064

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

Traceability of API requests within a deployed Mojaloop implementation is paramount to the Hub Operators ability to successfully and effectively provide operational support in issue resolution. This change-request is to

1.1 Change Request Information

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

1.2 Document Version Information

2. Problem Description

2.1 Background

The Mojaloop product is implemented using several distributed services, this implementation pattern being known as a micro-service architecture. A result is that a single transaction may be processed or handled by multiple services within the Mojaloop stack. This introduces a challenge for operational monitoring as it is difficult to trace or monitor a transaction as it flows through each of these distributed services.

2.2 Current Behaviour

At present, there is a tracing solution implemented in the current Mojaloop stack as part of the Event Framework.

This requires several non-standard FSPIOP specification headers which contain the trace-context (ref: Event Framework - Tracing Design - 4.1.1 W3C HTTP Headers) to be:

• processed by the Hub, and
• forwarded by participants on call-back requests.

The result being that FSPs are not currently forwarding tracing-context headers FSPIOP call-backs. This means that traces are currently broken into each of the FSPIOP legs of the PayerFSP request and PayeeFSP call-back.

Let's take Transfers as an example:

1. Mojaloop receives a Transfer Prepare Request, assuming there is no trace-context header from the PayerFSP, a trace-context is created by Mojaloop ML-API-Adapter. This trace-context is propagated through each of the micro-services and is utilised for monitoring purposes until the notification has been sent to the PayeeFSP.
2. When receiving the Transfer Fulfil Callback from the PayeeFSP, which does not contain the forwarded trace-context headers, Mojaloop will not have the necessary context to continue the trace from the prepare-leg (i.e. point 1 above). As such a new context is created from the point of receiving the fulfilment and until the notification is sent to the PayerFSP.

Thus we end up with two distinct trace-context for each leg of the Transfer.

2.3 Requested Behaviour

The W3C Tracing headers as describes in following design document: Event Framework - Tracing Design - 4.1.1 W3C HTTP Headers, are included as part of the FSPIOP specification with functional information on how the Mojaloop Switch and Participants should handle or process them appropriately.

Note: Participants are not required to do any additional processing of these tracing headers, but at a minimum, they should forward the tracing headers as part of FSPIOP call-back. This will ensure that there is an unbroken transactional trace from the switch to the FSP.

Let's take Transfers as an example:

1. Mojaloop receives a Transfer Prepare Request, assuming there is no trace-context header from the PayerFSP, a trace-context is created by Mojaloop ML-API-Adapter. This trace-context is propagated through each of the micro-services and is utilised for monitoring purposes until the notification has been sent to the PayeeFSP.
2. When receiving the Transfer Fulfil Callback from the PayeeFSP, the trace-context is included as a header, Mojaloop will then process this trace-context and continue the trace from the prepare-leg (i.e. point 1 above). As such the same context is now used from the point of receiving the prepare and until the fulfilment notification is sent to the PayerFSP.

Thus we end-up with single trace-context for both legs of the Transfer.

Example demo using simulated FSPs which support the tracing standard: https://youtu.be/JGL5HfYi0wE.

3. Proposed Solution Options

Refer to the W3C's Trace Context Level 2 Document for more detail on the standard that is currently supported by the Event Framework.

However, there are other tracing standards that can be considered such as Zipkin's B3 Propagation Design.

We propose to add these as optional headers so that the changes are backwards compatible so that Schemes that implement/deploy Mojaloop can decide on their usage (making them mandatory or optional for their Scheme).

Describe the bug
Some links in the markdown version of API Definition version 1.1 does not work. This is because we added a Resource Version History section in the beginning of each Resource section as part of version 1.1, starting from section 6.2 to 6.10, which increased the section numbers for subsequent subsections, and this is not automatically handled in markdown.

To Reproduce
See for example https://docs.mojaloop.io/mojaloop-specification/fspiop-api/documents/API%20Definition%20v1.1.html#6731-get-transfersid, there is a link to PUT /transfers/{ID} in that, but the link is using the section number from API Definition 1.0; 6.7.3.1 instead of the correct 6.7.4.1 as we added section 6.7.1 for the Resource Version History.

Expected behavior
Links within the markdown document work properly.

Screenshots
See below where hovering above PUT /transfers/{ID} link shows link containing ..#6731, instead of the correct ..#6741.

Desktop (please complete the following information):
N/A

Smartphone (please complete the following information):
N/A

Additional context
N/A

As discussed in the CCB call on 19 March:

I propose that we use the Open API Specification v3 version of the API specification as the primary reference for the API Definition.

This will allow us to easily track changes using Git and also more easily assess proposals using GitHub Pull Requests. (Also see #9 which proposes using GitHub for issue tracking).

Where possible I propose we also do away with documents that could be replaced with existing standards as these add an unnecessary maintenance burden on the project.

Proposed changes to existing documents:

• Logical Data Model & JSON Binding Rules

These documents could be replaced with a comprehensive JSON Schema definition for all types. If this is done with care these schemas can be referenced directly from the Open API v3 specification which would no longer need all of the schemas to be redefined.

This also allows developers to use the data models in isolation.

While I recognise the desire to have a binding-free data model definition we should be pragmatic about the cost of maintaining this AND bindings definitions.

If we REALLY want to we could define the data models using ASN.1 and generate JSON Schema from this but that seems like unnecessary overhead.

• API Definition

Migrate to be an Open API v3 schema. This would be a lightweight document, especially if it references all data schemas from the stand-alone data model definitions.

Tags and annotations can be used to provide much of the necessary additional context in auto-generated documentation that would be produced from the YAML format spec.

A good CI process would auto-publish a rich human readable version of the spec whenever changes are published to the YAML file.

• Generic Transaction Patterns
• Use Cases
• Scheme Rules
• Data Integrity, Confidentiality, and Non-Repudiation
• PKI Best Practices
• Signature
• Encryption

Ideally these documents could be migrated to Markdown so that the source text is easy to edit and collaborate on without external tools.

Admittedly tables are a challenge in markdown but they are not impossible and this makes the barrier to entry for contributions lower.

Images

The specifications contain a rich set of extremely valuable diagrams. Migrating these to a form that supports collaboration is tracked in this issue #10.

Let's keep this issue focused purely on the documents themselves.

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

Settlement 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

1.2 Document Version Information

2. Change Request

2. Change Request

Refer to mojaloop-specification/issue/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
            ...
          }
        ]
      }
    ]
  }
]

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 Remove Datastore Identifiers completely from the data models

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 Identifiers appropriately.

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

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

This section contains basic information regarding the change request.

1.1 Change Request Information

1.2 Document Version Information

2. Problem Description

2.1 Background

This is regarding the interpretation of the extensionList element's Data Model, from sections 7.4.4 of the API Definition v1.0. This element is present in several complex data structures used for quotes, transfers, error information and such others.

2.2 Current Behaviour

For ease of reference, here's the data model for extensionList (Section 7.4.4), taken from the API Definition v1.0 document.

ExtensionList

Table 72 contains the data model for the complex type ExtensionList.

Table 72

| Name | Cardinality | Format | Description |
| --- | --- | --- | --- |
| extension | 1..16 | Extension | Number of Extension elements. |

A representation of this in a Open API / Swagger looks like below:

extensionList:
{
  extension:
  [ 
    { 
      “key”: “item1”, 
      “value”: “Description for item1” 
    }, 
    { 
      “key”: “item2”, 
      “value”: “Description for item2” 
    }
  ]
}

This is how the current v1.0 Swagger (a supporting file of the Specification document set) represents the extensionList element, as can be seen here.

However, some of the examples given in the Specification document set indicate either a different interpretation of the data model definition or an error, which is making this ambiguous.

1. Here's an example from the API Definition:
   https://github.com/mojaloop/mojaloop-specification/blob/master/documents/API%20Definition%20v1.0.md#listing-5

{
    "errorInformation": {
        "errorCode": "3001",
        "errorDescription": "The Client requested an unsupported version, see exten-
sion list for supported version(s).",
        "extensionList": [
            { "key": "1", "value": "0"},
            { "key": "2", "value": "1"},
            { "key": "4", "value": "2"},
        ]
    }
}

2. Here's another example from the Encryption document:
   https://github.com/mojaloop/mojaloop-specification/blob/master/documents/Encryption.md#41-encryption-example

"extensionList": [
        { "value": "value1", "key": "key1"},
        { "value": "value2", "key": "key2"},
        { "value": "value3", "key": "key3" }
    ]

2.3 Requested Behaviour

There seems to be a need to clarify the data model so that it eliminates ambiguity. This may be done by providing examples of each type, one each for Simple, Complex types and some others so that they can be representative of how the data model definitions are to be interpreted.

It may also be moved to the proposed "Implementation Guide" document. However, the example already present in the Specification documents will need to be updated if they're found to be incorrect.

3. Proposed Solution Options

This may or may not need a change directly to the data model, but I think having a consensus regarding the interpretation and adding examples for the data structures representing each type would eliminate scope for misinterpretation. As mentioned above, the existing examples need to be reviewed for accuracy.

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

This section contains basic information regarding the change request.

1.1 Change Request Information

| Requested By | Sam Kummary |
| Change Request Status | In review ☒ / Approved ☐ / Rejected ☐ |
| Approved/Rejected Date | |

1.2 Document Version Information

2. Problem Description

2.1 Background

This issue is about handling error cases that happen during processing of PUT /transfers/{ID} calls. Specifically, about how a Switch should deal with a scenario when a validation error occurs during processing of a PUT /transfers/{ID} call. The API Error Handling section of the FSPIOP API Definition doesn't seem to touch on the error scenarios that happen during processing of PUT calls (validation or processing errors in a message that passes schema validation).

The FSPIOP API patterns do not support responding to a PUT with another PUT call. Inline with this, the current (Mojaloop) Switch implementation doesn't support sending an error callback (PUT /transfers/{ID}/error) to the Payee FSP in case of failures that happen because of validation issues of a PUT /transfers/{ID} call. However the Payer FSP is notified. However, if a Payee FSP requests for the final notification (by sending transferState as 'RESERVED' introduced with FSPIOP API v1.1: https://docs.mojaloop.io/mojaloop-specification/fspiop-api/documents/API%20Definition%20v1.1.html#6726-commit-notification)), it will receive a notification on finalization of the transfer.

Based on feedback from current adopters and implementers of Mojaloop, there is a need for Payee FSPs to be notified of failures in committing a transfer, which from the Payee FSP's perspective are COMMITTED, even in cases where the Payee FSP doesn't explicitly request to receive a final notification (using transferState as 'RESERVED').

2.2 Current Behavior

Explain how the API currently behaves.

Currently, if a validation error occurs during processing of a PUT /transfers/{ID} call, there is no error notification or callback to the Payee FSP. Only the Payer FSP will be notified. (In implementation, an error will be logged, which will need to be followed-up manually or separately).

2.3 Requested Behavior

To support this request, as discussed on the FSPIOP SIG call on the 2nd of November 2021, a new notification will be introduced with the next version of the FSPIOP API (v1.2 or 2.0 depending on whichever is published first, TBD by the SIG).

A PATCH /transfers/{ID}/error notification will be made to the Payee FSP in case of a processing failure resulting in a transfer being 'ABORTED' following a PUT /transfers/{ID} From a Payee FSP.

Example:

When a PUT /transfers/{ID} is sent from a Payee FSP in response to an earlier POST /transfers call, with an invalid completedTimestamp value which the Switch considers invalid (value passes schema validation, but is in the future, for example), then - currently the Switch doesn't make any additional call or send out any notification to the Payee FSP (only the Payer FSP receives an error callback and the error is logged internally).

With the proposed change, the Payee FSP receives a PATCH notification on the /transfers/{ID}/error end-point

3. Proposed Solution Options

Proposed solution: The Switch sends a PATCH notification on the /transfers/{ID}/error end-point to a Payee FSP when processing errors such as validation issues happen while processing a PUT /transfers/{ID} request from the Payee FSP.

This is in addition to the usual PUT error callback made to the Payer FSP on failures and also separate from the PATCH notification made to the Payee FSP when it explicitly requests a notification on finalization of a transfer (introduced in v1.1 by sending transferState=RESERVED)

Example:

If this change is approved and implemented,

1. A POST /transfers request is sent by a Payer FSP

{
  "transferId": "3f2be6ce-f2d7-4202-bd7b-1f33c5f979d9",
  "payerFsp": "testingtoolkitdfsp",
  "payeeFsp": "mojapayeefsp",
  "amount": {
    "amount": "100",
    "currency": "USD"
  },
  "expiration": "2021-11-03T17:35:37.373Z",
  "ilpPacket": "AYIDIgAAAAAAACcQIWcubW9qYXBheWVlZnNwLm1zaXNkbi4yNzcxMzgwMzkxMoIC9GV5SjBjbUZ1YzJGamRHbHZia2xrSWpvaU0yWXlZbVUyWTJVdFpqSmtOeTAwTWpBeUxXSmtOMkl0TVdZek0yTTFaamszT1dRNUlpd2ljWFZ2ZEdWSlpDSTZJakppTVRZMU1EWTJMVFkxWlRjdE5HTXhOaTFpWWpCa0xXWTRPV1l6WmpoaU5qWmtaU0lzSW5CaGVXVmxJanA3SW5CaGNuUjVTV1JKYm1adklqcDdJbkJoY25SNVNXUlVlWEJsSWpvaVRWTkpVMFJPSWl3aWNHRnlkSGxKWkdWdWRHbG1hV1Z5SWpvaU1qYzNNVE00TURNNU1USWlMQ0ptYzNCSlpDSTZJbTF2YW1Gd1lYbGxaV1p6Y0NKOWZTd2ljR0Y1WlhJaU9uc2ljR0Z5ZEhsSlpFbHVabThpT25zaWNHRnlkSGxKWkZSNWNHVWlPaUpOVTBsVFJFNGlMQ0p3WVhKMGVVbGtaVzUwYVdacFpYSWlPaUkwTkRFeU16UTFOamM0T1NJc0ltWnpjRWxrSWpvaWRHVnpkR2x1WjNSdmIyeHJhWFJrWm5Od0luMHNJbkJsY25OdmJtRnNTVzVtYnlJNmV5SmpiMjF3YkdWNFRtRnRaU0k2ZXlKbWFYSnpkRTVoYldVaU9pSkdhWEp6ZEc1aGJXVXRWR1Z6ZENJc0lteGhjM1JPWVcxbElqb2lUR0Z6ZEc1aGJXVXRWR1Z6ZENKOUxDSmtZWFJsVDJaQ2FYSjBhQ0k2SWpFNU9EUXRNREV0TURFaWZYMHNJbUZ0YjNWdWRDSTZleUpoYlc5MWJuUWlPaUl4TURBaUxDSmpkWEp5Wlc1amVTSTZJbFZUUkNKOUxDSjBjbUZ1YzJGamRHbHZibFI1Y0dVaU9uc2ljMk5sYm1GeWFXOGlPaUpVVWtGT1UwWkZVaUlzSW1sdWFYUnBZWFJ2Y2lJNklsQkJXVVZTSWl3aWFXNXBkR2xoZEc5eVZIbHdaU0k2SWtOUFRsTlZUVVZTSW4xOQA",
  "condition": "9ee-caNM-FwogFXc3wV6T_Wgw0OATckyfAgJrQPBqx0"
}

2. The Payee FSP receives it and responds with a corresponding PUT /transfers/3f2be6ce-f2d7-4202-bd7b-1f33c5f979d9 message with an invalid completedTimestamp value that follows the data type pattern but is invalid (is in the future according to the Switch), or some other validation failure happens on the Switch (the fulfilment is invalid, etc).

{
    "completedTimestamp": "2023-11-03T17:34:37.786Z",
    "transferState": "COMMITTED",
    "fulfilment": "dLsfm72QFTgzIo5SteCWwqoB4yIZt3RLmG7k4fIH84k"
}

3. The Switch logs it as an error and marks the transfer as ABORTED.
4. An error callback PUT /transfers/3f2be6ce-f2d7-4202-bd7b-1f33c5f979d9/error is sent to the Payer FSP and an error notification PATCH /transfers/3f2be6ce-f2d7-4202-bd7b-1f33c5f979d9/error is sent to the Payee FSP.

{
    "errorInformation": {
      "errorCode": "3100",
      "errorDescription": "Generic validation error"
  }
}

29 – Possibility to notify Payee FSP on successful commit in Switch

Open API for FSP Interoperability - Change Request

Table of Contents

• Preface
  • Change Request Information
  • Document Version Information
• Problem Description
  • Background
  • Current Behaviour
  • Requested Behaviour
• Proposed Solution Options

Preface

This section contains basic information regarding the change request.

Change Request Information

Document Version Information

Problem Description

Background

In order for a Payee FSP to ascertain that a transfer has been committed successfully in the Switch, the Payee FSP today needs to send a GET /transfers/<ID> to the Switch as detailed in Section 6.7.1.6 in the API Definition. The functionality to check the status is important for some use cases where it is complicated to perform a refund in case of problems, for example in cash-out or merchant payment use cases where the funds are paid out in cash or the funds are used to purchase goods or services. To avoid having to send the GET /transfers/<ID>, the change request is to allow the Payee FSP to tell the Switch that the funds have been reserved, and the Switch will then send a notification to the Payee FSP when the transfer is committed in the Switch.

Current Behaviour

The Payee FSP today needs to send a GET /transfers/<ID> to the Switch to know the status in the Switch.

Requested Behaviour

The Payee FSP can send the PUT /transfers/<ID> to the Switch saying that the funds are reserved and that it would like a notification when the transfer is committed in the Switch.

Proposed Solution Options

To indicate that the Payee FSP would like to have a notification regarding the status in the Switch before it will commit the transfer (the transfer must be reserved in the Payee FSP), the Payee FSP should send a PUT /transfers/<ID> with the transferState set to RESERVED instead, and no completedTimestamp as the transfer is not yet completed:

PUT /transfers/85feac2f-39b2-491b-817e-4a03203d4f14 HTTP/1.1
Content-Type: application/vnd.interoperability.transfers+json;version=1.0
Content-Length: 166
Date: Tue, 15 Oct 2019 08:14:02 GMT
FSPIOP-Source: DFSP2
FSPIOP-Destination: DFSP1
FSPIOP-Signature: {"signature": "YXBwbGlj...JzK2pzb2"}
{
"fulfilment": "mhPUT9ZAwd-BXLfeSd7-YPh46rBWRNBiTCSWjpku90s",
"transferState": "RESERVED",
}

Switch receives the PUT /transfers/<ID>, responds with HTTP 200 as normal. Switch then looks at the transferState element:
• If transfer state is COMMITTED, then there is no need to send out a notification as the Payee FSP has already accepted the risk that the transfer in some rare cases might fail. This is how it works in the API today.
• If transfer state is RESERVED, then the Switch needs to send out a notification when the transfer is committed in the Switch.

If the Switch should send out a notification (transfer state is RESERVED), the “JSON Merge Patch” standard as defined in https://tools.ietf.org/html/rfc7386 is used (except that we should continue to use the Content-Type header from the API). This is the simplistic version for patching existing JSON instead of the more complex “JSON Patch” standard (https://tools.ietf.org/html/rfc6902). JSON Merge Patch allows the Switch in a standardized way to just send out the elements that should be changed, i.e. the completedTimestamp and the transferState. Example:

PATCH /transfers/85feac2f-39b2-491b-817e-4a03203d4f14 HTTP/1.1
Content-Type: application/vnd.interoperability.transfers+json;version=1.0
Content-Length: 166
Date: Tue, 15 Oct 2019 08:14:03 GMT
FSPIOP-Source: Switch
FSPIOP-Destination: DFSP2
FSPIOP-Signature: {"signature": "YXBwbGlj...JzK2pzb2"}
{
"completedTimestamp": "2019-10-15T08:14:03.113+01:00",
"transferState": "COMMITTED",
}

When the Payee FSP receives the PATCH /transfers/<ID> notification, it responds with HTTP 200, and then either:
• If the transferState is set to COMMITTED, the Payee FSP commits the transfer
• If the transferState is set to ABORTED, the Payee FSP cancels the reserved transfers and aborts the transaction

If the Payee FSP does not get the notification from the Switch within a reasonable time, it can resend the PUT /transfers/<ID> to the Switch as the request should be idempotent. The Switch should then send (or resend) the PATCH /transfers/<ID> to the Payee regarding the status in the Switch. This is to align the flow with all other requests that can be resent to request a new callback (see for example Section 9.4 in API Definition).

The Payee FSP will need to receive the status from the Switch before committing, or accept the risk that the transfer in the Switch might have failed. The Payee FSP should not be allowed to abort the transaction without receiving an ABORTED state from the Switch, as the Payee FSP has sent the fulfilment (which is the commit trigger) to the Switch.

The suggested sequence flow for the communication between the Switch and the Payee FSP:

Deleted

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

1.2 Document Version Information

2. Problem Description

2.1 Background

The Admin API schemas definition for the Participant contains two Identifiers, the name, and an id as follows:

Participant:
  title: Participant
  type: object
  properties:
    name:
      description: The name of the participant.
      type: string
      example: hub
    id:
      description: The identifier of the participant in the form of a fully qualified domain name combined with the participant's `fspId`.
      type: string
      example: dev1-central-ledger.mojaloop.live/participants/hub

There is some confusion between the two. In a traditional REST context, one would expect to use the id to interact with Admin API's operations, however, the name is actually used for this purpose.

2.2 Current Behaviour

The name is the functional identifier and is used for all Admin API operations such as the GET /participants/{name}.

However, I am uncertain as to the use & requirements for the id as I am not aware of any Hub implementor, FSPs or Mojaloop Services that utilise this Fully Qualified Domain Name (FQDN).

Example of the Admin API GET /participants response:

[
  {
    "name": "hub",
    "id": "dev1-central-ledger.mojaloop.live/participants/hub", <-- FQDN Identifier
    "created": "2021-01-12T10:56:30.000Z",
    "isActive": 0,
    "links": {
      "self": "dev1-central-ledger.mojaloop.live/participants/hub"
    },
    "accounts": [
      {
        "id": 1,
        "ledgerAccountType": "POSITION",
        "currency": "AED",
        "isActive": 0,
        "createdDate": "2021-01-12T10:56:30.000Z",
        "createdBy": "unknown"
      }
    ]
  }
]

2.3 Requested Behaviour

To be discussed

3. Proposed Solution Options

To be discussed

• No change, i.e. keep the identifier as the FQDN
• Remove the identifier as there is no apparent use for it
• Modify the identifier to return the Datastore Identifier <-- this aligns with the Settlement API, and the existing CR [mojaloop/specification/#91](https://github.com/mojaloop/mojaloop-specification/issues/910

Describe the bug
Section 10 (End-to-End Example) incorrectly uses unicode encoded equals sign. The IlpPacket in Listings 45, 47, and 49 should end with ...== instead of ...\u003d\u003d. \u003d is = in unicode.

Expected behavior
\u003d should be = in Listing 45, 47, and 49.

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

This section contains basic information regarding the change request.

1.1 Change Request Information

| Requested By | Sam Kummary |
| Change Request Status | In review ☒ / Approved ☐ / Rejected ☐ |
| Approved/Rejected Date | |

1.2 Document Version Information

2. Problem Description

2.1 Background

The Operations of [Funds In and Funds Out](https://docs.mojaloop.io/api/administration/central-ledger-api.html#funds-in-and-funds-out) of the FSP participants are currently part of the Administration API.

These are facilitated by a POST or PUT HTTP message on the resource /participants/{name}/accounts/{id},
/participants/{name}/accounts/{id}/transfers/{transferId} (to record a transfer as a funds in/out transaction for the participant account) which can be misleading if not un-informative.

2.2 Current Behaviour

Currently the request POST /participants/{name}/accounts/{id} is used to record Funds In or Out of a participant account and a PUT /participants/{name}/accounts/{id}/transfers/{transferId} is used to record a transfer as a Funds In or Out transaction for a participant account.

2.3 Requested Behaviour

Keeping the behavior the same, the proposal is to move this functionality to the "Settlement API" introducing resources that are meaningfully named, such as /fundsin ? /fundsout' or /funds` and have an additional field in the data model of the message to indicate in/out or an enum (or as a parameter).

3. Proposed Solution Options

Current list of candidate items for v2.0 of the Mojaloop FSPIOP API

Thanks to Michael for an initial draft for the PISP/ third party API [doc file attached to this issue] -
Draft PISP Specification Changes.docx

This also encompasses issue: #68

The specification contain a rich set of extremely valuable diagrams.

We should find a way to store these in Git so that it is possible for change requests to be made that include modified versions of the diagrams to illustrate the changes more effectively.

This would require that they are stored in a form that is editable, preferably with minimal extra tooling.

Perhaps SVG is a good option?

Following up from our discussion today, our current proposal for the PISP API requires changes to how the FSPIOP-API handles the Transaction object, and the contents of the Transaction object.

Our existing proposal includes the following:

1. Including the Transaction object in plaintext for the PUT /quotes/{id} POST /transfers request
2. The addition of a subscriptions list, which contains interested parties who should be informed by the switch upon the conclusion of a transaction
3. Linking together the transactionId, transferId and transactionRequestId in one place

The question raised during the meeting was "Do we need the FSPIOP v2.0 API (with the above changes) for the PISP API to work?"

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

This section contains basic information regarding the change request.

1.1 Change Request Information

1.2 Document Version Information

2. Problem Description

2.1 Background

There has been discussion for some time in the Mojaloop community about how to manage currency conversion as part of funds transfers. A version of this has been implemented by Mowali, but this has operational drawbacks which have prompted a search for a simpler and more robust alternative. Following discussions with interested parties, an initial statement of a proposed solution has been created and is attached to this document.

This solution (like any solution to the problem of currency conversion) will require some changes to the FSPIOP API, and these are described in Section 6.1 of the attached document. It is proposed that the required changes should be non-breaking, but this is a matter for review.

2.2 Current Behaviour

The API does not support currency conversion at present.

Explain how you would like the API to behave.

The attached document explains the proposed behaviour

3. Proposed Solution Options

API Candidate for currency conversion support in Mojaloop.docx

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

This section contains basic information regarding the change request.

1.1 Change Request Information

1.2 Document Version Information

2. Problem Description

2.1 Background

The proposed Third Party API reuses a number of existing data models and API resources as the
FSPIOP API. In particular are the resources /participants and /parties, which the API
proposes to use to (1) register and lookup the authoritative source of a Consent object with
the Account Lookup Service, and (2) register and lookup an account identifier issued by an FSP
to a PISP.

See the following links for examples of how these resources are used in the Third Party API:

• Registering the Credential
• Finalizing the Consent

In order to use these resources in the Third Party API, the PartyIdType enumeration must be
extended to include the allowed values CONSENT and THIRD_PARTY_LINK.

2.2 Current Behaviour

The existing FSPIOP API does not allow for the a PartyIdType of CONSENT or THIRD_PARTY_LINK in the
/participants or /parties resources.

Requests such as GET /parties/CONSENT/<ID> or POST /participants/THIRD_PARTY_LINK/<ID> are considered
invalid.

2.3 Requested Behaviour

The PartyIdType
enum should be extended to include the following values:

The following are 4 example HTTP requests of how the extended PartyIdType fields may be used:

Example 1 - Association of a THIRD_PARTY_LINK identifier to a PISP

POST /participants/THIRD_PARTY_LINK/123456789 HTTP/1.1
Accept: application/vnd.interoperability.participants+json;version=1.1
Content-Length: 50
Content-Type: application/vnd.interoperability.participants+json;version=1.1
Date: Tue 12 Oct 2021 10:12:24 GMT
FSPIOP-Source: dfspa
FSPIOP-Destination: Switch
{
    "fspId": "pispa"
}

Example 2 - Lookup of a THIRD_PARTY_LINK identifier

GET /participants/THIRD_PARTY_LINK/123456789 HTTP/1.1
Accept: application/vnd.interoperability.participants+json;version=1.1
Date: Tue 12 Oct 2021 10:13:24 GMT
FSPIOP-Source: dfspb
FSPIOP-Destination: Switch

Example 3 - Association of a CONSENT identifier to an Auth Service

POST /participants/CONSENT/123456789 HTTP/1.1
Accept: application/vnd.interoperability.participants+json;version=1.1
Content-Length: 50
Content-Type: application/vnd.interoperability.participants+json;version=1.1
Date: Tue 12 Oct 2021 10:12:24 GMT
FSPIOP-Source: CentralAuthService
FSPIOP-Destination: Switch
{
    "fspId": "CentralAuthService"
}

Example 4 - Lookup of a consent's owner based on a consentId

GET /participants/CONSENT/123456789 HTTP/1.1
Accept: application/vnd.interoperability.participants+json;version=1.1
Date: Tue 12 Oct 2021 10:12:24 GMT
FSPIOP-Source: pispa

3. Proposed Solution Options

Alternatively to the solution described in [#requested-behaviour](Requested Behaviour), the Third Party API
could maintain it's own version to the PartyIdType field, with the extended fields included.

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

Modifications to the /authorizations resource to support the PISP use case.

1.1 Change Request Information

| Requested By | Michael Richards |
| Change Request Status | In review ☒ / Approved ☐ / Rejected ☐ |
| Approved/Rejected Date | |

1.2 Document Version Information

2. Problem Description

2.1 Background

At present, the /authorizations resource only has a GET command associated with it. The information about the transaction for which authorization is required is passed in the query string in a rudimentary form, specifying only the amount and currency of the transaction. This is appropriate for the use case originally considered, which is authorizing a transfer at an ATM or POS terminal.

The work currently being undertaken to extend the API to support the PISP use case also requires use of the /authorizations resource. In this use case, it is used to allow the PISP application to obtain authorization for a transfer from the account holder. In the PISP use case, however, it is important that more information should be provided, so that the PISP application can provide sufficient information the PISP application should possess additional information about the transfer (e.g. about the fees to be charged,) so that it can enable the customer to make an informed choice about whether or not to proceed with the transfer.

2.2 Current Behaviour

Explain how the API currently behaves.

The /authorizations resource currently only supports a GET command, where supporting information is passed to the recipient in the query string.

2.3 Requested Behaviour

The /authorizations request should be extended to support sufficient information to allow the recipient to understand all the characteristics of the transfer for which authorization is being requested, so that it can decide how to represent the transfer to the customer whose authorization is being sought. This information should also include the current balance of the account which will be debited as a consequence of authorization being obtained.

3. Proposed Solution Options

We could add a POST command to the resource. This command would take a Transaction object as its payload, together with an optional accountBalance field of type Money. The existing PUT could continue to be used as the response.

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

1.2 Document Version Information

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.

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

Additional data is required for some existing data items in order to meet the particular requirements of individual implementations.

• When registrations are made using the /participants resource, DFSPs need to be able to specify the transaction account to which transfers to the new ID will be credited, and in the case of Merchant IDs the Tax Identification Number (TIN) for the merchant. This requires the addition of an ExtensionList field to the PartyIdInfo data structure.

• When information is returned from a call to the /parties resource, and when it is included in a request sent to the /quotes resource, additional information about the party needs to be included. This includes identifying what TransactionInitiatorType the party belongs to, and whether the party's account is a bank account or a wallet. This requires the addition of an optional ExtensionList field to the Party data structure.

1.1 Change Request Information

| Requested By | Michael Richards, ModusBox |
| Change Request Status | In review ☒ / Approved ☐ / Rejected ☐ |
| Approved/Rejected Date | |

1.2 Document Version Information

2. Problem Description

The implementation of the Open API in TIPS has revealed the need for additional data to be passed between participants in the system. The normal pattern for adding implementation-specific details to calls in the Open API is via the use of an ExtensionList field(see Open API Specification, Section 7.4.4) However, some data items as defined in the specification do not contain ExtensionList fields, and these data items cannot therefore have additional information added.

2.1 Background

Specific instances where data structures in the existing Open API definition need to have specialised data associated with them are:

• When registrations are made using the /participants resource, DFSPs need to be able to specify the transaction account to which transfers to the new ID will be credited, and in the case of Merchant IDs the Tax Identification Number (TIN) for the merchant. This requires the addition of an ExtensionList field to the PartyIdInfo data structure.

• When information is returned from a call to the /parties resource, and when it is included in a request sent to the /quotes resource, additional information about the party needs to be included. This includes identifying what TransactionInitiatorType the party belongs to, and whether the party's account is a bank account or a wallet. This requires the addition of an optional ExtensionList field to the Party data structure.

2.2 Current Behaviour

It is not possible to add implementation-specific information to the Party data structure or the PartyIdInfo data structure.

2.3 Requested Behaviour

Allow the addition of implementation-specific information to the Party data structure and the PartyIdInfo data structure.

3. Proposed Solution Options

Add an Extensionlist data structure to the Party data structure and the PartyIdInfo data structure.

Transactions that cross-borders often have stringent data collection requirements to comply with KYC regulations etc.

One way this might be accommodated is the addition of a new data element in the quote request and response (callback) called Participants.

This would be an ordered list that is added to by each participant and contains data about intermediary and the transfer that it will perform as part of the end-to-end transaction.

E.g:

• Participants:
  • Participant:
    • FspIp: blue-mobile
    • TransferCurrency: USD
    • Fee: USD 5
    • Commission: USD 0
    • Data Requirements: [ full name, national identity number ]
    • Data Encryption Key: gd6g86qwlhjv7tdxkuywef8gfc2welv
  • Participant:
    • FspIp: fxp
    • TransferCurrency: XOF
    • Fee: XOF 5
    • Commission: XOF 0
    • Data Requirements: [ full name, physical address ]
    • Data Encryption Key: 70qw6g86qwlhjv7tdxkuywef8gfc2wel

Data from the payee FSP is encrypted first with the requestor's key and then the payer's key and included in the quote response. It is decrypted by the payer (although still encrypted under the requestor's key) and included in the transfer.

Data from the payer FSP is included in the transfer encrypted under the requestor's key.

Participants can reject the quote if they are unable to provide the data requested or they can reject the transfer if the data provided is insufficient.

This data model needs to be explored more thoroughly including the impact on the message signatures. It's assumed that in a multi-hop transaction each hop will have a different JWS.

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

This section contains basic information regarding the change request.

1.1 Change Request Information

| Requested By | Michael Richards, ModusBox |
| Change Request Status | In review ☒ / Approved ☐ / Rejected ☐ |
| Approved/Rejected Date | |

1.2 Document Version Information

2. Problem Description

2.1 Background

There have been a number of requests in the past to extend the Mojaloop system to support messages in ISO 20022 format. This requirement has now become urgent, to meet the needs of the proposed implementation in Rwanda. This change request discusses the changes that might be required to meet this need.

I want to look at the FSPIOP API from two slightly different perspectives. The first perspective is the endpoints that it supports; and, in particular, the endpoints that relate to the progress of a transfer. As we know, these fall into three phases: discovery, agreement and the transfer itself. Each of those phases has two messages associated with it: the original request, and a response (which can be either positive or negative.) Mojaloop works via requests and responses on the same resource type, whereas ISO 20022 typically has two different message definitions, one for the request and the other for the response. Otherwise, however, initial analysis of the ISO 20022 message catalogues suggests that There are ISO 20022 messages to support the following resources:

• /parties (query and callback)
• /participants (creation and callback)
• /quotes (creation and callback)
• /transfers (creation and callback)
• /transferRequests (creation and callback)
• /transactions (query and callback)

ISO20022 does not, in general, have a different syntax for bulk messages. The simple transfer is simply a specialisation of a bulk transfer. We may therefore omit the /bulkquotes and /bulktransfers resources. The only Mojaloop resource which is not covered by an obvious ISO 20022 message type is the /authorizations resource. We defer consideration of this for the initial implementation (actually, I think we defer it to a PISP discussion).

Our conclusion is that the orchestration aspect of the current Mojaloop API can be retained in an ISO 20022 context.

The second perspective is that of the content of the messages. It seems to me that there are two questions we need to answer here. The first is: will the content of the ISO 20022 message catalogue provide the content which the switch processes need to perform their functions? My answer to that is, broadly speaking, yes. I say "broadly speaking" to leave open the possibility that a scheme might want to evaluate rules based on information about the proposed transfer that an ISO message might not be able to contain. This seems to me, however, to be a relatively remote possibility.

The second question is: do the current Mojaloop messages contain information which cannot be encoded in the existing ISO 20022 structures? There are some cases where this is true: for instance, the complicated structure which is used to describe a transaction type is not directly representable in ISO. There are, however, other ways of representing a transaction's type. The most obvious problem, however, is the condition and fulfilment. There is no field in the existing ISO 20022 structures which represents these fields, and they are essential to the correct functioning of a Mojaloop system. However, ISO messages generally have a structure (the Supplementary Data field) which can be used to represent any information which cannot be represented in the existing ISO data structures; so my conclusion is that we can represent all the data we need to in the ISO structures.

Since this is the case, I propose that we should look at how to add support for ISO 20022 messages to the Mojaloop system. I think that the easiest way of doing this would be to set up a new API to manage interactions with the switch using ISO 20022, but would like to propose the question for discussion.

2.2 Current Behaviour

There is no current support for ISO 20022 messages

2.3 Requested Behaviour

N/A

There are a number of API changes proposed as a result of the work on cross-currency and cross-border. Let's use this thread to co-ordinate discussion around these.

If necessary we can setup a conference call to discuss in more detail, the details will be posted here. If you want to stay in the loop "Subscribe" to this thread (look for the button on the right).

The current API defines a flow for discovery of the payee and payee details using a combination of the /parties and /participants API.

Ultimately this results in the sending DFSP getting a Party response which provides details of the payee. It is anticipated that the sending DFSP will use this information (such as Party.name) to render appropriate options to the sender for making a payment.

It is not currently possible to determine the currency of the payee's account from the Party data model.

Page 80 of the API specification suggests that the API support a query string for the purposes of filtering:

This HTTP request should support a query string (see Section 3.1.3 for more information regarding URI syntax) for filtering of currency. To use filtering of currency, the HTTP request GET /participants//?currency=XYZ should be used, where XYZ is the requested currency.

However this only allows the sender to filter out payees that would require a cross-currency transfer, it doesn't allow the sender to determine the currency of the payee's account if the sender is willing to make a cross-currency transfer.

Privacy

The design of a mechanism for the discovery of accounts, and routing of quotes and payments to those accounts, needs to be done in a privacy preserving manner. It should not be possible during the lookup flow for a sender to discover more information about the receiver than the receiver is prepared to share or than is needed to make the payment.

If the payee has multiple accounts in different currencies that it can receive payments into then these should be indexed in the lookup using opaque identifiers.

Proposal

The following updates to the API would facilitate cross-currency quotes and transfers and the necessary lookups to facilitate these.

Update Party

The Party data model should be updated to include a new addresses data element:
(Some existing properties excluded to save space)

Add AddressList and Address data types

The AddressList data model is defined as:

The Address data model is defined as:

The Address data type is a variable length string with a maximum size of 1023 characters and consists of:

• Alphanumeric characters, upper or lower case. (Addresses are case-sensitive so that they can contain data encoded in formats such as base64url.)
• Underscore (_)
• Tilde (~)
• Hyphen (-)
• Period (.)
  Addresses MUST NOT end in a period (.) character

An entity providing accounts to parties (i.e. a participant) can provide any value for an Address that is routable to that entity. It does not need to provide an address that makes the account identifiable outside the entity's domain. i.e. This is an address not an identifier

For example, a participant (Blue DFSP) that controls the address space moja.blue might allocate a random UUID to the account and return the value:

{
  "address" : "moja.blue.8f027046-b82a-4fa9-838b-70210fcf8137",
  "currency" : "ZAR" 
}

This address is routable to Blue DFSP because it uses the prefix moja.blue

Blue DFSP may also simply use their own address if that is sufficient (in combination with the remainder of the PartyIdInfo) to uniquely identify the payee and the destination account.

{
  "address" : "moja.blue",
  "currency" : "ZAR" 
}

This address is also routable to Blue DFSP because it uses the prefix moja.blue

IMPORTANT: The policy for defining addresses and the life-cycle of these is at the discretion of the address space owner (the payee DFSP in this case)

Use the address in the Party.PartyIdInfo.PartySubIdOrType to assist in routing

If a sending DFSP has an address for the payee that they wish to include in a quote request to assist intermediaries in routing the quote they should include this in the Party.PartyIdInfo.PartySubIdOrType data element.

Intermediaries that need to route a quote request via FX providers or Cross-network providers/gateways will determine the next hop of the quote request by consulting their internal routing tables using the address as the lookup value.

By @adrianhopebailie , PR: #22

Per discussion in the DA and on the mid-PI review this is a consolidated proposal of all changes in the issue list.

It includes fixes for:

1. alignment with ILPv4
2. better cryptographic binding
3. extensions to facilitate cross-currency
4. extensions to facilitate data collection for cross-border

If #13 is implemented to align the API with ILPv4 it will be necessary to define a data element in the callback of the /quote API to carry data sent by the payee that it expects to be unchanged and returned in the subsequent /transfer API call. (Currently payee systems will use the encoded ILP packet)

This field will be used by the payee to generate the fulfilment and condition so it must be returned unchanged to the payee in order to fulfil the transfer. To satisfy this requirement it is recommended that the field is base64 encoded.

The content of the field is at the discretion of the payee and MAY contain data (such as the quote and transaction details) that it can use to ensure the fulfilment and condition are cryptographically bound to the transaction.

Describe the bug
The API Definition document does not clearly state what should happen if a Payer or Payer FSP rejects a quote. The process is described in the Generic Transaction Patterns document, Section 4.1.4 step 15:

The Payer is assumed to approve the transaction in this sequence. If the Payer would reject the transaction at this stage, no response regarding the rejection is sent to the Payee FSP. The created quote at the Payee FSP should have an expiry time, at which time it is automatically deleted.

The same as above should be described in the API Definition document.

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

In order to support the extension of Mojaloop to allow PISPs (Payment Initiation Service Providers, like GooglePay) to join Mojaloop schemes, the Open API will need to provide ways to document the negotiations between PISPs and the DFSPs who own the accounts with which the PISP will be authorised to interact. This change request describes the interactions required and proposes a way of supporting them. It is based on design discussions in the PISP development team (Lewis Daly, JJ Geewax, Adrian Hope-Baillie, Michael Richards.)

1.1 Change Request Information

| Requested By | Michael Richards, ModusBox |
| Change Request Status | In review ☒ / Approved ☐ / Rejected ☐ |
| Approved/Rejected Date | |

1.0 Document Version Information

2. Problem Description

2.1 Background

In order for a PISP to be authorised to access a customer's account with an account-holding DFSP, a number of actions need to be completed:

1. The PISP needs to find out which DFSPs in a given Mojaloop scheme support PISP access.
2. The PISP needs to find out which accounts a customer holds with a given DFSP.
3. The PISP needs to find out from the customer which account(s) the customer wants to give the PISP access to, and what kind of access that should be (examples might be: transfer funds from my account, see my account balance.)
4. The PISP needs to inform the account holding DFSP what kind of access is required, and which account(s) access is required for.
5. The account holding DFSP needs to satisfy itself that its customer has approved the PISP's request for access to the customer's account.
6. The account holding DFSP needs to inform the PISP that its request has been approved (or, indeed, rejected.)

This change request is intended to address the requirements described in items 4, 5 and 6.

To meet the requirements of item 4, the following questions need to be decided:

1. What should the form of an access request be?
2. What kinds of access should be supported?
3. Should it be possible to ask for more than one form of access to an account in the same request?
4. Should it be possible to ask for access to more than one account in the same request?
5. How should the request be made?
6. How can the DFSP to whom the request is addressed be confident that the PISP who makes the request is authorised to make it, and what is the extent of the authorisation?
7. Should the DFSP respond immediately to say that the request has been received and is being processed, or should it delay its response until the request has been accepted or rejected by all parties?

To meet the requirements of item 5, the following questions need to be decided:

1. How should authorisation be requested?
2. How should the response to the authorisation be returned?
3. How can the DFSP be confident that the response really did come from the customer?

To meet the requirements of item 6, the following questions need to be decided:

1. Should the result of the access request be a response to the origiinal request or a separate message?
2. What information needs to be included in the response?
3. The PISP should use a unique identifier to access the customer's account. Should this be given a new identifier type?
4. Who should create the identifier and how should it be communicated to the other party?
5. Does the identifier need to be stored in the ALS, given that it will already be known to both parties?

2.2 Current Behaviour

There is no current behaviour. This is an addition to the API

2.3 Requested Behaviour

The current state of the design is given here:

3. Proposed Solution Options

We are thinking in terms of two additional API resources:

1. An consentAuthorizations resource to be used by the PISP to ask the DFSP to give the PISP access to the customer's account. Assent to this by the DFSP means that the association process has been initiated.
2. A consents resource to be used by the DFSP to inform the PISP of the consent(s) that have been granted or refused for the account(s) requested.

More detail will be added about content.

TIPS needs to be able to analyse use cases by recipient type as well as by initiator type: for instance, to be able to distinguish readilybetween P2P, P2B and P2G use cases. We therefore propose to add a field to the TransactionType object (spec Section 7.4.18.)

The field should be called recipientType. It should be optional to support backwards compatibility. It should have the same type as the initiatorType field in the current data structure.

Open API for FSP Interoperability - Change Request

Table of Contents

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

1. Preface

This section contains basic information regarding the change request.

1.1 Change Request Information

2. Problem Description

2.1 Background

The OpenApi definitions of v1.0 and v1.1 of the FSPIOP Specification has no standard naming scheme for operationID's. OperationID's are important for some framworks when routing paths. Some microservices deviate from the hosted definition

2.2 Current Behaviour

Current definition has no standardized naming scheme for operation Id's

Example

https://github.com/mojaloop/mojaloop-specification/blob/master/fspiop-api/documents/v1.1-document-set/fspiop-v1.1-openapi3.yaml#L111

    put:
      description: The callback `PUT /participants/{Type}/{ID}` (or `PUT /participants/{Type}/{ID}/{SubId}`) is used to inform the client of a successful result of the lookup, creation, or deletion of the FSP information related to the Party. If the FSP information is deleted, the fspId element should be empty; otherwise the element should include the FSP information for the Party.
      summary: Return participant information
      tags:
        - participants
      operationId: ParticipantsByTypeAndID3
                                   ^ No HTTP verb. Not very descriptive

https://github.com/mojaloop/mojaloop-specification/blob/master/fspiop-api/documents/v1.1-document-set/fspiop-v1.1-openapi3.yaml#L237

    post:
      description: The HTTP request `POST /participants/{Type}/{ID}` (or `POST /participants/{Type}/{ID}/{SubId}`) is used to create information in the server regarding the provided identity, defined by `{Type}`, `{ID}`, and optionally `{SubId}` (for example, `POST /participants/MSISDN/123456789` or `POST /participants/BUSINESS/shoecompany/employee1`). An ExtensionList element has been added to this reqeust in version v1.1
      summary: Create participant information
      tags:
        - participants
      operationId: ParticipantsSubIdByTypeAndIDPost
                              ^ Example of a descriptive name. Describes path. Uses HTTP verb. 

2.3 Requested Behaviour

Operation Id's are updated.

3. Proposed Solution Options

Decide on naming scheme and update documents.

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

This section contains basic information regarding the change request.

1.1 Change Request Information

1.2 Document Version Information

2. Problem Description

2.1 Background

The current API defines a mechanism by which a condition and fulfilment are exchanged between the payer and payee DFSP per the Interledger protocol.

The purpose of this condition and fulfilment (as defined in ILP) is to give the payer FSP assurance that the transaction was received and accepted by the payee FSP (only the receiving FSP can produce the fulfilment). This requires that the payer FSP can be certain the condition they receive in the quote response was provided by the payee FSP and not an intermediary.

The Mojaloop API documents propose that a payee FSP use the content of the transaction as input into the generation of the condition and fulfilment, thereby cryptographically binding the condition to the transaction.

However, the mechanism by which this is done is using a SHA256 HMAC over the transaction object using a secret known only to the payee FSP. Therefor, it is impossible, without revealing the secret, for any party to validate that the fulfilment is derived from the transaction.

The purpose of using a SHA-256 hash of the fulfilment as the condition is that it is very simple to validate and it is a fair expectation that all implementors are capable of performing a SHA256 (as opposed to a more complex signing algorithm such as RSA).

2.2 Current Behaviour

The payee FSP, on receiving a quote request, constructs a transaction object that specifies details of the payer, the payee and the amounts they will send and receive respectively.

The is transaction object represents the "contract" between the payer and payee FSPs. It does not currently include details of any intermediary transfers required to execute the contract.

The payee FSP derives a fulfilment using a SHA256 HMAC of the transaction object and a secret known only to the payee FSP. The FSP then derives a condition by performing a SHA256 hash of the fulfilment. The condition is returned to the payer FSP in the quote response.

The payer FSP passes the condition in the request to prepare the transfer that it sends to the switch. The switch will only clear the transfer if the response from the payee FSP contains a fulfilment that hashes to exactly the same value.

2.3 Requested Behaviour

A desired property of the condition and fulfilment is that they are cryptographically bound to the "terms of the contract" (i.e. the transaction object) however this is:
a) Not a property that is required for the Interledger protocol
b) Not easily verifiable because the fulfilment can only be validated as being derived from the transaction if the payee FSP secret is revealed.

For multi-hop transactions it is important that a simple end-to-end condition and fulfilment are present however it would be best if the cryptographic binding of the transfer fulfilment to the transaction at each hop was done using a different condition and fulfilment that is specific to each hop (transfer).

• Each participant in a transaction that will be the recipient of a transfer should generate a condition as part of the quote cycle.
• The fulfilment of that condition should be provided by that participant when they fulfil the subsequent transfer.
• The clearing system should validate the transfer specific fulfilment when clearing a transfer
• It should be possible to verify that the transfer specific fulfilment is cryptographically bound to the "contract" (either the transaction object or the transfer details encoded in some deterministic way).

3. Proposed Solution Options

1. Introduce a Transfer Signature

The transfer signature is a a value provided by the payee FSP in a transfer response as part of the fulfilment callback. It is provided alongside the ILP fulfilment.

The fingerprint of the public key that will be used to sign the transfer is sent by the payee FSP in the quote response callback and also in the transfer prepare.

The clearing system (switch) will only accept prepared transfers if it recognises the public key fingerprint as belonging to the payee participant. It will only clear the transfer if the fulfil callback contains a valid signature over the transfer using that key.

2. Simplify the ILP Condition generation

Change the instructions in the API documentation that instructs payees on how to generate the ILP fulfilment. This does not need to be derived from the transaction details.

3. Provide a means to validate that the ILP Condition is from the payee FSP

This requires some investigation but will likely require that the condition is signed by the payee FSP and the signature returned in the quote response callback along with the condition.

The verification of ownership of the signing key is left to still be determined.

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

This change request is to support extended KYC information for parties.

1.1 Change Request Information

1.2 Document Version Information

2. Problem Description

2.1 Background

Non-national Mojaloop schemes such as Mowali are regulated like a DFSP. In particular, they need to be able to comply with KYC regulations relating to the parties involved in the transfers they facilitate. Schemes do not, however, undertake any KYC activity on their own account: the Mojaloop principle is that information relating to individual account holders is owned by the scheme's participants, not by the scheme itself.

Since this is the case, a scheme which needs to comply with KYC regulation about the transfers it facilitates will need to obtain that information from the DFSPs who are the parties to the transfer. There is already an object in the specification which contains some information about a party to the transfer. This is the PartyPersonalInfo object (Section 7.4.14 of v1.1 of the FSPIOP API definition.) This object forms part of the information which is returned by the payee DFSP in the PUT /parties response, and also forms part of the payer's quote request (POST /quotes,) which allows personal information for the payer and the payee to be included.

The PartyPersonalInfo object currently supports two items of data: the full name of the party and their date of birth. Standard KYC requirements, however, frequently require additional items of information to ensure that a customer is correctly identified. This change request proposes extensions to the PartyPersonalInfo object to support these requirements.

2.2 Current Behaviour

The PartyPersonalInfo object currently supports two items of data: the full name of the party and their date of birth.

2.3 Requested Behaviour

The PartyPersonalInfo object should be extended to include an opaque data object which individual schemes can use to hold KYC information as defined by their requirements. The API itself will not mandate the content of this data object, but individual schemes will be free to validate its contents, e.g. by the applicaiton of rules.

3. Proposed Solution Options

The proposed structure for the PartyPersonalInfo object is given below:

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

This section contains basic information regarding the change request.

1.1 Change Request Information

| Requested By | Michael Richards, ModusBox |
| Change Request Status | In review ☒ / Approved ☐ / Rejected ☐ |
| Approved/Rejected Date | |

1.2 Document Version Information

2. Problem Description

2.1 Background

This change request contains information which was originally proposed as part of the Consolidated Change Request prepared by Adrian Hope-Baillie to cover the various changes associated with cross-network and cross-currency functionality.

As part of the linking process by which PISPs and DFSPs agree that a PISP can make debit requests against a DFSP customer's account, the PISP needs to obtain information about the accounts which the DFSP associates with the customer's identifier. This information is the same as the information proposed as part of the consolidated change request, and it is therefore pulled from that request and presented (with some modification) as the content of this change request, so that it can be independently proposed and approved by the CCB

2.2 Current Behaviour

Explain how the API currently behaves.

The information currently returned about a party via the API does not contain any information about either the accounts to which the identifier has access or the currencies in which those acocunts are denominated.

2.3 Requested Behaviour

The Party data model is updated to include a new accounts data element:

Add AccountList and Account data types

The AccountList data model is defined as:

The Account data model is defined as:

The AccountAddress data type is a variable length string with a maximum size
of 1023 characters and consists of:

• Alphanumeric characters, upper or lower case. (Addresses are case-sensitive so
  that they can contain data encoded in formats such as base64url.)
• Underscore (_)
• Tilde (~)
• Hyphen (-)
• Period (.) Addresses MUST NOT end in a period (.) character

An entity providing accounts to parties (i.e. a participant) can provide any
value for an AccountAddress that is routable to that entity. It does not
need to provide an address that makes the account identifiable outside the
entity's domain. i.e. This is an address not an identifier

For example, a participant (Blue DFSP) that has been allocated the address space
moja.blue might allocate a random UUID to the account and return the value:

{
  "address": "moja.blue.8f027046-b82a-4fa9-838b-70210fcf8137",
  "currency": "ZAR"
}

This address is routable to Blue DFSP because it uses the prefix moja.blue

Blue DFSP may also simply use their own address if that is sufficient (in
combination with the remainder of the PartyIdInfo) to uniquely identify the
payee and the destination account.

{
  "address": "moja.blue",
  "currency": "ZAR"
}

This address is also routable to Blue DFSP because it uses the prefix
moja.blue

IMPORTANT: The policy for defining addresses and the life-cycle of these is
at the discretion of the address space owner (the payee DFSP in this case)

Describe the bug
The sequence diagrams that are based on plantuml files are not available on the markdown version of the docs such as the API Definition.

For example figure-50 on the API Definition v1.1 markdown file: https://github.com/mojaloop/mojaloop-specification/blob/master/fspiop-api/documents/API-Definition_v1.1.1.md#figure-50

Notes: Since gitbooks has been chosen for rendering documentation, the scripts we have automatically generate svgs for plantuml diagrams when we create a release and then publish to git books. This is part of the CI/CD process.

There are two types of diagrams in the current docs, sequence diagrams that use plantuml and then other hand drawn diagrams, to represent state transitions etc (that are not plantuml); Both types of diagrams show fine on gitbooks: https://docs.mojaloop.io/api/fspiop/v1.1/api-definition.html#figure-50

This may technically not be a bug but more of an experience issue (as it is by design), but logging this to discuss ways to enhance the experience around plain markdown files

Priority & Severity:
Priority: Low
Severity: Low

To Reproduce
Steps to reproduce the behavior:

1. Go to figure-50 on the API Definition v1.1 markdown file: https://github.com/mojaloop/mojaloop-specification/blob/master/fspiop-api/documents/API-Definition_v1.1.1.md#figure-50
2. There is no svg available (by design)

Expected behavior
To be decided - should there be an SVG or a diagram available even on the markdown file (discuss)

Screenshots
Not. a screenshot, but this is how it shows up currently (on the md files)

figure 50
{% uml src="assets/diagrams/sequence/figure50.plantuml" %} {% enduml %}

For consistency, simplicity, and to take advantage of branding, update the name of the API to "Mojaloop API." Implement using a global search and replace for text. There will also likely be some additional effort to replace in tables and diagrams.

I suggest that we should add the following wording to ensure that the requirement for padding is clear.

In section 3 (the API Signature Definition) of the Signature document:
"For the avoidance of doubt: whenever reference is made to Base64URL encoding in the signature definition or in the examples included in this document, then the encoding MUST include appropriate pad characters as specified in Section 3.2 of RFC 4648 (https://tools.ietf.org/html/rfc4648#section-3.2)"

In section 7.2.17 (the definition of a BinaryString) of the Open API specification:
"For the avoidance of doubt: the Base64URL encoding for a BinaryString MUST include appropriate pad characters as specified in Section 3.2 of RFC 4648 (https://tools.ietf.org/html/rfc4648#section-3.2)"

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

This section contains basic information regarding the change request.

1.1 Change Request Information

| Requested By | Sam Kummary, ModusBox |
| Change Request Status | In review ☒ / Approved ☐ / Rejected ☐ |
| Approved/Rejected Date | |

1.2 Document Version Information

2. Problem Description

2.1 Background

The TransferState enumeration defined in Section 7.5.13 of the API Definition v1.0 has these four values: RECEIVED, RESERVED, COMMITTED, ABORTED (Section 6.7.5 gives the possible states of a transfer). These states are fine to indicate the status of a transfer on a single FSP (or ledger), however the current issue is regarding the usage of the "ABORTED" state in a PUT /transfers/{ID} call described in Section 6.7.3.1 (corresponding to an initial POST /transfers call).

2.2 Current Behaviour

As part of fulfilling a prepared transfer (done via POST /transfers) using PUT /transfers/{ID} endpoint, it is possible to send the 'transferState' as ABORTED because its a valid enumeration value. Its possible for FSPs to interpret this as a valid option to abort transfers instead of using the PUT /transfers/{ID}/error endpoint.

The current Switch implementation caters for both of these options (ABORTED transferState sent in a PUT /transfers call or using a PUT /transfers/{ID}/error). The former doesn't have scope to add any additional information regarding the error or abort request, whereas the call on /error endpoint does have a field that can be used (along with error code).

After discussion with the CCB, the understanding was that the error endpoint (/transfers/{ID}/error) needs to be used by an FSP in case a transfer needs to be aborted and not use the PUT /transfers/{ID} call with an "ABORTED" value in the transferState field.

Example:

1. A Payer FSP makes a POST /transfers call to make a transfer request

{
  "transferId": "b8114fc7-56b4-4929-8943-5877c73dfcec",
  "payerFsp": "payerfsp",
  "payeeFsp": "payeefsp",
  "amount": {
    "amount": "1.11",
    "currency": "USD"
  },
  "expiration": "2020-02-11T14:18:27.921Z",
  "ilpPacket": "AQAAAAAAAADIEHByaXZhdGUucGF5ZWVmc3CCAiB7InRyYW5zYWN0aW9uSWQiOiIyZGY3NzRlMi1mMWRiLTRmZjctYTQ5NS0yZGRkMzdhZjdjMmMiLCJxdW90ZUlkIjoiMDNhNjA1NTAtNmYyZi00NTU2LThlMDQtMDcwM2UzOWI4N2ZmIiwicGF5ZWUiOnsicGFydHlJZEluZm8iOnsicGFydHlJZFR5cGUiOiJNU0lTRE4iLCJwYXJ0eUlkZW50aWZpZXIiOiIyNzcxMzgwMzkxMyIsImZzcElkIjoicGF5ZWVmc3AifSwicGVyc29uYWxJbmZvIjp7ImNvbXBsZXhOYW1lIjp7fX19LCJwYXllciI6eyJwYXJ0eUlkSW5mbyI6eyJwYXJ0eUlkVHlwZSI6Ik1TSVNETiIsInBhcnR5SWRlbnRpZmllciI6IjI3NzEzODAzOTExIiwiZnNwSWQiOiJwYXllcmZzcCJ9LCJwZXJzb25hbEluZm8iOnsiY29tcGxleE5hbWUiOnt9fX0sImFtb3VudCI6eyJjdXJyZW5jeSI6IlVTRCIsImFtb3VudCI6IjIwMCJ9LCJ0cmFuc2FjdGlvblR5cGUiOnsic2NlbmFyaW8iOiJERVBPU0lUIiwic3ViU2NlbmFyaW8iOiJERVBPU0lUIiwiaW5pdGlhdG9yIjoiUEFZRVIiLCJpbml0aWF0b3JUeXBlIjoiQ09OU1VNRVIiLCJyZWZ1bmRJbmZvIjp7fX19",
  "condition": "HOr22-H3AfTDHrSkPjJtVPRdKouuMkDXTR4ejlQa8Ks"
}

2. Following a POST /transfers call by the Payer FSP, a Payee FSP responds with a PUT /transfers/{ID} with an ABORTED transferState (other fields are optional)

Call on:

PUT /transfers/{b8114fc7-56b4-4929-8943-5877c73dfcec}

{
    "completedTimestamp": "2020-02-11T14:08:28.417Z",
    "transferState": "ABORTED"
}

3. Since this (ABORTED) is a valid state, the Switch is having to process it and consider the transfer as aborted. With the change suggested, a PUT /transfers/{ID} call that looks like the above will fail Schema validation or will receive an error callback

2.3 Requested Behaviour

There is no request for a change in the behavior of the API as such, but to add more description to indicate the behaviour described above explicitly - to not use ABORTED state in PUT /transfers/{ID} calls and only use a PUT call on the error endpoint if a transfer needs to be aborted.

This will have significant implication to the Switch implementation on the OSS side which will help simplify things.

3. Proposed Solution Options

Summarized in Section 2.3 above. Additional description offering clarity on this would be helpful for both FSPs and Switch/Hub implementers.

The current format (PDF) makes it very difficult to contribute incremental changes to the documents through pull requests.

Suggest using a text based format such as Markdown or HTML and implement a publishing workflow in a CI to output these well-formatted artefacts.

Examples:

• Markdown (published as HTML) on https://github.com/interledger/rfcs
• HTML (using the ReSpec library) on https://github.com/w3c/payment-request
• XML (published as HTML/RFC text) on https://github.com/httpwg/http-core

Describe the bug
In Section 7.2.4.1 of the API specification, the definition of the regular expression to parse a variable of the Name type states: "all Unicode32 characters are allowed". In fact, accented and non-Roman characters are rejected by the example regular expression given in Listing 14.

To Reproduce
Steps to reproduce the behavior:

1. Go to https://regex101.com/
2. Paste the regular expression in Listing 14 into the REGULAR EXPRESSION box
3. Paste any text with accented characters into the TEST STRING box (e.g. "Côte d'Ivoire")
4. MATCH INFORMATION box displays "Your regular expression does not match the subject string."

Expected behavior
MATCH INFORMATION box displays:

Match 1

Full match | 0-13 | Côte d'Ivoire

Desktop (please complete the following information):

• Windows 10
• Chrome
• Version 80.0.3987.122 (Official Build) (64-bit)

Additional information:

Replace the regular expression in Listing 14 with:
^(?!\s*$)[(\p{L}|\p{Nd}) .,'-]{1,128}$
This uses the Unicode character groups for "any letter" and "any numeric digit"
Now the accented characters (and non-Roman scripts) are parsed correctly.

The CCB will develop and maintain an API Best practices document that will include common best practices (for all the ML family of APIs)

Template:
API.Best.Practices.docx

Notes:

1. Eg POST shouldn't contain any information in the URI (but should be in the body)
2. Adapt Word doc style guide for markdown format
3. Enumerations
4. Definitions

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

1.2 Document Version Information

2. Change Request

2. Change Request

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.