Change Request: ISO 20022 Version of FSPIOP API

[MichaelJBRichards]

Open API for FSP Interoperability - Change Request

Table of Contents

• 1. Preface
  • 1.1 Change Request Information
  • 1.2 Document Version Information
• 2. Problem Description
  • 2.1 Background
  • 2.2 Current Behaviour
  • 2.3 Requested Behaviour
• 3 Proposed Solution Options

1. Preface

___

This section contains basic information regarding the change request.

1.1 Change Request Information

| Requested By | Michael Richards, INFITX |
| Change Request Status | In review ☒ / Approved ☐ / Rejected ☐ |
| Approved/Rejected Date | |

1.2 Document Version Information

Version	Date	Author	Change Description
1.0	2023-01-19	Michael Richards	Initial version of change request.

2. Problem Description

___

2.1 Background

The Mojaloop Foundation intends to publish a version of the FSPIOP API which uses ISO 20022 documents as the body of its messages. Initial analysis suggests that the existing ISO 20022 messages are not suitable for our purposes. We have proposed a number of new messages to meet our requirements. The ISO 20022 Payments SEG has asked us to investigate the possibility of modifying existing messages to meet our purposes. Accordingly, we have produced an analysis of the changes to the core payment execution message (pacs.008) that we think will be required to meet the Mojaloop requirements. A copy of the analysis is available here.

In addition, we have produced a sequence diagram showing how a simple P2P transfer could be made in a Mojaloop system using ISO 20022 messages including the proposed modifications. We need this sequence diagram to be reviewed by FSPIOP experts to ensure that the ISO 20022 implementation is solid. Please respond by commenting on this issue.

2.2 Current Behaviour

Standard FSPIOP behaviour

Explain how you would like the API to behave.

The same way as it does now, but using agreed ISO 20022 messages

3. Proposed Solution Options

___

[henrka]

Thanks @MichaelJBRichards, I have looked at the flow and I have the following comments/questions:

POST /quotes:

• Step 1 says "Please send 200 SGD ...", but the quote information here seems to imply that the Payer would like to send 5050 SGD from their account..
• ChrgBr: Is it really correct that DEBT would be equivalent to AmountType SEND? ChrgBr=DEBT should mean that it is the debtor that bears the charges, but AmountType=SEND means that any fees are withdrawn from the amount, meaning less funds to the Payee, which should be the reverse in my mind.. But maybe I'm misunderstanding the ISO 20022 concept here..
• New proposed TxTp structure: Some elements (SubScenario, Initiator, ..) in this new structure should probably be abbreviated as existing ISO 20022 elements. I expect there is some standard for how the parameters are abbreviated in ISO 20022..
• InitiatorType in TxTp: This aligns with current version 1.1 of the FSPIOP API, but maybe it makes sense to change to what was decided in Adding detail to transaction type definition #25 for FSPIOP version 2.0, i.e. removing initiatorType from a transaction and having it in the Party information instead.
• The quote does not contain a transactionRequestId now as it is a Payer initiated transaction, but is Payee initiated transactions also in scope for ISO 20022?

PUT /quotes:

• See comments for POST /quotes on TxTp
• IntrBkSttlAmt shouldn't change for a SEND amount (is 5000 in POST /quotes and 5100 in PUT /quotes), the Payee would receive less. If it was AmountType RECEIVE, then the IntrBkSttlAmt should be higher to cover for the Payee FSP fees.
• ILP is used in the FSPIOP API, but maybe it is better for ISO if we leave this more open, so that other technologies that work in the same way could potentially be used as well? I don't know if it is easier for them to accept if there is not a requirement on ILP specifically, like IIPS could potentially be used by other technologies than Mojaloop.

POST /transfers:

• Is there no need for a specific transferId here? Or is that assumed to be the MsgId for the POST /transfers?
• ChrgBr: See comment for POST /quotes.
• ILP: See comment for POST /quotes.

PUT /transfers:

• Is it correct that the MsgId should be the "callback ID" (as in PUT /transfers/<callback ID> here? In the FSPIOP API POST /transfers there is an element transferId, that is used as the "callback ID".
• Here the fulfilment is without prefix "Ilp", which is in line with my suggestion under PUT /quotes to generalize it a bit more.

[MichaelJBRichards]

I have incorporated 1, 2 and 4 of Henrik's suggestions and (I hope) aligned the amounts.

WRT 3: I agree, Henrik, but I thought I'd leave the ISO people some fun to have...

WRT 5: Yes, we will expect to support payee initiated transactions. There is an ISO 20022 RTP message (pain.013), but we promised the ISO guys that we'd start with pacs.008. I am planning at present to include in the quotation the information that there was an RTP by adding a StgeInf element with an RTP stage identification and the RTP ID...

You raise an interesting question with respect to the ILP packet. We could think about using the existing W3 schema for XML signatures, which ISO already uses as part of the Business Application Header; but I'm agnostic here. Let's discuss.

Yes, I was assuming that the FSPIOP TransferId would be represented by the MsgId.

On the fulfilment, I define an ILP Cryptography field which is an XML choice between a condition and a fulfilment. In the earlier messages, you see the condition; in this one the fulfilment. But I think you don't show the containing structure in the XML. I may be wrong about this, of course...

Anyway, here's a revised version of the sequence diagram incorporating the changes.

[henrka]

Thanks @MichaelJBRichards,

Some comments on the updated flow for fees and settlement amounts:

• POST /quotes: "Agt": { // This says who's getting the fee: it's the payer
  -- Should be more correct to say Payer FSP instead of just "payer"?
• POST /quotes: There is a fee of 2 here, and AmountType SEND is used according to ChrgBr which indicates that the Payer would like 200 to be withdrawn from their account. If the Payer FSP has a fee of 2 for the Payer for this transaction, that would mean that 2 should be withdrawn from the amount (200) that is sent to the Payer FSP, meaning the settlement amount between the banks (IntrBkSttlAmt) is 198 here. See https://docs.mojaloop.io/api/fspiop/v1.1/api-definition.html#disclosing-send-amount for an example.
• PUT /quotes: "Agt": { // This says who's getting the fee: it's the payee
  -- Should be more correct to say Payee FSP instead of just "payee"?
• PUT /quotes: As in an earlier comment above, IntrBkSttlAmt should be 198. Preferably to follow the Mojaloop FSPIOP API, there should be a field indicating what the Payee will receive (198 in IntrBkSttlAmt - 1 in Payee FSP fee=197 SGD), but it is also possible to calculate this using the ChrgsInf.
• Step 23: "You are cleared to make this transfer. 203 SGD will be debited from your account. Your beneficiary will receive 200 SGD. Please confirm that you want to proceed"
  -- This text indicates that AmountType RECEIVE has been used, as fees are added on top of the amount. If RECEIVE should be used, then the IntrBkSttlAmt before PUT /quotes are correct. As the Payee FSP wants a fee of 1 SGD as visible in the PUT /quotes, the IntrBkSttlAmt needs to be equally increased by 1 SGD to cover the Payee FSP fee so that the Payee actually receives 200 SGD, meaning IntrBkSttlAmt = 201 SGD in PUT /quotes.
• POST /transfers: The IntrBkSttlmAmt should be updated, to which amount depends on if it is RECEIVE or SEND AmountType as discussed above.