The Mojaloop Financial Services Provider Interoperability Specification (FSPIOP) API’s purpose is to enable interoperable financial transactions between a Payer (a payer of electronic funds in a payment transaction) located in one FSP (an entity that provides a digital financial service to an end user) and a Payee (a recipient of electronic funds in a payment transaction) located in another FSP. The API does not specify any front-end services between a Payer or Payee and its own FSP; all services defined in the API are between FSPs. FSPs are connected either (a) directly to each other or (b) by a Switch placed between the FSPs to route financial transactions to the correct FSP. The transfer of funds from a Payer to a Payee should be performed in near real-time. As soon as a financial transaction has been agreed to by both parties, it is deemed irrevocable. This means that a completed transaction cannot be reversed in the API. To reverse a transaction, a new negated refund transaction should be created from the Payee of the original transaction.
FSPIOP version1.1 has been approved on May 19th, 2020 by the Change Control Board (CCB). There are three APIs in the Mojaloop ecosystem as of now and this note is about the item#1 below:
- Mojaloop FSP Interoperability API
- Settlements API
- Admin / Operations API
Brief History
The first version of the Mojaloop FSPIOP API was published in March 2018. Before going in to the changes that are being introduced with version 1.1, below is a depiction of the evolution of the FSPIOP API with some key milestones.
Changes being introduced in version1.1
The Mojaloop Specification document set uses the repository mojaloop-specification on Mojalooop GitHub. All the Change Requests, bugs in the Specification, Solution proposals along with the Specification document set and supporting documents are hosted here.
One of the versioning standards the FSPIOP API follows is to increment the major version for any breaking change (ML FSPIOP API follows a x.y notation – major.minor versions). So, any minor version upgrade can be considered backward compatible.
After the initial release in March of 2018, changes were made along the way for editing, fixing typographical errors and formatting, which didn’t affect the content as such. Below are the changes that are approved and introduced as part of v1.1 that was approved and confirmed by the CCB on the 19th of May 2020. The description below, for the most part, is taken from the Change Requests in the mojaloop-specification repository itself.
-
Possibility to notify Payee FSP on successful commit in Switch
For a Payee FSP to ascertain that a transfer has been committed successfully in the Switch, the Payee FSP in version 1.0 needs to send a GET /transfers/<ID> to the Switch as detailed in API Definition document. 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>, a change was introduced in version1.1 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. The sequence diagram, the data model changes, and other details are discussed in the GitHub issue for this Change Request (Solution Proposal as well).
-
Adding ExtensionList fields to existing data structures
Additional data is required for some existing data items 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.
Following this change, the data model is updated to add an optional ExtensionList element to the PartyIdInfo complex type based on the Change Request: https://github.com/mojaloop/-specification/issues/30.
For consistency, the data model for the POST /participants// and POST /participants/// calls has been updated to include the optional ExtensionList element as well.
-
Clarify usage of “ABORTED” transfer state in a PUT /transfers/{ID}
The TransferState enumeration defined in the API Definition v1.0 has these four values: RECEIVED, RESERVED, COMMITTED, ABORTED. 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 (Fulfil request) corresponding to an initial POST /transfers (Prepare) call.
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 it is a valid enumeration value. It’s 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 for FSPIOP v1.0 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 a 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. This is an error that needs to be addressed and fixed by FSPs, Schemes during testing phases.
So moving forward, the Switch implementation for v1.1 will be refactored accordingly, to only accept calls on error endpoint (PUT /transfers/{ID}/error), to abort transfers and not accept ABORTED as a valid state in a PUT /transfers/{ID} Fulfil call. However, note that ABORTED state is still a valid enumeration value for a transfer’s State and can be used in callbacks corresponding to a GET /transfers/{ID} call.
-
Bug fixes and additional notes, description to improve clarity
Along with the above changes, there were additional bug fixes to fix issues such as inaccurately interpreted examples or typographical errors and in addition, text was added as notes and descriptions to offer more clarity to some of the issues that came up over the course of the last two years.
These changes are listed in the tracking issue here, which also have individual issue links that capture all the details: https://github.com/mojaloop/-specification/issues/52
Roadmap
There are several changes in the pipeline for 2.0 of the ML FSPIOP API such as linking quotes and transfers in a simpler manner, which wasn’t included in the version1.1 as it was a breaking change. Along with this, there are other significant changes expected from other streams currently in progress.
Cross currency/network, PISP
Some very significant changes to the API to support Cross network/currency and Third-party Payment initiation (to support Payment Initiation Service Providers (PISPs) ) are being worked on and once approved, are planned to be included in the version 2.0 of the Specification. In some cases, there may be new APIs proposed for Use Cases such as PISP, which will exist in the Mojaloop-ecosystem that will not be part of the Mojaloop FSP Interoperability API.
If you have any questions or Change Requests in mind, you can raise these with the CCB on one of the CCBs webinars or on GitHub here.
