sequence diagrams for transactions-requests-service (including authorizations)

SUMMARY.md

@@ -125,6 +125,10 @@
       * [Funds Out - Commit](mojaloop-technical-overview/central-settlements/funds-in-out/funds-out-commit.md)
       * [Funds Out - Abort](mojaloop-technical-overview/central-settlements/funds-in-out/funds-out-abort.md)
     * [OSS Settlement FSD](mojaloop-technical-overview/central-settlements/oss-settlement-fsd.md)
+  * [Transaction-requests-service Service](mojaloop-technical-overview/transaction-requests-service/README.md)
+    * [Transaction Requests Create](mojaloop-technical-overview/transaction-requests-service/transaction-requests-post.md)
+    * [Transaction Requests Query](mojaloop-technical-overview/transaction-requests-service/transaction-requests-get.md)
+    * [Authorizations](mojaloop-technical-overview/transaction-requests-service/authorizations.md)
   * [Central-Event-Processor Services](mojaloop-technical-overview/central-event-processor/README.md)
     * [Event Handler (Placeholder)](mojaloop-technical-overview/central-event-processor/9.1.0-event-handler-placeholder.md)
     * [Notification Handler For Rejections](mojaloop-technical-overview/central-event-processor/5.1.1-notification-handler-for-rejections.md)

mojaloop-technical-overview/transaction-requests-service/README.md

@@ -2,5 +2,8 @@
 
 ## Sequence Diagram
 
-{% uml src="mojaloop-technical-overview/transaction-requests-service/assets/diagrams/sequence/seq-trs-1.0.0.plantuml" %}
+{% uml src="mojaloop-technical-overview/transaction-requests-service/assets/diagrams/sequence/trx-service-overview-spec.plantuml" %}
 {% enduml %}
+
+* The transaction-requests-service is a mojaloop core service that enables Payee initiated use cases such as "Merchant Request to Pay".
+* This is a pass through service which also includes Authorizations.

mojaloop-technical-overview/transaction-requests-service/assets/diagrams/sequence/seq-trx-req-authorizations-3.0.0.plantuml

@@ -0,0 +1,64 @@
+/'*****
+ License
+ --------------
+ Copyright © 2017 Bill & Melinda Gates Foundation
+ The Mojaloop files are made available by the Bill & Melinda Gates Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ Contributors
+ --------------
+ This is the official list of the Mojaloop project contributors for this file.
+ Names of the original copyright holders (individuals or organizations)
+ should be listed with a '*' in the first column. People who have
+ contributed from an organization can be listed under the organization
+ that actually holds the copyright for their contributions (see the
+ Gates Foundation organization for an example). Those individuals should have
+ their names indented and be marked with a '-'. Email address can be added
+ optionally within square brackets <email>.
+ * Gates Foundation
+ - Name Surname <name.surname@gatesfoundation.com>
+
+ * Sam Kummary <sam@modusbox.com>
+ --------------
+ ******'/
+
+
+@startuml
+Title Transaction Requests Service - Authorizations
+participant "Payer FSP"
+participant "Switch\ntransaction-requests-service" as Switch
+participant "Payee FSP"
+
+autonumber
+"Payee FSP" --\ "Payee FSP": Lookup, Transaction request,\nprocessing not shown here
+note over "Payee FSP", Switch: Payee FSP generates a transaction-request to the Payer FSP
+"Payer FSP" --> "Payer FSP": Do quote, generate OTP\nnotify user (not shown here)
+"Payer FSP" -\ Switch: GET /authorizations/{TransactionRequestID}
+Switch --/ "Payer FSP": 202 Accepted
+
+alt authorization request is valid
+
+    Switch -> Switch: Validate GET /authorizations/{TransactionRequestID} (internal validation)
+    Switch -> Switch: Retrieve corresponding end-points for Payee FSP
+    note over Switch, "Payee FSP": Switch forwards GET /authorizations request to Payee FSP
+    Switch -\ "Payee FSP": GET /authorizations/{TransactionRequestID}
+    "Payee FSP" --/ Switch: 202 Accepted
+    "Payee FSP" -> "Payee FSP": Process authorization request\n(Payer approves/rejects transaction\nusing OTP)
+
+    note over Switch, "Payee FSP": Payee FSP responds with PUT /authorizations//{TransactionRequestID}
+    "Payee FSP" -\ Switch: PUT /authorizations//{TransactionRequestID}
+    Switch --/ "Payee FSP": 200 Ok
+
+    note over "Payer FSP", Switch: Switch forwards PUT /authorizations//{TransactionRequestID} to Payer FSP
+    Switch -> Switch: Retrieve corresponding end-points for Payer FSP
+    Switch -\ "Payer FSP": PUT /authorizations//{TransactionRequestID}
+    "Payer FSP" --/ Switch: 200 Ok
+
+
+else authorization request is invalid
+    note over "Payer FSP", Switch: Switch returns error callback to Payer FSP
+    Switch -\ "Payer FSP": PUT /authorizations/{TransactionRequestID}/error
+    "Payer FSP" --/ Switch: 200 OK
+    "Payer FSP" --> "Payer FSP": Validate OTP sent by Payee FSP
+end
+@enduml

mojaloop-technical-overview/transaction-requests-service/assets/diagrams/sequence/seq-trx-req-service-1.0.0.plantuml

@@ -0,0 +1,93 @@
+/'*****
+ License
+ --------------
+ Copyright © 2017 Bill & Melinda Gates Foundation
+ The Mojaloop files are made available by the Bill & Melinda Gates Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ Contributors
+ --------------
+ This is the official list of the Mojaloop project contributors for this file.
+ Names of the original copyright holders (individuals or organizations)
+ should be listed with a '*' in the first column. People who have
+ contributed from an organization can be listed under the organization
+ that actually holds the copyright for their contributions (see the
+ Gates Foundation organization for an example). Those individuals should have
+ their names indented and be marked with a '-'. Email address can be added
+ optionally within square brackets <email>.
+ * Gates Foundation
+ - Name Surname <name.surname@gatesfoundation.com>
+
+ * Sam Kummary <sam@modusbox.com>
+ --------------
+ ******'/
+
+
+@startuml
+Title Transaction Requests Service - Create
+participant "Payer FSP"
+participant "Switch\ntransaction-requests-service" as Switch
+participant "Payee FSP"
+
+autonumber
+"Payee FSP" -\ "Payee FSP": Lookup process\n(not shown here)
+note over "Payee FSP", Switch: Payee FSP generates a transaction-request to the Payer FSP
+"Payee FSP" -\ Switch: POST /transactionRequests
+Switch -> Switch: Validate POST /transactionRequests schema
+Switch --/ "Payee FSP": 202 Accepted
+
+alt transaction-request is valid
+
+    Switch -> Switch: Validate POST /transactionRequests (internal validation)
+    Switch -> Switch: Retrieve corresponding end-points for Payer FSP
+    note over Switch, "Payer FSP": Switch forwards POST /transactionRequests request to Payer FSP
+    Switch -\ "Payer FSP": POST /transactionRequests
+    "Payer FSP" --/ Switch: 202 Accepted
+    "Payer FSP" -> "Payer FSP": Process transaction-request
+
+    alt Payer FSP successfully processes transaction-request
+
+        note over "Payer FSP", Switch: Payer FSP responds to POST /transactionRequests
+        "Payer FSP" -\ Switch: PUT /transactionRequests/{ID}
+        Switch --/ "Payer FSP": 200 Ok
+
+        Switch -> Switch: Validate PUT /transactionRequests/{ID}
+
+        alt response is ok
+
+            note over Switch, "Payee FSP": Switch forwards transaction-request response to Payee FSP
+            Switch -> Switch: Retrieve corresponding end-points for Payee FSP
+
+            Switch -\ "Payee FSP": PUT /transactionRequests/{ID}
+            "Payee FSP" --/ Switch: 200 Ok
+
+            note over "Payee FSP" #3498db: Wait for a quote, transfer by Payer FSP\nor a rejected transaction-request
+        else response invalid
+
+            note over Switch, "Payer FSP": Switch returns error to Payer FSP
+
+            Switch -\ "Payer FSP": PUT /transactionRequests/{ID}/error
+            "Payer FSP" --/ Switch : 200 Ok
+
+            note over Switch, "Payer FSP" #ec7063: Note that under this\nscenario the Payee FSP\nmay not receive a response
+
+        end
+    else Payer FSP calculation fails or rejects the request
+
+        note over "Payer FSP", Switch: Payer FSP returns error to Switch
+
+        "Payer FSP" -\ Switch: PUT /transactionRequests/{ID}/error
+        Switch --/ "Payer FSP": 200 OK
+
+        note over "Payee FSP", Switch: Switch returns error to Payee FSP
+
+        Switch -\ "Payee FSP": PUT /transactionRequests/{ID}/error
+        "Payee FSP" --/ Switch: 200 OK
+
+    end
+else transaction-request is invalid
+    note over "Payee FSP", Switch: Switch returns error to Payee FSP
+    Switch -\ "Payee FSP": PUT /transactionRequests/{ID}/error
+    "Payee FSP" --/ Switch: 200 OK
+end
+@enduml

mojaloop-technical-overview/transaction-requests-service/assets/diagrams/sequence/seq-trx-req-service-get-2.0.0.plantuml

@@ -0,0 +1,90 @@
+/'*****
+ License
+ --------------
+ Copyright © 2017 Bill & Melinda Gates Foundation
+ The Mojaloop files are made available by the Bill & Melinda Gates Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ Contributors
+ --------------
+ This is the official list of the Mojaloop project contributors for this file.
+ Names of the original copyright holders (individuals or organizations)
+ should be listed with a '*' in the first column. People who have
+ contributed from an organization can be listed under the organization
+ that actually holds the copyright for their contributions (see the
+ Gates Foundation organization for an example). Those individuals should have
+ their names indented and be marked with a '-'. Email address can be added
+ optionally within square brackets <email>.
+ * Gates Foundation
+ - Name Surname <name.surname@gatesfoundation.com>
+
+ * Sam Kummary <sam@modusbox.com>
+ --------------
+ ******'/
+
+
+@startuml
+Title Transaction Requests Service - Query
+participant "Payer FSP"
+participant "Switch\ntransaction-requests-service" as Switch
+participant "Payee FSP"
+
+autonumber
+note over "Payee FSP", Switch: Payee FSP requests the status of a transaction-request at the Payer FSP.\nID here is the ID of prevoiusly created transaction-request
+"Payee FSP" -\ Switch: GET /transactionRequests/{ID}
+Switch -> Switch: Validate GET /transactionRequests/{ID}
+Switch --/ "Payee FSP": 202 Accepted
+
+alt transaction-request query is valid
+
+    Switch -> Switch: Retrieve corresponding end-points for Payer FSP
+    note over Switch, "Payer FSP": Switch forwards GET /transactionRequests/{ID} request to Payer FSP
+    Switch -\ "Payer FSP": GET /transactionRequests/{ID}
+    "Payer FSP" --/ Switch: 202 Accepted
+    "Payer FSP" -> "Payer FSP": Retrieve transaction-request
+
+    alt Payer FSP successfully retrieves transaction-request
+
+        note over "Payer FSP", Switch: Payer FSP responds with the\nPUT /transactionRequests/{ID} callback
+        "Payer FSP" -\ Switch: PUT /transactionRequests/{ID}
+        Switch --/ "Payer FSP": 200 Ok
+
+        Switch -> Switch: Validate PUT /transactionRequests/{ID}
+
+        alt response is ok
+
+            note over Switch, "Payee FSP": Switch forwards transaction-request response to Payee FSP
+            Switch -> Switch: Retrieve corresponding end-points for Payee FSP
+
+            Switch -\ "Payee FSP": PUT /transactionRequests/{ID}
+            "Payee FSP" --/ Switch: 200 Ok
+
+        else response invalid
+
+            note over Switch, "Payer FSP": Switch returns error to Payer FSP
+
+            Switch -\ "Payer FSP": PUT /transactionRequests/{ID}/error
+            "Payer FSP" --/ Switch : 200 Ok
+
+            note over Switch, "Payer FSP" #ec7063: Note that under this\nscenario the Payee FSP\nmay not receive a response
+
+        end
+    else Payer FSP is unable to retrieve the transaction-request
+
+        note over "Payer FSP", Switch: Payer FSP returns error to Switch
+
+        "Payer FSP" -\ Switch: PUT /transactionRequests/{ID}/error
+        Switch --/ "Payer FSP": 200 OK
+
+        note over "Payee FSP", Switch: Switch returns error to Payee FSP
+
+        Switch -\ "Payee FSP": PUT /transactionRequests/{ID}/error
+        "Payee FSP" --/ Switch: 200 OK
+
+    end
+else transaction-request is invalid
+    note over "Payee FSP", Switch: Switch returns error to Payee FSP
+    Switch -\ "Payee FSP": PUT /transactionRequests/{ID}/error
+    "Payee FSP" --/ Switch: 200 OK
+end
+@enduml

mojaloop-technical-overview/transaction-requests-service/authorizations.md

@@ -0,0 +1,8 @@
+# Transaction Requests
+
+GET /authorizations/{TransactionRequestID} and PUT /authorizations/{TransactionRequestID} to support authorizations in "Merchant Request to Pay" and other Payee initiated use cases
+
+## Sequence Diagram
+
+{% uml src="mojaloop-technical-overview/transaction-requests-service/assets/diagrams/sequence/seq-trx-req-authorizations-3.0.0.plantuml" %}
+{% enduml %}

mojaloop-technical-overview/transaction-requests-service/transaction-requests-get.md

@@ -0,0 +1,8 @@
+# Transaction Requests - Query
+
+GET /transactionRequests and PUT /transacionRequests to suppport "Merchant Request to Pay"
+
+## Sequence Diagram
+
+{% uml src="mojaloop-technical-overview/transaction-requests-service/assets/diagrams/sequence/seq-trx-req-service-get-2.0.0.plantuml" %}
+{% enduml %}

mojaloop-technical-overview/transaction-requests-service/transaction-requests-post.md

@@ -0,0 +1,8 @@
+# Transaction Requests
+
+POST /transactionRequests and PUT /transacionRequests to suppport "Merchant Request to Pay"
+
+## Sequence Diagram
+
+{% uml src="mojaloop-technical-overview/transaction-requests-service/assets/diagrams/sequence/seq-trx-req-service-1.0.0.plantuml" %}
+{% enduml %}