Giters

mojaloop / mojaloop-specification

This repo contains the specification document set of the Open API for FSP Interoperability

Home Page:https://docs.mojaloop.io/api

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Thirdparty/PISP APIs and FSPIOP v2.0

lewisdaly opened this issue · comments

commented

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?"

commented

It would be great to understand why these changes are required. As of now these are very high level requests without stating why they are needed by the PISP API as part of a 2.0 version of the FSP Interoperability API.

commented
commented

Hi Miller, Henrik,

Thanks for your patience on this one. I didn't want to give a quick, half-baked answer, so I thought it best to wait until after the convening to give me time to "line up my ducks", so to speak.

Reasons for FSPIOP-API 2.0

1. Extend PUT /parties with account identifiers

During the account linking stage of the PISP/DFSP/User interactions, we need a method of allowing a user to see the accounts they hold with a DFSP, and select from that list which accounts they wish to link with the PISP.

This is important, since the PISP needs to be able to specify which account of the end user's that the Payer FSP should debit funds from.

To do this, we built upon Adrian's proposal for an extended Parties object.

2. Include 'subscriber' information in the Transaction Object

One of the challenges we have faced with the PISP design is "How do we inform the PISP of the transaction outcome?". We have been many stops in this journey of exploration, and these are the guiding principles for this design that have emerged:

  1. We don't want the switch to watch transactions and build it's own state to imply the list of interested parties - the list of interested parties should be expressed explicitly in messaging. (We had previously gone in this direction, but it was deemed too inefficient and clunky)
  2. We want the delivery of the final notification to come from the switch itself, and not from the Payer FSP. This was to (1) avoid any inconsistencies in state, as the central-ledger is the authority on whether or not a transaction was successful or not, and (2) ensure that the PISP does not become a dumb 'client' of the Payer FSP
  3. We should work towards a design which makes the PATCH /transfers notification to the Payee FSP more generic. @MichaelJBRichards can probably comment a little more this. It seems like in the future we will need such a mechanism for informing interested parties whether they be PISPs, DFSPs, or other future participants we may dream up
  4. We didn't want to conflate the business logic of clearing a transfer with switching messages. The original proposal for PISP was to introduce a new FSPIOP-Initiator header, but since the FSPIOP- headers are for routing messages, this didn't seem appropriate to use, since what we really want is to generate a new message based on some business logic to do with a transaction.

That has brought us to the latest iteration of our design, which includes a list of Subscribers (you can read the full writeup in Adrian's draft proposal here)

Here's how we see it working:

  1. The Payer FSP generates the subscribers list. For a vanilla Mojaloop transaction, this list would simply contain themselves as an interested party. In the case of a PISP transaction, the Payer FSP also includes the PISP as an interested party (see the example request here)
  2. During POST /quotes the Payer FSP sends the subscribers list in the request body
  3. The Payee FSP reads the subscribers list, and optionally includes themselves as an interested party

    Note: this is identical to the behaviour of the Payer FSP sending a PUT /transfers/{id} with a transferState=reserved in FSPIOP-API v1.1

  4. The Payee FSP adds the subscribers list to the Transaction object, and generates the condition and fulfillment
  5. The Payee FSP sends a PUT /quotes/{id} request back to the Payer FSP
  6. When the POST /transfers request is sent, the switch keeps a copy of the transaction object
  7. When the PUT /transfers/{id} arrives at the switch, the transfer is either fulfilled or rejected and the central-ledger emits a single notification containing the subscribers list. The api-adapters read this message and deliver the appropriate notifications to the FSPs and PISP

In brief, subscribers is a list sent by the Payer FSP in the POST /quotes request body. The Payee FSP optionally includes itself in this list, and adds the subscribers list it to the Transaction object. Upon the fulfillment or rejection of the transfer, the interested parties in the list are informed.

Let’s be cautious here about burdening the central ledger with unnecessary handling of the transaction object. Having a transaction service that is signaled internally by the normal central ledger events (in some way) to deliver materials to subscribers might be explored. But we should not burden the central ledger notifications with the full transaction object.

I think I understand this point Miller, but would certainly like to explore it further (I take it this applies to points 6 + 7 above). The reason we added the subscribers list to the transaction object in our designs, and not anywhere else was to ensure that it could not be tampered with by the Payer or Payee FSP. The challenge with including the list of interested parties in the messages itself is that we need to pass this information through the system somehow. Perhaps we can think of another way to include notification metadata which doesn't require a modification to the Transaction object itself.

commented

Thanks @lewisdaly,

Maybe I missed something, but your comment does not really seem to answer why all the three requirements in the issue are needed:

  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

I can see the answer for nr 2 (the subscription list), but not the others? It would be great if you can explain the reasons behind the other two requirements (nr 1 and nr 3) to the CCB/SIG as well, so that we all have a common understanding and can prioritize any issues accordingly.

May I also ask you to explain why the PISP is requesting the transfer from Payer FSP (the customer's FSP), instead of the Payee FSP (the merchant's FSP in case of a merchant initiated payment)? This might very well already be documented somewhere, so feel free to just share a link in that case. If the PISP request was sent to the Payee FSP instead, which would in turn send a normal POST /transactionRequests to the Payer FSP, it seems like there would be no need of a subscription as the Payee FSP would then have the final outcome of the transfer from the Switch and can notify the PISP? I have not analyzed this in detail though, so there might very well be other issues.

Kind regards,
Henrik

commented

Thanks @ehenrka

For #1 - I will leave for @MichaelJBRichards to comment on. I think this was a concern for the efficiency of processing transfers, since we will need to decode the transaction object to obtain the list of subscribers.

As for #3, yes I realize now I didn't go into enough detail there. The PISP knows nothing about the underlying transfer that will take place, it knows only about the Thirdparty Transaction Request Resource, and indeed is waiting for a PATCH /thirdpartyRequests/transactions/{id} callback, where id is the initial transactionRequestId.

The PATCH /thirdpartyRequests/transactions/{id} callback from the switch is sent upon the clearing of funds (as with the PUT /transfers/{id} call to the Payer FSP, and the optional PATCH /transfers/{id} to the Payee FSP). Which means we need a way to tie together a transferId and transactionRequestId.

May I also ask you to explain why the PISP is requesting the transfer from Payer FSP (the customer's FSP), instead of the Payee FSP (the merchant's FSP in case of a merchant initiated payment)?

I think this was the way we always looked at the problem, given the relationship between the User, PISP and Payer FSP. Given that the Payer FSP is the one with the knowledge of the user's account, and the credential linking the account with the PISP, it makes sense for the Payer FSP to be the one requesting the authentication. I'm sure there's other reasons I'm not thinking of as well at the moment...

Perhaps these two sets of documentation, linking and transfer will shed some more light, although we don't explicitly answer that question.

To me a POST /transactionRequests seems like another level of misdirection here, but I'd like to explore this further, since this was something that has come up in conversation a couple times recently.

it seems like there would be no need of a subscription as the Payee FSP would then have the final outcome of the transfer from the Switch and can notify the PISP?

Indeed I think this is possible in any case. We could very easily require the Payer FSP to inform the PISP of the transaction outcome after it receives the PUT /transfers/{id} call from the switch. This was something we discussed earlier on, but decided that the Switch is the authority on the state of a transaction, so it should be the switch doing the informing. But I'd like to open up this topic again.

commented

Thanks @lewisdaly,

The PATCH /thirdpartyRequests/transactions/{id} callback from the switch is sent upon the clearing of funds (as with the PUT /transfers/{id} call to the Payer FSP, and the optional PATCH /transfers/{id} to the Payee FSP). Which means we need a way to tie together a transferId and transactionRequestId.

Do you mean that it is the Switch that needs to be able to tie the transferId and the transactionRequestId together, or who is it that (the we) needs to tie these together? If the PATCH /thirdpartyRequests/transactions/{id} request is sent from the Switch, should not both the transferId and the transactionRequestId be known by the Switch already, as the original POST /thirdpartyRequests/transactions was passed along the Switch on its way to the FSP?

Is it because you do want to store any information about the thirdPartyRequest in the Switch? Should it really be the Switch that is sending this callback, would it not be easier if it was the FSP that the user has its account in, as that is where the original POST /thirdpartyRequests/transactions was sent to?

I think this was the way we always looked at the problem, given the relationship between the User, PISP and Payer FSP. Given that the Payer FSP is the one with the knowledge of the user's account, and the credential linking the account with the PISP, it makes sense for the Payer FSP to be the one requesting the authentication.

I'm really sorry for the confusion, it seems like I had a too quick look on the flow and misunderstood the basic use case, if the User is the Consumer and this is a normal P2P transfer then yes it makes perfect sense. I was thinking about the use case Merchant initiated merchant payment, where it is the merchant that requests a payment from the Consumer. In that case the credential linking and related relationship should be between the Merchant, PISP, and Merchant FSP (the Payee FSP in a merchant initiated payment).

Indeed I think this is possible in any case. We could very easily require the Payer FSP to inform the PISP of the transaction outcome after it receives the PUT /transfers/{id} call from the switch. This was something we discussed earlier on, but decided that the Switch is the authority on the state of a transaction, so it should be the switch doing the informing. But I'd like to open up this topic again.

For a P2P Transfer, yes it should be very easy for the Payer FSP to inform the PISP as they have the final PUT /transfers callback from the Switch. It seems to me that a flow where it is the Switch that is in charge of informing the PISP puts unnecessary requirements on the Switch, as well as making unnecessary changes to the API. But it might very well be that there are very good reasons for that, and I would just like to understand them.

Kind regards,
Henrik

commented
commented

Thanks @millerabel, @ehenrka,

I know there's another thread on the community page that contains some of this discussion.

Until the payer DFSP is satisfied that the transfer completed, it is still pending with the payer and therefore the status between the PISP and the Payer DFSP is unsettled even if the transfer has been committed and even if the PISP has other knowledge of completion in the hub. That’s not a good outcome.

I hadn't considered this case until now - this is a good point. From the PISP's perspective, the source of truth on a transfer's outcome should come from the Payer DFSP, and the Payer DFSP can use the ILP Packet to prove that indeed the transaction took place.

The latest of @MichaelJBRichards's and my thinking is simply to require the Payer DFSP to inform the PISP of the transaction outcome. This simplifies many things, and avoids the can of worms. We weren't originally intending the PISP to need the fulfilment in the final notification from the Payer DFSP, but now I'm beginning to see that it will be necessary.

Even if we decide to require the Payer DFSP to go this route, I think we should have a discussion on these generic notification principles, as it is something discussed in other proposed changes (or musings of proposed changes). Having a clear statement of the principles here will aid future designs (and make sure we don't go around in circles).

commented

Thanks @lewisdaly,

The latest of @MichaelJBRichards's and my thinking is simply to require the Payer DFSP to inform the PISP of the transaction outcome. This simplifies many things, and avoids the can of worms. We weren't originally intending the PISP to need the fulfilment in the final notification from the Payer DFSP, but now I'm beginning to see that it will be necessary.

Please explain to me why the PISP should need the fulfilment? At least in my understanding, the PISP should not be involved in the actual transaction more than that the end user is requesting the transaction and confirming the transaction via the PISP instead of the FSP directly. The only entities that are involved in the actual financial transaction are the Payer, Payer FSP, Switch, Payee FSP, and the Payee. The only involved entities in the actual transfer of funds between FSPs are Payer FSP, Switch, and Payee FSP, hence there is a need for a proof of the transaction for these entities. The transfer of funds in the Payer/Payee FSP is within the same system, hence there should be no need for a proof of the transaction. If the end user gets the notification from its FSP via the PISP, then the end user can trust that the transaction has been performed. If there would be any problems, then the FSP has the fulfilment that the Switch has sent to them as proof. The PISP should not have to validate a fulfilment.

Even if we decide to require the Payer DFSP to go this route, I think we should have a discussion on these generic notification principles, as it is something discussed in other proposed changes (or musings of proposed changes). Having a clear statement of the principles here will aid future designs (and make sure we don't go around in circles).

Please explain any use case that you see where it should be required that the Switch is sending a notification to anyone else than the Payer FSP or Payee FSP, as part of the transfer of funds between the Payer FSP and the Payee FSP?

Kind regards,
Henrik