Before reviewing, have there been any discussions regarding the suggestion about GSMA MM API in #60?

Thanks for the quick response @ehenrka . No they're not included in the initial draft, but have a follow-up meeting on this and I'll raise that there..

Thanks @sam - perhaps the label should be thirdparty-change-proposal?

Sure @lewisdaly - updated

Please find some initial comments below.

General comments

• My main question is why a lot of information that is related to the transfer between the Payer FSP and the Payee FSP needs to be shared to the PISP? The PISP should (at least in my mind) only care about presenting the end user quote for confirmation, and the result of the transaction to the end user. In the current design, it seems like private information like date of birth for both Payer and Payee is shared, internal IDs are shared, as well as internal FSP fees that are never meant to be shared to any party that is not involved in the actual transfer between the FSPs. Please explain to me what the PISP is supposed to do with that all that information? I'm not comfortable at all sending all this information to a PISP without proper understanding of why this information is required in the PISP. The PISP is not supposed to perform any kind of screening as far as I'm aware.
• As part of the project for designing the FSP Interoperability API, a glossary was developed which is located here https://github.com/mojaloop/mojaloop-specification/blob/master/documents/Glossary.md. The term that we decided to use for the financial service provider was FSP, not DFSP. If we should be consistent and follow that glossary, then please use FSP instead for the PISP API as well.
• There is a mix of American and British spelling, I would assume that we should use American spelling? This is a real problem in for example GET /authorizations/<ID>, where the correlation ID is called authorisationId. Another example is enquire vs inquire.
• If we should keep consistency with the FSP Interoperability API logical API service names, then please keep them relatively short. For example "Request permission to perform operations on one or more accounts owned by another participant." is more of a sentence than a logical name.
• Please do not allow unlimited number of elements (where Cardinality is set to for example 1..n), as an attacker may try to submit an extremely large number of elements, making the parser crash or cause a buffer overflow (however unlikely it might be in a scheme like this which is also using TLS). There is no purpose in allowing for example an unlimited number of scopes. Please decide a reasonable maximum number of elements. The same is also valid for any kind of string, this needs to have a limit in size.
• Please be consistent in naming, sometimes <ID> is used, in other instances <Id> is used.
• Many of the references to the FSP Interoperability API Definition in Section 6 seem to be off by 1, for example reference says 6.7.3.1 but where the actual Section number is 6.7.4.1.

Specific comments

Section 2.1.2: "This resource is an extension of the /authorizations resource described in Section 6.6 of Ref. 1 above"

• I don't understand the extension part here, to me it seems like a replacement? How should the FSP be able to support both as they have the same URI? The text also says that it is a new "A new POST service", this does not sound like an extension.

Section 2.1.2.1.1: "This resource will allow the DFSP which owns an account from which the PISP has requested that funds be transferred to ask for authorisation from the PISP that its user has in fact confirmed that the request should be honoured, and that they have done so via two-factor authentication on the registered device."

• This is a very long sentence that is really hard to understand.

Section 2.1.2.2.1: "When a PISP has shown the terms of a transfer to its customer and obtained the customer’s consent to or rejection of those terms, it will return this response to the DFSP."

• It is not a response that is returned, it is a callback.

Section 2.1.2.2.1: "The content of this callback will be as described in Section 6.6.3.1 of Ref. 1 above."

• Section 6.6.3.1 in FSP Interoperability API definition is not a callback, it is the GET request.
• Why is the logical API service name something other than in the FSP Interoperability API definition if it should be the same callback?

Section 2.1.3.1.1: "The <ID> in the URI should contain the requestId that was assigned to the request by the PISP when it originated it."

• "... when it originated it." there are too many "it"s here to make this sentence easy to understand..

Section 2.1.3.1.2: "callbackUri"

• The Type name is Url instead of Uri. Please be consistent.
• Is this meant to be the full URI? I would prefer to have the host name static to decrease the likelihood of a man-in-the-middle attack. If the host name is static, then what can be changed by an attacker is just the path.

Section 2.1.3.1.2: "The HTTP request POST /consentRequests is used to request a DFSP to grant access for the sending PISP to one or more accounts owned by a customer of the DFSP who uses the PISP."

• Please define what a "sending PISP" means.

Section 2.1.3.2 "This section describes the callbacks that are used by the server under the resource/consentRequests."

• Missing whitespace..

Section 2.1.3.2.1: "The PUT /consentRequests/<ID> resource returns the current state of the permissions relating to a particular condition request. "

• "condition request"?

Section 2.1.4: "the /consents resource is used to negotiate a series of permissions between the PISP and the DFSP which owns the account(s) on behalf of which the PISP wants to transact."

• "the" should be "The".

Section 2.1.4.1.1: "The GET consents/<Id> resource allows a party to enquire after the status of a consent."

• Should be "GET /consents/<ID>"

Section 2.1.4.1.1: "The <Id> used in the query string of the request should be the consent request ID which was used to identify the consent when it was created."

• Which query string are you referring to here? There is no query string as part of the request that I can see?

Section 2.1.4.1.2 "The PUT /consents/<Id> resource is used to return information relating to the consent object whose consentId is given in the query."

• Which query are you referring to?

Section 2.1.5: "The PISP will be permitted to issue a PUT /parties response."

• Please explain how this would work. To me, it seems like the account holder should request an alias to be created for them at the FSP, preferably as part of the consent request when the PISP is given access to an account. When this alias is used by for example a merchant, the FSP routes the confirmation to the PISP.

Section 2.1.5.2.1 "The PUT /parties resource will use the same form as the resource described in Section 6.3.4.1 of Ref. 1 above.
It should be noted, however, that the Party object returned from this resource has a different format from the Party object described in Section 7.4.11 of Ref. 1 above. The structure of this object is described in Section 2.2.1.21 below."

• I don't understand how this will work as they have exactly the same name. What is the purpose of the note as the only object that is in the PUT /parties callback is the Party? That means that the entire service is different, as there is only one element and that differs between the PISP and the FSP Interoperability API?

Section 2.1.6: "The services resource is a new resource which enables a participant to query for other participants who offer a particular service. The requester will issue a GET request, specifying the type of service for which information is required as part of the query string. The switch will respond with a list of the current DFSPs in the scheme which are registered as providing that service."

• Can you please give some examples of how this service is supposed to be used, so that it is easier to understand the purpose of it?

Section 2.1.7: "The PISP uses it to request the owner of the PISP’s customer’s account to transfer a specified amount from the customer’s account with the DFSP to a named recipient."

• Please use term Payee instead of recipient as recipient can mean both a recipient of message or recipient of money.

Section 2.1.7.2.1 "The PUT /thirdpartyRequests/transactions/<ID> resource will have the same content as the PUT /transactionRequests/<ID> resource described in Section 6.4.3.1 of Ref. 1 above."

• Please explain why the PISP needs to have the information that is sent in the PUT /transactionRequests/<ID>?

Section 2.1.7.2.2 "The issuing PISP will expect a response to their request for a transfer which describes the finalised state of the requested transfer. This response will be given by a PATCH call on the /thirdpartyRequests/transactions/<ID> resource."

• This comment is related to the bullet above. As currently specified, there does not seem to be any purpose in the PUT callback that I can understand. Based on my (perhaps limited) understanding, the result of the transaction should come in the PUT callback after the transaction has been performed between the Payer and Payee FSP.

Section 2.1.7.2.2 "The content of this resource will be the same as the data model described in Table 23 of Ref. 1 above, in the section describing the PUT command on the /transfers resource shown in Section 6.7.3.1 of Ref. 1 above."

• Please explain to me why the PISP needs to know about the inner details of the transfer between the Payer and Payee FSP?

Section 2.1.8.1.2: "Challenge"

• Please do not allow a string of any size.

Section 2.1.9.3.1: "PUT /thirdPartyRequests/validations/<type>/<ID>/error"

• The "thirdPartyRequests" part seems a bit misplaced here, as this is not present in any other service as part of the resource.

Section 2.2.1.1: "AccountAddress"

• Can you please explain the purpose of the AccountAddress as part of this? What will it be used for? I would like to understand the purpose of this change in relation to PISP. I know that this has earlier been discussed as a potential part of transfers between schemes, but I don't really see the purpose for PISPs.

Section 2.2.1.2: "It does not need to provide an address that makes the account identifiable outside thementity's domain."

• "thementity's"?

Section 2.2.1.2: "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)."

• I don't understand what the "the payee DFSP in this case"-part has to do with PISPs?

Section 2.2.1.8: "The AuthenticationValue data element contains a response returned by the recipient of an authorization request. It is described in Section 7.3.3 of Ref. 1 above, and is extended to support the new authentication type used for PISP."

• Are you proposing to extend the definition of the type in the FSP Interoperability API, or is this just using the same name which would be confusing?

Section 2.2.1.10: "Challenge"

• There is another Challenge in Section 2.1.8.1.2 (POST /thirdPartyRequests/verifications). Is that supposed to use this Challenge, or are different challenges?

Section 2.2.1.10 "payload"

• Please do not allow a string without a maximum size.

Section 2.2.1.25 "This information is forwarded to the PISP by the Payer DFSP so that the PISP’s customer can make an informed consent to the transfer, and is forwarded to the FIDO server (if one is used) to confirm the bona fides of the authorisation received from the PISP."

• Please explain to me why the customer would be interested in all this information as showed in the table? This contains private information like the date of birth which should be used for screening purposes. Information like date of birth is not meant to be sent to a consumer, and I have no idea what the PISP is supposed to do with the information. Any kind of personal data that is transmitted must have an acceptable reason for it to be shared.
• The information showed in the table is also not the quote information, it seems to be a copy of the Party type.

Section 2.2.1.26: "The following shows a proposed revision of the Party data element to support the additional information required to support PISP interactions."

• Why is this information required to support PISP interactions? See comment above as this contains personal information which is not meant to be shared for other reasons than screening (date of birth). Why should the consumer or PISP be interested in seeing the merchantClassificationCode?

Section 2.2.1.28: "ScopeAction"

• The name "ScopeAction" sounds strange, either it is a scope, or it is an action?

Section 2.2.1.29: "Scope"

• The name of the element is Scope (should be "scope"), but the type name is "ScopeAction"?

Section 2.2.1.31: "Transaction"

• Please explain to me why the PISP needs all these details regarding the transaction between the Payer FSP and the Payee FSP.
• For example, as an FSP I would not like the Payee FSP fee or Payee FSP commission to be sent to another party that is not involved in the actual transaction between the Payer FSP and Payee FSP (the PISP in this case). I would really not want to spread any personal information like date of birth which is part of the Party type.

Section 2.2.1.33: URL Regular expression

• The regular expression is not valid (the //). Additionally, the regular expression seems to allow me to enter any number of characters, meaning that an attacker can send an extremely long string, which can cause a parser crash or buffer overrun. Please don't allow an unlimited number of characters. Please investigate if you can find a better regular expression for validating the URL.

Section 2.2.2.6: "THIRDPARTYLINK"

• Please be consistent with existing names. Other types which contain more than one word (PERSONAL_ID and ACCOUNT_ID) has an underscore between the words, hence the name should be "THIRD_PARTY_LINK"

Section 2.2.2.7: "BALANCEENQUIRY", "FUNDSTRANSFER"

• Please be consistent with existing enums. See above.

Section 2.2.2.8: "3PDFSP"

• Why not just use some word that is easier to understand? You will likely not see any difference in performance compared to using a longer name. "3PDFSP" sounds like a character in Star Wars ;)

Kind regards,
Henrik

Thanks for your prompt comments, Henrik.

First, a number of your comments seem to me to relate to best practice in relation to APIs in general. As I said in the reorganisation proposal, I think that there should be a best practices document maintained by the CCB, and I've therefore started one based on your comments and aligned the PISP API document with them. Let me know what you think.

Second, the use of the term "DFSP". This is, in my view generally in use in the Mojaloop community today and has largely replaced "FSP". Accordingly, I would like to continue to use "DFSP" in this document, simply because I think it is the term most likely to be understood by users. I'd be happy to add it to the glossary; which, again, I would expect to continue to be maintained by the central CCB.

Since the Service Name entries in the Open API Specification for FSP Interoperability refer to entries in the Generic Transaction Patterns document, and we are not at present proposing a PISP version of this document, I have removed them from the PISP API definition.

Think I changed all the references to the Open API Specification for FSP Interoperability.

I have replaced the regex for URI with that given in RFC 3986.

I take a different view from you about the imposition of maximum limits. Briefly, it is as follows. A Mojaloop scheme is a community of known participants regulated by rules, and the messages that pass between them are, as you say, protected by security measures. If those measures are not adequate to protect the community from outside attack, then my feeling is that the sooner the system knows about it the better. If, on the other hand, toxic messages are being created and sent by participants, then, again, the system should identify the problem and work with the participant responsible to take appropriate action. However, I will raise this as an issue with the PISP team and canvass their opinion on how they would like to proceed.

I will also raise the issue of the information that it is proper for the PISP to expect the payer DFSP to include when it asks the PISP to confirm the transfer. Our expectation was that this should be equivalent to the terms of the transfer, and that it would therefore definitely need to include, for instance, information about the costs that the customer was expected to pay. In the end, though, it will not be the DFSPs who decide which information is to be included and which excluded, but the scheme via the scheme rules. We will not, in my view, be doing the API a service if we exclude from it information which schemes subsequently want to include; but if we allow the inclusion of information which they subsequently decide to exclude, no harm is done that I can see. In any case, I will raise the issue and let you know what we decide.

Draft PISP Specification Changes.docx

API Best Practices.docx

Thanks @mjbrichards,

From what I can see in the PISP Specification document, you have not enabled changes to be tracked? May I ask you to either answer directly on my comments so that I know which ones you have addressed, or at least use track changes in the document, so that I don't have to review the entire document again to find out where you might have changed anything? This would save a lot of time for me, and for others who might have read the first version or my comments so that they are also aware of what has changed.

Based on a quick read now it seems like some of my comments are ignored, and it would be good to know why. I'm sure there are a number misunderstandings in my comments (one of the misunderstandings is mentioned below) as I have not been involved in this specification development, and that some objects are shared, while others are not shared with the FSPIOP API. There are also questions that are left unanswered.

I will read and review your start of the API Best Practices document, let me get back to you with comments regarding that.

Regarding the term DFSP, it is already in the glossary as an alternative term for FSP.

I will also raise the issue of the information that it is proper for the PISP to expect the payer DFSP to include when it asks the PISP to confirm the transfer. Our expectation was that this should be equivalent to the terms of the transfer, and that it would therefore definitely need to include, for instance, information about the costs that the customer was expected to pay.

This issue seems to be mostly because the quote object was not defined in the earlier version. My assumption was that this was to be based on the existing quote object in FSPIOP API provided on the information in that section (my emphasis added on Payee DFSP: The Quote object is used to collect the information on the terms of a transfer which a Payee DFSP returns as part of the positive response to a quotation. This information is forwarded to the PISP by the Payer DFSP so that the PISP’s customer can make an informed consent to the transfer, ...), as the quote object was not defined in the previous version. In the new update, the quote object is now more of an end user quote. The end user fees in the user's FSP definitely need to be shared to the PISP, as this information is required by the end user to be able to confirm.

Also regarding the quote, just looking at the quote part now again:

• There might be also be additional fees or taxes for the end user, or some bonus or commission payout involved in the transaction (see Section 5.1 in the FSPIOP API Definition). As far as I can see, this information is not made available to the user in the current specification?
• Why is the quote sent in the POST /thirdpartyRequests/transactions to the FSP? It is not the PISP that decides the quote?
• How is Send amount or Receive amount decided?

In the end, though, it will not be the DFSPs who decide which information is to be included and which excluded, but the scheme via the scheme rules.

Please let me know why you think that a PISP should ever know about the birth dates of the Payer and Payee? I would just like to understand any use case for the PISP where this information could be valuable? In the FSP Interoperability API, the information is there to support sanction screening. But for PISPs I do not understand the purpose of the data, hence I would like to know why it can even be shared.

We will not, in my view, be doing the API a service if we exclude from it information which schemes subsequently want to include; but if we allow the inclusion of information which they subsequently decide to exclude, no harm is done that I can see.

There is certainly harm done if someone would spread personal information to a PISP which should not need to know the information. Our FSPs that follows GDPR have the obligation to protect any data of consumers so that only necessary private data is shared. If I was an account holder in any of the FSPs that does not try to follow GDPR, I would still like them to keep my private data private.

Kind regards,
Henrik

Hi Henrik, thank you for your comments, and please accept my apologies for not having turned on Track Changes when updating the specification. I have produced a further revision of the specification, together with a document responding to each of the points you raised in your original response, and I attach them here.

On the other points you raise:

• You are correct: the current specification does not break down the fees into their components. As far as I recall, the L1P only requires that customers are informed about the overall cost of a transaction. I'm not against more detail personally, but we saw no need for it.
• You are correct: the quote object should not appear in the POST /thirdpartyRequests/transactions request. I have removed it.
• The receive amount is returned by the payee DFSP as part of the quote response. The send amount is contained in the Transaction object, though this may be modified by the Payer DFSP if it intends to deduct further fees from the customer.

Please let me know why you think that a PISP should ever know about the birth dates of the Payer and Payee? I would just like to understand any use case for the PISP where this information could be valuable?

• My PISP provides an on-line grocery service where purchases may include alcohol. I want to know my customer's age from an authority other than themselves before allowing them to make a purchase which includes alcohol.
• MY PISP provides an on-line pocket money service. You can only use it to send to people less than 18 years of age.

Now to your last paragraph. My view is as follows, at the risk of repeating myself. Decisions about what data items are required or forbidden to be included in messages are the responsibility of the operators of the scheme. The switch provides functionality which enables these decisions to be enforced. In any case, extension lists allow any sort of information about entities in the system to be passed; but at the cost of damaging the general application of the technology providers' solutions, as we have already discussed. This effectively by-passes the sort of control over content which I think you propose as a function of the API.

Now, in relation to your specific points. First, it is in my view the responsibility of the scheme, not the API, to decide whether or not a PISP needs to, or can, be party to specific items of information. If yes, then it will allow or mandate the content; if no, it will forbid it. All of this will, of course, be aligned with the regulatory regime in force in the jurisdiction(s) in which the scheme operates; if that were not true, it would not be permitted to operate at all. Second, if you personally did not agree with the sharing of private data in accordance with the regulatory regimes in force in the jurisdiction under which your DFSP operated, you would be entirely at liberty not to participate; but, in my opinion, it would be unreasonable to expect an API to enforce regulations that a regulator did not.

Yours,
Michael
Draft PISP Specification Changes.docx
HK Comment Responses.docx

Thanks Michael and Henrik for your rigorous discussion. I've done another review myself, which you can find here:

Draft.PISP.Specification.Changes_ld_review_16_nov.docx

Thanks @mjbrichards,

You are correct: the current specification does not break down the fees into their components. As far as I recall, the L1P only requires that customers are informed about the overall cost of a transaction. I'm not against more detail personally, but we saw no need for it.

At least many of our FSPs has the requirement that the customer should be able to see how much of the amount that they pay is tax. I can't say if it is a regulatory requirement, or if just our FSPs want to be open with how much is tax vs fee. If you want agents to be able to use PISP, then you need to share the commission that they have earned as well.

The receive amount is returned by the payee DFSP as part of the quote response. The send amount is contained in the Transaction object, though this may be modified by the Payer DFSP if it intends to deduct further fees from the customer.

I'm not talking about the amount that the Payee would receive. As a Payer, you can choose that the amount of the transaction is either a Send amount or a Receive amount. This controls if fees for the Payer should be added on top of the amount, or withdrawn from the amount (please see Section 5.1 in API Definition for FSPIOP). As far as I understand, the use case that you are trying to solve for now is P2P? For a merchant payment, you would always use a Receive amount as the merchant should receive a specific amount. For a P2P, the use of Send vs Receive differs between our deployments.

Thank you for providing two examples where you think the birth dates are important for the PISP. Please note that I'm not against that private data can be shared to the PISP. What I'm against is that it seems like the data is shared without any control from the user. I'm sure that there are other types of private data that the PISP might be interested in, why I think there should be a generic support for asking consent about sharing private data in a standardized way. Please see for example OpenID Connect, where a service can specify a number of claims that represent different kinds of personal data that can be requested from the user.

Can you please explain to me how I as an FSP would know when the PISP would need the birth dates based on the existing design? Otherwise it seems like the FSP would now always need to share the birth dates, as the PISP might need them for some use case. This would allow the PISP to collect a lot of data about both parties, even though only one of them is a customer of the PISP (either Payer or Payee).

In my mind, as you already have a way of asking for consent as part of the API, the PISP should also ask for consent to get the birth date from the user. It probably already has a consent from the PISP's consumer from the sign up of the customer for the service, but probably not from the other consumer (Payee or Payer depending on use case).

I think that we are doing the schemes and implementers of the API a service if these topics are discussed as part of the API design, as privacy issues are in general a hot topic, instead of just allowing the data to be sent without any more thought. Having a standardized way of asking for consent to share the data would also allow other types of private data to be shared other than just birth date.

I will read and review the updated documents.

Kind regards,
Henrik

This is a new version of the PISP API specification (1.3) which I hope takes account of the latest state of our discussions on the account linking process. Any comments would be most welcome. Two particular points:

1. I have replaced the proposed unlinking syntax (POST /consents/ID/revoke) with a syntax more closely aligned with the existing FSPIOP API: **DELETE /consents/**ID. This is the syntax currently used to make changes to oracles in the ALS, and I therefore thought it more suitable here. However, I am aware that the proposed syntax is better aligned with the Google syntax recommendations for custom methods (https://google.aip.dev/136). Perhaps we should discuss.
2. It occurred to me in thinking about unlinking that our statement of the consent does not at present include definition of the two parties (the PISP and the DFSP) between whom the consent is agreed. It occurred to me that a central register for all consents would really require this, and I have therefore included them in the data body for the POST /consents call. Let me know your thoughts.

Otherwise, I have tried to stick to the sequence diagrams, with what success I shall leave you to judge.
Draft PISP Specification Changes.docx

This is a new version of the PISP API specification (1.3)
Thanks Michael! Taking a look now

A new version (1.4) of the PISP specification, based on discussions with @lewisdaly, JJ and @eoln. This now represents our agreed view.
Draft PISP Specification Changes.docx

Thanks @MichaelJBRichards

@MichaelJBRichards
3.1.4.2.2 PUT /consents/
-> in table we have specified property consentState of typeCredenitalState I see here some inconsistency I think it should be ConsentStatusType
- in api-snippets we have defined ConsentStatusType
- in api-snippets we have spreaded in multiple places enum values for CredenitalStatus: PENDING VERIFIED

-> for property credential type is not specified

I have made the changes suggested by @eoln, together with changes consequent on a detailed review of the sequence diagrams and changes to the data model for the PUT /thirdPartyRequests/authorizations endpoint described in Section 3.1.6.2.1, following a discussion on this point.
Draft PISP Specification Changes.docx

Commenting just on the POST /thirdpartyRequests/authorizations for now:

• Is the transactionId necessary for the PISP? This is the ID for the Mojaloop transfer, which is not known for an on-us transaction. The transactionRequestId was created by the PISP, so that is necessary to know, but the transactionId should not necessary as far as I know. What should the PISP do with the information?
• Is the ilpCondition necessary for the PISP? This is not known for an on-us transaction as far as I know. What should the PISP do with the information?

@MichaelJBRichards what do you think?

I think the only case where the PISP would want the transactionId is if it wanted to query the switch about a past transaction, which I don't see as a valid use case - they should instead ask the DFSP for the transactionRequest, with GET thirdpartyRequests/{id}/transactions call.

For the ilpCondition, we've dropped the need for the PISP to have and end-to-end guarantee of the transfer, so I think we can lose this as well.

These changes are now summarized in this PR: #90

Please comment inline there where it makes sense.

I've just updated the openapi spec documents for this change request in PR #90, so it's ready for another review.