From 8d7143629b608f0412a1ca77df3c78fcf30b7440 Mon Sep 17 00:00:00 2001
From: Christian Grothoff <christian@grothoff.org>
Date: Sun, 9 Aug 2020 12:59:39 +0200
Subject: revise public case

---
 design-documents/007-payment.rst | 35 +++++++++++++++++++++--------------
 1 file changed, 21 insertions(+), 14 deletions(-)

diff --git a/design-documents/007-payment.rst b/design-documents/007-payment.rst
index 09205705..0b4ca4ad 100644
--- a/design-documents/007-payment.rst
+++ b/design-documents/007-payment.rst
@@ -99,11 +99,10 @@ Backend Client Order Status Page
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The merchant backend runs the following steps to generate the HTML page for
-``GET /orders/{order-ID}?session_id={session-ID}&claim_token={claim-token}&h_contract={contract-hash}``:
-------- NOTE: currently the argument is just 'token', not 'claim_token'! ----------
+``GET /orders/{order-ID}?session_id={session-ID}&token={claim-token}&h_contract={contract-hash}``:
 
 1. If *order-ID* does not identify an existing order, render a 404 Not Found response.  **Terminate.**
-2. If *order-ID* identifies a paid order (where the *session-id* matches the one from the payment), run these steps:
+2. If *order-ID* identifies a paid order (where the *session-ID* matches the one from the payment), run these steps:
 
    1. If the *contract-hash* request parameter does not match the contract terms hash of the order,
       return a 403 Forbidden response. **Terminate.**
@@ -119,24 +118,32 @@ The merchant backend runs the following steps to generate the HTML page for
       obtained.  **Terminate.**
       ----- FIXME: IIRC our long-polling API does only allow waiting for the granted refund amount, not for the *obtained* refund amount. => API change?
 
-   3. Here the order has been paid. -------- what about refunded???
-      Prompt the URI ------ ???why? don't we redirect to fulfillment URL???????
+   3. Here the order has been paid and possibly refunded.
+      Redirect to the *fulfillment-URL* of the order.
+      **Terminate.**
 
-      ::
 
-        taler{proto_suffix}://pay/{/merchant_prefix*}/{order-id}/{session-id}
+3. If *order-ID* identifies an *unclaimed* order, run these steps:
 
-      Redirect to the *fulfillment-URL* of the order once
-      payment has been proven under *session-ID*.
+   1. If the order is *unclaimed* and the *claim-token* request parameter does not
+      match the claim token of the order, return a 403 Forbidden response. **Terminate**.
 
-      **Terminate.**
+   2. Prompt the URI
+
+      ::
+
+        taler{proto_suffix}://pay/{/merchant_prefix*}/{order-id}/{session-ID}?c={claim-token}
 
+      The generated Web site should long-poll to check for the payment happening.
+      It should then redirect to the *fulfillment-URL* of the order once
+      payment has been proven under *session-ID*, or possibly redirect to the
+      *already-paid-order-ID*. Which of these happens depends on the (long-polled) JSON replies.
+      **Terminate.**
 
-3. If *order-ID* identifies an *unpaid* order, run these steps:
+4. If *order-ID* identifies an *claimed* and *unpaid* order, run these steps:
 
-   1. If the the *claim-token* request parameter does not match the claim token of
-      the order,  return a 403 Forbidden response. **Terminate**.
-      ----- DISCUSS: unpaid vs. unclaimed: do we check token or h_contract? ------
+   1. If the order is *claimed* and the *contract-hash* request parameter does not
+      match the contract hash of the order, return a 403 Forbidden response. **Terminate**.
 
    2. If there is a non-null *already-paid-order-ID* for *session-ID* stored under the current order,
       redirect to the *fulfillment-URL* of *already-paid-order-ID*. **Terminate**.
-- 
cgit v1.2.3