Change Request: Refactoring 3PPI Transfer Interface

[mjbrichards]

Refactoring the 3PPI Transfer Interface

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

1.2 Document Version Information

Version	Date	Author	Change Description
1.0	2022-01-28	Michael Richards	Initial version of issue. Sent out for review.

2. Problem Description

___

2.1 Background

The current structure of a 3PPI transfer request is as follows:

1. 3PPI requests identification of the recipient directly from the switch.
2. Creditor DFSP responds to 3PPI with identification.
3. 3PPI requests initiation of transfer by debtor DFSP.
4. Debtor DFSP responds to 3PPI with acceptance of transfer initiation request.
5. Debtor DFSP requests authorisation of transfer from 3PPI. This includes information about the terms of the transfer.
6. 3PPI obtains confirmation from customer and responds to debtor DFSP.
7. If terms rejected, debtor DFSP responds with a PATCH on request 3 (i.e. supersedes 4) and STOP
8. If terms accepted, debtor DFSP checks authorisation.
9. If authorisation check fails, debtor DFSP responds with a PUT (S/B PATCH?) on request 3 (i.e. supersedes 4) and STOP.
10. Otherwise, transfer is executed and debtor DFSP responds with a PATCH on request 3 (i.e. supersedes 4) and STOP.

So, essentially, steps 1-2 correspond with the discovery phase, steps 3-5 with the agreement phase, and steps 7-10 with the execution phase. Failures in the execution phase, however, are recorded in a step that might be seen as properly belonging to the agreement phase.

Like many external APIs, the proposed Google Imali interface divides a transfer into the following phases:

1. The 3PPI requests a transfer of a given amount to a specified account. (the Request phase)
2. The debtor DFSP responds with the details of the transfer and a challenge to sign.
3. The 3PPI requests execution of the transfer, giving the signed challenge to establish its bona fides. (the execution phase).
4. The debtor DFSP responds with the outcome of the transfer execution.

So:

1. The response at step 2 is equivalent to the request at step 5 in the Mojaloop sequence.
2. The request at step 3 is equivalent to the response at step 6 in the Mojaloop sequence.

In mapping two-step transfer sequences like the Imali one onto our three-step sequence, we have tended to map the initial phase onto our discovery phase, and the second phase onto our agreement and execution phases. This thinking has given rise to the potential problem just described, where requests on either side can perfectly properly be ignored by the other side:

• If the debtor DFSP makes a request for authorisation based on a 3PPI's prior request to initiate a transfer, that completes a request/response pair on the 3PPI's side, and the 3PPI would not intuitively expect to need to send a further request ("Please don't!") if the customer decides not to proceed.
• If the 3PPI requests a transfer (including the signed challenge) and the debtor DFSP rejects the signature, or if the transfer fails for some other reason, then the response comes back as a modification to the two-phase model's transfer request, not the execution request.

This mismatch contains the possibility that errors and misunderstandings will arise over the course of implementation, increasing the likelihood of failure and hence the cost of operation of a system which supports transfers initiated by 3PPIs. If possible, we should consider aligning our interface with Google's Imali interface as a representative of a common pattern in transfer initiation which is consistent with Level 1 principles, as described below.

2.2 Current Behaviour

See above

2.3 Requested Behaviour

At present, we map our Discovery phase onto the two-phase Request phase, and our Agreement and Execution phases onto the two-phase Execution phase. But in the 3PPI context, the point of agreement, and the conclusion of the Request phase, is the user's authorisation of the agreed terms of the transfer. Hence the Execution phase cannot begin until the 3PPI has responded with the signed challenge, which is a request to execute the agreed transfer. This meets the Level One requirement that a customer should always be able to consent to the exact terms of the transfer before confirming that the transfer should be executed.

A more correct mapping of the Mojaloop phases onto the two-phase model might rather be:

• The Request phase starts with step 1 of the Mojaloop sequence and completes at step 5.
• The Execution phase starts with step 6 of the Mojaloop sequence and continues to the end.
• The content of a Request phase, er, request is equivalent to our current step 3 (the body of a POST /thirdpartyRequests/transactions request, perhaps with the payee.fspId left blank to indicate the requirement for discovery).
• The content of a Request phase response is our step 5 (the body of a POST thirdpartyRequests/authorizations request).
• The content of an Execution phase request is our step 6 (the body of a PUT thirdpartyRequests/authorizations request).
• The PATCH responses in our steps 7, 9 and 10 now appear as simple PUT responses to the request issued in our step 6.

This approach would require a revision of our endpoint definitions, but, I think, no revision to the message content. It would also remove the need for a 3PPI to support the FSPIOP GET /parties endpoint.