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 completedTimestampas 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 bulkTransferStateelement: • 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 transferStateis 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 ABORTEDstate 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:

[mjbrichards]

As an aside, I'm not sure that it's possible for a cash-out situation to occur in a bulk transfer. In a cash-out, the funds are transferred from the customer's account to the agent's, and the agent gives the customer the cash. In the bulk (e.g. salary) case, the funds are transferred from the employer's account to the customer's account. If the customer were subsequently to cash the funds out, that would be a separate transfer. The other example that we typically use for requiring confirmation from the switch is goods purchase; but, again, that won't be the case here.

Am I right in thinking that, in the case where a normal transfer is aborted by the switch, the payee DFSP will receive a notification in any case? Is that the case for bulk transfers, or not? If it is, presumably we would need to dedupe the messages so that the payee DFSP does not receive them twice...

[elnyry-sam-k]

Thanks for reviewing Michael, @mjbrichards ..

On the last point - where a normal transfer is aborted by a Switch, currently FSPIOP API patterns do not support sending any notification to the Payee FSP; only the Payer FSP receives the notification (Payer FSP receives it always).. Example here: https://docs.mojaloop.io/api/fspiop/v1.1/api-definition.html#client-receiving-expired-transfer , which actually necessitates this change request (and even the previous patch notification for individual transfers, to some extent).

Regarding the other points, the scenarios prompting this change request involve bulk disbursements of loan amounts which happen via Banks or Mobile Wallet providers.

[henrka]

Thanks @elnyry-sam-k. Some quick comments for now:

• The bulkTransferState should probably be ACCEPTED instead of PROCESSING, as the description for PROCESSING is "Payee FSP has started to transfer fund to the Payees.". Accepted is "Payee FSP has accepted the bulk transfer for processing.", which seems to be more correct here.
• Some copy-paste issues about how the Switch should handle the PUT /bulkTransfers/{ID} in "If transfer state is COMPLETED or REJECTED, ..." and "If transfer state is PROCESSING, ...", transfer state should be bulk transfer state for these.
• Add handling (cancel all reservations) if Payee FSP receives bulkTransferState=ABORTED in the PATCH /bulkTransfers/{ID}

@mjbrichards, technically in the API it is actually possible to say that a bulk is a cash out (transactionScenario=WITHDRAWAL), but operationally this is not possible in a bulk... We should add some restrictions on which transactionScenarios that you are allowed to use for a bulk, because I don't think we have this mentioned in the specification right now.

[elnyry-sam-k]

Thanks @elnyry-sam-k. Some quick comments for now:

• The bulkTransferState should probably be ACCEPTED instead of PROCESSING, as the description for PROCESSING is "Payee FSP has started to transfer fund to the Payees.". Accepted is "Payee FSP has accepted the bulk transfer for processing.", which seems to be more correct here.
• Some copy-paste issues about how the Switch should handle the PUT /bulkTransfers/{ID} in "If transfer state is COMPLETED or REJECTED, ..." and "If transfer state is PROCESSING, ...", transfer state should be bulk transfer state for these.
• Add handling (cancel all reservations) if Payee FSP receives bulkTransferState=ABORTED in the PATCH /bulkTransfers/{ID}

@mjbrichards, technically in the API it is actually possible to say that a bulk is a cash out (transactionScenario=WITHDRAWAL), but operationally this is not possible in a bulk... We should add some restrictions on which transactionScenarios that you are allowed to use for a bulk, because I don't think we have this mentioned in the specification right now.

Thanks for the review and comments, Henrik. I'm happy to use "ACCEPTED" state, as the same advantage of not needing a new state applies here and this aligns better with the existing description. Fixed the other issues as well..

[henrka]

@elnyry-sam-k, A gentle reminder on this to create the actual solution :).

Minor comment on the updated flow: Current step 18 ("Request completion notification from Switch by sending bulk transfer state as ACCEPTED") shouldn't go to the Payee, it should go the Payee FSP itself.

[elnyry-sam-k]

Sure Henrik