We are excited to announce the release of version 1.1 of the Mojaloop Financial Services Provider Interoperability (FSPIOP) API Specification. Currently, there are three APIs in the Mojaloop ecosystem:
- Mojaloop FSP Interoperability API
- Settlements API
- Admin / Operations API
The FSPIOP API enables an interoperable financial transaction between a Payer account from one financial service provider (FSP) and a Payee account of a different FSP. The first version of the Mojaloop FSPIOP API was published in March 2018. Version 1.1 was approved on May 19th, 2020 by the Mojaloop Change Control Board (CCB) and adds a number of exciting changes.
The evolution of the FSPIOP API and key milestones.
Changes introduced in version 1.1
All Mojaloop change requests, bugs in the specification, solution proposals, specification document set, and other supporting documents are hosted in the specification repository on the Mojaloop GitHub site.
One of the versioning standards which the FSPIOP API follows is to increment the major version for any breaking change (ML FSPIOP API follows an x.y notation – major.minor versions). For this reason, any minor version upgrade must be backward compatible. Below are the changes that were approved and introduced as part of v1.1. The descriptions below, for the most part, represent the change requests in the specification repository itself.
Notifying payee FSP on successful commit in Switch
To simplify the support of two-phase commit process for transactions at the DFSP, where they first reserve funds, then commit them when confirmation is received, the PUT /transfers/<ID> has been extended to send an automatic notification to the Payee rather than have the Payee make an explicit GET /transfers/<ID> call.
in version 1.0, for a Payee FSP to ascertain that a transfer has been committed successfully in the Switch, the Payee FSP needed to send a GET /transfers/<ID> call to the Switch as detailed in API Definition document. This is essential functionality to check the status when any FSP, participating as either a Payer or Payee, is in doubt over the status of a transfer. For example, due to connectivity issues, the PUT notification from the Payee might not have been received by the Switch or Payer. So, before engaging in remedial actions an FSP should always check the status of the transfer in question using the GET endpoint.
For FSPs that prefer this mode of operation, the flow has been modified in version1.1 and the PUT /transfers/<ID> is extended to allow the Payee FSP to communicate to the Switch that the funds have been reserved. The Switch will then send a notification to the Payee FSP when the transfer is committed on the Switch, this introduces the PATCH /transfers/<ID>. The final COMMITTED or ABORTED state of the transfer will be shared with the Payee. The sequence diagram, 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
As payment schemes are adopting Mojaloop, they have found that minor additions to the discovery mechanisms (the Account Lookup Service and associated Oracles) allow better management of participating parties and improved customer user experiences where contextual data is needed to be returned and acted on by the customer. For example, when customers are making payments to utilities, the extension lists can be used to share when a payment is due or other account-specific data; and, where registrations are made using the /participants resource, FSPs need to be able to specify the transaction account to which transfers to the new ID will be credited.
This was easily facilitated through the addition of an optional ExtensionList field to the PartyIdInfo data structure.
Following this change, the data model has been updated to add an optional ExtensionList element to the PartyIdInfo complex type based on the Change Request.
For consistency, the data model for the POST /participants/<Type>/<ID> and POST /participants/<Type>/<ID>/<SubId> calls has been updated to include the optional ExtensionList element as well.
Clarified usage of the “ABORTED” transfer state in a PUT /transfers/<ID>
The intention of a Mojaloop switch is to facilitate payments wherever possible. However, there are times when the Payee organization must legitimately decline a transaction – resulting in an ABORTED transfer on the switch. When this happens, the Switch and the Payer FSP should also be given an appropriate reason for the transaction being declined so that the customer’s experience can be managed. The intention was for this to be facilitated through the PUT /transfers/<ID>/error endpoint. This change in version 1.1 starts the process of deprecating an alternative method to decline the transactions that did not record the reason appropriately. In the following paragraphs, we go into detail about the current behavior and the changes that are being introduced with v1.1
The TransferState enumeration defined in the API Definition v1.0 has these four values: RECEIVED, RESERVED, COMMITTED, and ABORTED. These indicate the status of a transfer within a single FSP (or ledger). However, the usage of the “ABORTED” state in a PUT /transfers/<ID> call (Fulfil request) corresponding to an initial POST /transfers (Prepare) call caused some confusion.
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. FSPs could 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/<ID> call or using a PUT /transfers/<ID>/error). The former does not 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).
It was decided by the CCB that the error endpoint (/transfers/<ID>/error) needs to be used by an FSP in case a transfer must be aborted and not to use the PUT /transfers/<ID> call with an “ABORTED” value in the ‘transferState’ field. This error should be addressed and corrected by FSPs, Schemes during testing phases.
Going 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 the 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, updated notes, and descriptions to improve clarity
Along with these changes, several additional bug fixes were implemented to correct issues such as inaccurately interpreted examples or typographical errors. Additionally, notes and descriptions have been updated to offer more clarity around common issues that have arisen over the course of the last two years.
The changes above can all be found in the tracking issue for version v1.1, which contains links to all individual issues included.
What’s next?
There are several changes in the pipeline for v2.0 of the ML FSPIOP API such as linking quotes and transfers in a simpler manner. This wasn’t included in version1.1 as it was a breaking change. Along with this, there are significant changes expected from other workstreams that are currently in progress.
Cross currency/network, PISP
Some very significant changes to the API that 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 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 but not included as part of the Mojaloop FSP Interoperability API.
For any questions or Change Requests regarding the API, please raise these on one of the CCB’s webinars or on Mojaloop’s GitHub.
Learn more about this project on our Mojaloop page or visit our Mojaloop Partner Program for information about how to get involved in the Mojaloop community, taking advantage of the Mojaloop Lab, or signing up for our courses.
