feat(mojaloop/3347): enhance the request to pay transfer api process …

…for payer acceptance flow (#163)

feat([mojaloop/3347](mojaloop/project#3347)): enhance the request to pay transfer api process for payer acceptance flow

**Changes:**

SDK Backend API:
- Added `homeR2PTransactionId` and `transactionRequestId` to `POST /quoteRequest`
- Added `homeR2PTransactionId` to `POST /transfers`
- Added new API resource `PUT /requestToPay/{transactionRequestId}`

SDK Outbound API:
- Changed `requestToPayTransactionId` to `transactionRequestId` in `PUT /requestToPayTransfer`
- Added `homeR2PTransactionId` and `transactionRequestId` to `requestToPayTransferRequest`
- Fixed schema for `scenario` field in `requestToPayTransferRequest`
- Added `authenticationType` to `requestToPayTransferRequest`
- Changed `requestToPayTransactionId` to `transactionRequestId` in `requestToPayTransferResponse`
- Added `homeR2PTransactionId` to `requestToPayTransferResponse`
- Fixed schema of `quoteResponse` in `requestToPayTransferResponse`
- Added `authorizationResponse` to `requestToPayTransferResponse`
- Fixed schema of `fulfil` in `requestToPayTransferResponse`

docs/sdk-scheme-adapter-backend-v2_0_0-openapi3-snippets.yaml

@@ -104,6 +104,29 @@ paths:
       summary: Callbacks for the bulk transaction request.
       tags:
         - BulkTransactionsPut
+  /requestToPay/{transactionRequestId}:
+    put:
+      description: >-
+        It is used to notify the DFSP backend about the status of the
+        requestToPayTransfer.
+      operationId: RequestToPayPut
+      parameters:
+        - $ref: '#/components/parameters/transactionRequestId'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/requestToPayCallback'
+      responses:
+        '200':
+          description: OK
+        '400':
+          $ref: '#/components/responses/400'
+        '500':
+          $ref: '#/components/responses/500'
+      summary: Callback for the requestToPay request.
+      tags:
+        - RequestToPayPut
   /bulkTransfers:
     post:
       operationId: BackendBulkTransfersPost
@@ -1196,6 +1219,11 @@ components:
     quoteRequest:
       description: A request for a quote for transfer from the DFSP backend.
       properties:
+        homeR2PTransactionId:
+          type: string
+          description: >-
+            Linked homeR2PTransactionId which was generated as part of POST
+            /requestToPay to SDK incase of requestToPay transfer.
         amount:
           $ref: '#/components/schemas/money'
         amountType:
@@ -1233,6 +1261,8 @@ components:
           $ref: '#/components/schemas/transactionId'
         transactionType:
           $ref: '#/components/schemas/transactionType'
+        transactionRequestId:
+          $ref: '#/components/schemas/transactionRequestId'
       required:
         - quoteId
         - transactionId
@@ -1483,6 +1513,11 @@ components:
       type: object
     transferRequest:
       properties:
+        homeR2PTransactionId:
+          type: string
+          description: >-
+            Linked homeR2PTransactionId which was generated as part of POST
+            /requestToPay to SDK incase of requestToPay transfer.
         amount:
           $ref: '#/components/schemas/money'
         amountType:
@@ -1513,6 +1548,8 @@ components:
           $ref: '#/components/schemas/transactionType'
         transferId:
           $ref: '#/components/schemas/transferId'
+        transactionRequestId:
+          $ref: '#/components/schemas/transactionRequestId'
       required:
         - transferId
         - quote
@@ -1560,6 +1597,18 @@ components:
         - WAITING_FOR_QUOTE_ACCEPTANCE
         - COMPLETED
       type: string
+    requestToPayCallback:
+      description: Callback for requestToPay.
+      properties:
+        homeR2PTransactionId:
+          type: string
+          description: >-
+            Transaction ID from the DFSP backend, used to reconcile transactions
+            between the Switch and DFSP backend systems.
+        transactionRequestState:
+          $ref: '#/components/schemas/transactionRequestState'
+      required:
+        - transactionRequestState
     TransactionSubScenario:
       title: TransactionSubScenario
       type: string

docs/sdk-scheme-adapter-outbound-v2_0_0-openapi3-snippets.yaml

@@ -383,15 +383,15 @@ paths:
           $ref: '#/components/responses/transferServerError'
         '504':
           $ref: '#/components/responses/transferTimeout'
-  /requestToPayTransfer/{requestToPayTransactionId}:
+  /requestToPayTransfer/{transactionRequestId}:
     put:
       summary: >-
-        Continues a transfer that has paused at the otp stage in order to accept
+        Continues a transfer that has paused at the Authentication stage in order to accept
         or reject quote
       description: >
-        The HTTP request `PUT /transfers/{transferId}` is used to continue a
-        transfer initiated via the `POST /transfers` method that has halted
-        after party lookup and/or quotation stage.
+        This request is used to continue a requestToPayTransfer initiated via
+        the `POST /requestToPayTransfer` method that has halted after Quotation
+        stage and/or Authentication stage.
 
 
         The request body should contain either the "acceptOTP" or "acceptQuote"
@@ -410,7 +410,7 @@ paths:
                 - $ref: '#/components/schemas/transferContinuationAcceptQuote'
                 - $ref: '#/components/schemas/transferContinuationAcceptOTP'
       parameters:
-        - $ref: '#/components/parameters/requestToPayTransactionId'
+        - $ref: '#/components/parameters/transactionRequestId'
       responses:
         '200':
           $ref: '#/components/responses/transferSuccess'
@@ -2370,7 +2370,8 @@ components:
     requestToPayTransferRequest:
       type: object
       required:
-        - requestToPayTransactionId
+        - homeR2PTransactionId
+        - transactionRequestId
         - from
         - to
         - amountType
@@ -2380,11 +2381,13 @@ components:
         - initiator
         - initiatorType
       properties:
-        requestToPayTransactionId:
+        homeR2PTransactionId:
           type: string
           description: >-
             Transaction ID from the DFSP backend, used to reconcile transactions
             between the Switch and DFSP backend systems.
+        transactionRequestId:
+          $ref: '#/components/schemas/CorrelationId'
         from:
           $ref: '#/components/schemas/transferParty'
         to:
@@ -2396,17 +2399,101 @@ components:
         amount:
           $ref: '#/components/schemas/Amount'
         scenario:
-          $ref: '#/components/schemas/TransactionType'
+          $ref: '#/components/schemas/TransactionScenario'
+        subScenario:
+          $ref: '#/components/schemas/TransactionSubScenario'
         initiator:
           $ref: '#/components/schemas/TransactionInitiator'
         initiatorType:
           $ref: '#/components/schemas/TransactionInitiatorType'
         note:
           $ref: '#/components/schemas/Note'
+        authenticationType:
+          $ref: '#/components/schemas/AuthenticationType'
+    AuthenticationValue:
+      title: AuthenticationValue
+      anyOf:
+        - title: OtpValue
+          type: string
+          pattern: ^\d{3,10}$
+          description: >-
+            The API data type OtpValue is a JSON String of 3 to 10 characters,
+            consisting of digits only. Negative numbers are not allowed. One or
+            more leading zeros are allowed.
+        - title: QRCODE
+          type: string
+          minLength: 1
+          maxLength: 64
+          description: QR code used as a One Time Password.
+        - title: U2FPinValue
+          type: object
+          description: >
+            U2F challenge-response, where payer FSP verifies if the response
+            provided by end-user device matches the previously registered key.
+          properties:
+            pinValue:
+              type: string
+              pattern: ^\S{1,64}$
+              minLength: 1
+              maxLength: 64
+              description: >
+                U2F challenge-response, where payer FSP verifies if the response
+                provided by end-user device matches the previously registered
+                key.
+            counter:
+              title: Integer
+              type: string
+              pattern: ^[1-9]\d*$
+              description: >-
+                Sequential counter used for cloning detection. Present only for
+                U2F authentication.
+          required:
+            - pinValue
+            - counter
+      pattern: ^\d{3,10}$|^\S{1,64}$
+      description: >-
+        Contains the authentication value. The format depends on the
+        authentication type used in the AuthenticationInfo complex type.
+    AuthenticationInfo:
+      title: AuthenticationInfo
+      type: object
+      description: Data model for the complex type AuthenticationInfo.
+      properties:
+        authentication:
+          $ref: '#/components/schemas/AuthenticationType'
+        authenticationValue:
+          $ref: '#/components/schemas/AuthenticationValue'
+      required:
+        - authentication
+        - authenticationValue
+    AuthorizationResponseType:
+      title: AuthorizationResponseType
+      type: string
+      enum:
+        - ENTERED
+        - REJECTED
+        - RESEND
+      description: |-
+        Below are the allowed values for the enumeration.
+        - ENTERED - Consumer entered the authentication value.
+        - REJECTED - Consumer rejected the transaction.
+        - RESEND - Consumer requested to resend the authentication value.
+      example: ENTERED
+    AuthorizationIDPutResponse:
+      title: AuthorizationIDPutResponse
+      type: object
+      description: The object sent in the PUT /authorizations/{ID} callback.
+      properties:
+        authenticationInfo:
+          $ref: '#/components/schemas/AuthenticationInfo'
+        responseType:
+          $ref: '#/components/schemas/AuthorizationResponseType'
+      required:
+        - responseType
     requestToPayTransferResponse:
       type: object
       required:
-        - requestToPayTransactionId
+        - transactionRequestId
         - from
         - to
         - amountType
@@ -2416,11 +2503,13 @@ components:
       properties:
         transferId:
           $ref: '#/components/schemas/CorrelationId'
-        requestToPayTransactionId:
+        homeR2PTransactionId:
           type: string
           description: >-
             Transaction ID from the DFSP backend, used to reconcile transactions
             between the Switch and DFSP backend systems.
+        transactionRequestId:
+          $ref: '#/components/schemas/CorrelationId'
         from:
           $ref: '#/components/schemas/transferParty'
         to:
@@ -2440,16 +2529,39 @@ components:
         quoteId:
           $ref: '#/components/schemas/CorrelationId'
         quoteResponse:
-          $ref: '#/components/schemas/QuotesIDPutResponse'
+          type: object
+          required:
+            - body
+          properties:
+            body:
+              $ref: '#/components/schemas/QuotesIDPutResponse'
+            headers:
+              type: object
         quoteResponseSource:
           type: string
           description: >
             FSPID of the entity that supplied the quote response. This may not
             be the same as the FSPID of the entity which owns the end user
             account in the case of a FOREX transfer. i.e. it may be a FOREX
             gateway.
+        authorizationResponse:
+          type: object
+          required:
+            - body
+          properties:
+            body:
+              $ref: '#/components/schemas/AuthorizationIDPutResponse'
+            headers:
+              type: object
         fulfil:
-          $ref: '#/components/schemas/TransfersIDPutResponse'
+          type: object
+          required:
+            - body
+          properties:
+            body:
+              $ref: '#/components/schemas/TransfersIDPutResponse'
+            headers:
+              type: object
         lastError:
           description: >
             Object representing the last error to occur during a transfer
@@ -2803,15 +2915,6 @@ components:
       description: >-
         Identifier of the merchant request to pay to continue as returned in the
         response to a `POST /requestToPay` request.
-    requestToPayTransactionId:
-      name: requestToPayTransactionId
-      in: path
-      required: true
-      schema:
-        $ref: '#/components/schemas/CorrelationId'
-      description: >-
-        Identifier of the merchant request to pay transfer to continue as
-        returned in the response to a `POST /requestToPayTransfer` request.
     transferId:
       name: transferId
       in: path