Change Request: PISP Extensions to the Open API
mjbrichards opened this issue · comments
Open API for FSP Interoperability - Change Request
Table of Contents
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
| Version | Date | Author | Change Description |
|---|---|---|---|
| 1.0 | 2020-05-19 | Michael Richards | Initial version. |
2. Problem Description
___ The extension of the Mojaloop product to accommodate PISPs (Payment Initiation Service Providers) requires new API resources, as well as some changes to existing resources. The question is whether these should be accommodated using the existing Open API specification, or whether it would be better to accommodate the new resources in a different API, and perhaps include PISP-specific versions of the existing Open API calls which PISPs would be allowed to use in the same API.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:
- GET /parties, to return the accounts associated with the customer's identifier
- POST /consentRequests, to request permission to link with a customer's account(s)
- GET /consentRequests, to enquire after the statur of a linking request.
Inbound:
- PUT /parties, to receive information about a customer's accounts.
- PUT /consentRequests, to receive confirmation that a linking request has been accepted for processing or rejected.
- 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:
- GET /parties, to identify the DFSP of the payee
- POST /thirdPartyRequests, to request a payment (assuming different resource name from the current /transactionRequests)
- GET /thirdPartyRequests, ,to enquire after the status of a transaction request.
- PUT /authorizations, to respond with a customer's confirmation to go ahead with a transfer.
- GET /transfers, to enquire after the status of a transfer.
Inbound:
- PUT /parties, to return the DFSP who owns a payee account.
- PUT /thirdPartyRequests, to receive the status of a transfer request.
- POST /authorizations, to receive a request from a DFSP for customer consent to a proposed transfer.
- 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.
Would like to clarify the nomenclature for payment request as thirdPartyRequests.
Do we have an agreed conversion of who are primary parties (I think DFSP) in use of Mojaloop and other are third parties?
If so is that what drives the nomenclature POST /thirdPartyRequests, to request a payment (assuming different resource name from the current /transactionRequests).
Thanks for your comments, JM. To take them in reverse order: the idea of having a separate resource for use by PISPs is related to the problems with checking messages discussed in Issue 60. Having a separate resource for PISPs will simplify checking, since the check will not need to interrogate the body of the message to distinguish PISP from MRTP.
I refer to the PISPs as third parties because they do not hold any accounts themselves. As you say, this contrasts with the entities we have been referring to as DFSPs, who are the direct owners of transaciton accounts. I think that means that DFSP is in fact too wide a term (since PISPs are also providing digital financial services,) but we're so used to it now that there seemed no urgent reason to introduce a new acronym.
I'm leaning towards having a separate API for PISPs that is using the same architecture as the FSP Interoperability (using FSP API for simplicity from now on in this comment..) and sharing/reusing as much as possible from the FSP API. For example share current Section 3 (API Definition), 5.2 (Party addressing), and 6.2 (the /parties resource) from the existing API Definition document between the APIs.
The existing FSP API is focused on providing quotes and transfers between FSPs. For PISPs, the API will be more consumer oriented, for example the suggestion to be able to retrieve the balance from an account. The proposed changes to the /authorizations resource (#58) also adds consumer specific parts containing a quote intended for the consumer and a consent from the consumer instead of a simple OTP.
Additionally, some transfers initiated from a PISP will be internal within the FSP, for example when a customer and a merchant is located in the same FSP, meaning the FSP API will not even be used. This means no Mojaloop transfer will be executed, which in turn means that there is no possibility to use GET /transfers and PUT /transfers. How the transfer is performed in the FSP should in my view be agnostic for the PISP; it could be an FSP internal transfer, it could be a transfer using the FSP API (bilateral or through a Mojaloop switch), it could also be a transfer using some other unknown API. All that should matter is that the transfer is performed from the Payer to the Payee as requested by the consumer through the PISP.
It should also be easier to understand for implementers which parts that you need to add support for if there is clear division between PISPs and FSPs. For example, a PISP should not implement support for the FSP API's /quotes or the /transfers (as the transfer might not be a Mojaloop transfer) resources, and does not need to know anything about Interledger (Section 4) or quoting between FSPs (Section 5.1). Similarly, an FSP that does not want to support PISPs does not need to care about the PISP-specific resources.
I had a conversation with the architects on Mowali and TIPS to assess their views on the proposal. Broadly speaking, they were well disposed towards a separate API (or possibly two additional APIs.) The attached document summarises our discussion.
API alternatives for PISP.docx