Change Request: Possibility to notify Payee FSP on completion of a bulk transfer in Switch

[elnyry-sam-k]

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 | Sam Kummary, Mojaloop community | | Change Request Status | In review ☒ / Approved ☐ / Rejected ☐ | | Approved/Rejected Date | |

1.2 Document Version Information

Version	Date	Author	Change Description
1.0	2022-06-07	Sam Kummary	Initial draft created and shared with CCB, FSPIOP SIG for review.

2. Problem Description

___

2.1 Background

In order for a Payee FSP to ascertain that individual transfers in a bulk have been committed successfully in the Switch, the Payee FSP today needs to send a GET /bulkTransfers/<ID> to the Switch as detailed in the API Definition.

In a use-case involving bulk disbursements of funds for one of Mojaloop's adopters, it is risky to release funds without getting confirmation from a Switch. This involves scenarios where it is complicated to perform a refund in case of problems, as these involve cash-outs. To avoid having to send the GET /bulkTransfers/<ID>, the change request is to allow the Payee FSP to tell the Switch that the funds have been reserved, and the Switch will then send a notification to the Payee FSP when the bulk transfer is completed in the Switch.

This is similar to the patch notification introduced as part of the change request "possibility to notify a Payee FSP on a successful commit". (Text taken from CR#29 and changes made to reflect bulk scenario)

2.2 Current Behaviour

The Payee FSP today needs to send a GET /bulkTransfers/<ID> to the Switch to know the status in the Switch.

2.3 Requested Behaviour

The Payee FSP can send the PUT /bulkTransfers/<ID> to the Switch saying that the funds are reserved (at an individual transfer level) and that it would like a notification when the bulk transfer is completed in the Switch with the individual transfers being either committed or aborted.

3. Proposed Solution Options

___

To indicate that the Payee FSP would like to have a notification regarding the status of the bulkTransfer in the Switch before it will commit the individual transfers (the individual transfers must be reserved in the Payee FSP), the Payee FSP should send a PUT /bulkTransfers/<ID> with the bulkTransferState set to ACCEPTED (similar to RESERVED for transferState of individual transfers) instead, and no completedTimestamp as the transfer is not yet completed (The proposal made here to use "ACCEPTED" is so that an existing enum value for bulk transfer state can be used instead of a new value to minimize changes to the API):

PUT /bulkTransfers/85feac2f-39b2-491b-817e-4a03203d4f14 HTTP/1.1
Content-Type: application/vnd.interoperability.bulkTransfers+json;version=1.2
Content-Length: 166
Date: Tue, 07 Jun 2022 08:14:02 GMT
FSPIOP-Source: payeefsp
FSPIOP-Destination: payerfsp
FSPIOP-Signature: {"signature": "YXBwbGlj...JzK2pzb2"}
{
	"bulkTransferState": "ACCEPTED",
	"individualTransferResults": [{
			"transferId": "2d412bbc-a5c4-26fc-bea0-c1598dcefce8",
			"fulfilment": "1eLGaPcSJqNJhx2f6A2TA0oW-kflVEsF7AyZehZ-qXF"
		},
		{
			"transferId": "345c2nnc-4b24-ag37-poi1-124xdxs1234i",
			"fulfilment": "HfQBjEJLj96GGyJ1hBl4EXiEKLg9_raKzSpICW9-CgM"
		}
	]
}

Switch receives the PUT /bulkTransfers/<ID>, responds with HTTP 200 as normal. Switch then looks at the bulkTransferState element: • If the bulk transfer state is COMPLETED or REJECTED, then there is no need to send out a notification as the Payee FSP has already either accepted the risk that some transfers in rare cases might fail or has rejected all of it, respectively. This is how it works in the API today (v1.1). • If the bulk transfer state is ACCEPTED, then the Switch needs to send out a notification when the all the individual transfers in the bulk transfer are processed (either COMMITTED or ABORTED) in the Switch. A new object type is required that includes individual transferState for each of the transfers, along with the existing elements of the current PUT /bulkTransfers/<ID> message body. Alternately, the existing complex type (message body of PUT bulkTransfers call) can be used here where transfers with failures can use error information response type and committed transfers can present fulfilments or an existing field other than error information.

PATCH /bulkTransfers/85feac2f-39b2-491b-817e-4a03203d4f14 HTTP/1.1
Content-Type: application/vnd.interoperability.bulkTransfers+json;version=1.2
Content-Length: 166
Date: Tue, 07 Jun 2022 08:14:02 GMT
FSPIOP-Source: switch
FSPIOP-Destination: payeefsp
FSPIOP-Signature: {"signature": "YXBwbGlj...JzK2pzb2"}
{
	"bulkTransferState": "COMPLETED",
	"completedTimeStamp": "2022-06-07T20:07:09.602+03:58",
	"individualTransferResults": [{
			"transferId": "2d412bbc-a5c4-26fc-bea0-c1598dcefce8",
			"transferState": "COMMITTED"
		},
		{
			"transferId": "345c2nnc-4b24-ag37-poi1-124xdxs1234i",
			"transferState": "COMMITTED"
		}
	]
}

When the Payee FSP receives the PATCH /bulkTransfers/<ID> notification, it responds with HTTP 200, and then either: • If the individual transferState in the bulk is set to COMMITTED, the Payee FSP commits the corresponding transfer • If the individual transferState is set to ABORTED, the Payee FSP cancels the corresponding reserved transfer and aborts the transaction

If the Payee FSP does not get the notification from the Switch within a reasonable time, it can resend the PUT /bulkTransfers/<ID> to the Switch as the request should be idempotent. The Switch should then send (or resend) the PATCH /bulkTransfers/<ID> to the Payee regarding the status in the Switch. This is to align the flow with all other requests that can be resent to request a new callback, in the FSPIOP API specification.

The Payee FSP will need to receive the status from the Switch before committing, or accept the risk that some transfers in the bulk might have failed in the Switch. The Payee FSP should not be allowed to abort any individual transfer without receiving an ABORTED state from the Switch, as the Payee FSP has sent the fulfilment (which is the commit trigger) to the Switch.

The proposed sequence diagram for the new bulk patch notification: