[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-docs] branch master updated (069bf92 -> 551739c)
From: |
gnunet |
Subject: |
[taler-docs] branch master updated (069bf92 -> 551739c) |
Date: |
Sun, 09 Aug 2020 12:16:58 +0200 |
This is an automated email from the git hooks/post-receive script.
grothoff pushed a change to branch master
in repository docs.
from 069bf92 more problems
new 3d697e3 content: https://www.gnu.org/philosophy/words-to-avoid.en.html
new 6d4a4b2 fix English
new 551739c points for discussion
The 3 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
design-documents/007-payment.rst | 110 ++++++++++++++++++++++++++-------------
1 file changed, 75 insertions(+), 35 deletions(-)
diff --git a/design-documents/007-payment.rst b/design-documents/007-payment.rst
index c797cd5..aacd163 100644
--- a/design-documents/007-payment.rst
+++ b/design-documents/007-payment.rst
@@ -14,15 +14,17 @@ Requirements
as well as external wallets (mobile phone, command line)
* The initiator of the payment can be a Website or another channel,
such as an e-mail or a messaging service.
-* For paid digital content, there should be a reasonable technical barrier to
- sharing the content with unauthorized users
+* For paid digital works, there should be a reasonable technical barrier to
+ sharing the information with unauthorized users
* A simple API should be offered to shops
-* Sharing of links or re-visiting of bookmarks should result in well-defined,
+* Sharing of links or re-visiting of bookmarks should result in well-defined
behavior instead of random, ugly error messages.
Proposed Solution
=================
+
+
Session-bound payment flow for Web resources
--------------------------------------------
@@ -35,103 +37,133 @@ Storefront
When *resource-URL* is requested, the storefront runs the following steps:
1. Extract the the *order-ID* (or null) and *resource name* from the
*resource-URL*.
-2. Extract the *session-ID* (or null) from the request's signed cookie
+2. Extract the *session-ID* (or null) from the request's signed cookie.
+ -------- DISCUSS: 'signed'? Since when are cookies signed???
3. If *session-ID* and *order-ID* is non-null and the storefront's
*session-payment-cache* contains the tuple (*order-ID*, *resource-name*,
*session-ID*),
- return to the client the content for *resource name*. **Terminate.**
-4. If the *session-ID* is null, assign a fresh session ID and set it in a
cookie to be sent with the response
+ return to the client the resource associated with *resource name*.
**Terminate.**
+4. If the *session-ID* is null, assign a fresh session ID and set it in a
cookie to be sent with the response.
5. If *order-ID* is null, create a new order for *resource-name* by doing a
``POST /private/orders`` to
the merchant backend. Store the new order ID as *order-ID*.
6. Check the status of the payment for *order-ID* under *session-ID* by doing
a ``GET /private/orders/{order-ID}?session_id={session-ID}``.
This results in the *order-status*, *refund-amount* and the
*client-order-status-URL*.
-7. If the *order-status* is paid and *refund-amount* is non-zero,
+7. If the *order-status* is paid and *refund-amount* is non-zero,
return to the client the refund info page for *resource name*.
**Terminate.**
+ ---------- DISCUSS: what is a 'refund info page'? What should be on it?
Explain better!
8. If the *order-status* is paid, store the tuple (*order-ID*,
*resource-name*, *session-ID*) in *session-payment-cache*
- and return to the client the content for *resource name*. **Terminate.**
+ and return to the client the resource associated with *resource name*.
**Terminate.**
9. Otherwise, the *order-status* is unpaid. Redirect the client to
*client-order-status-URL*. **Terminate.**
.. note::
- When a refund is given, the corresponding tuple must be removed from the
*session-page-cache*.
+ The use of a *session-page-cache* is optional, but recommended for
performance. When a refund is given, the corresponding tuple must be removed
from the *session-page-cache*.
Backend Private Order Status
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The merchant backend runs the following steps to generate the
*client-order-status-URL* when processing a request for ``GET
-/private/orders/{order-ID}?session_id={session-ID}``:
+/private/orders/{order-ID}?session_id={session-ID}&timeout_ms={timeout}``:
-1. Let *session-ID* be the session ID of the request (note: **not** the last
paid session ID)
-2. If *order-ID* does not identify an existing order, return an error.
**Terminate**.
+1. Let *session-ID* be the session ID of the request or null if not given
(note: **not** the last paid session ID)
+2. If *order-ID* does not identify an existing order, return a 40 Not Found
response. **Terminate**.
3. If *order-ID* identifies an order that is *unclaimed* and has claim token
*claim-token*, return the URL
::
{backendBaseUrl}/orders/{order-ID}?token={claim-token}&session_id={session-ID}
- **Terminate.**
-4. If *order-ID* identifies an order that is either *claimed* or *paid* and
has contract terms hash *contract-hash*, return the URL
+ (if no claim-token was generated, omit that parameter from the above URI).
**Terminate.**
+
+4. Here *order-ID* identifies an order that is *claimed*. If the order is
*unpaid*, wait until timeout or payment.
+
+5. If the order remains unpaid or was paid for a different *session-ID*,
obtain the contract terms hash *contract-hash* and return the URL
+
+ ::
+
+
{backendBaseUrl}/orders/{order-ID}?h_contract={contract-hash}&session_id={session-ID}
+
+ together with the status *unpaid*. (If *session-ID* is null, it does not
matter for which session the contract was paid.) **Terminate.**
+
+6. Here *order-ID* must now identify an order that is *paid* or *refunded*.
Obtain the contract terms hash *contract-hash* and return the URL
::
{backendBaseUrl}/orders/{order-ID}?h_contract={contract-hash}&session_id={session-ID}
+ together with the status *paid* or *refunded* (and if applicable, with
details about the applied refunds). **Terminate.**
+
+
+
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'!
----------
-1. If *order-ID* does not identify an existing order, render an error page.
**Terminate.**
-2. If *order-ID* identifies a paid order *ord*, run these steps:
+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:
- 1. If the *contract-hash* request parameter does not match the contract
terms hash of *ord*,
+ 1. If the *contract-hash* request parameter does not match the contract
terms hash of the order,
return a 403 Forbidden response. **Terminate.**
- 2. If *ord* has refunds that are not picked up, prompt the URI
+
+ 2. If the order has granted refunds that have not been obtained by the
wallet yet, prompt the URI
::
taler{proto_suffix}://refund/{/merchant_prefix*}/{order-id}/{session-id}
- Redirect to the *fulfillment-URL* of *ord* once the refund is picked up
and
- payment has been proven under *session-ID*.
+ The generated Web site should long-poll until all refunds have been
obtained,
+ then redirect to the *fulfillment-URL* of the order once the refunds
have been
+ 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?
- **Terminate.**
-
- 3. Prompt the URI
+ 3. Here the order has been paid. -------- what about refunded???
+ Prompt the URI ------ ???why? don't we redirect to fulfillment URL???????
::
taler{proto_suffix}://pay/{/merchant_prefix*}/{order-id}/{session-id}
- Redirect to the *fulfillment-URL* of *ord* once
+ Redirect to the *fulfillment-URL* of the order once
payment has been proven under *session-ID*.
**Terminate.**
-3. If *order-ID* identifies an unpaid order *ord*, run these steps:
-
- 1. If the the *claim-token* request parameter does not matches the claim
token of
- *ord*, return a 403 Forbidden response. **Terminate**.
- 2. Prompt the URI
+3. If *order-ID* identifies an *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?
------
-
taler{proto_suffix}://pay/{/merchant_prefix*}/{order-id}/{session-ID}?c={claim-token}
+ 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**.
- Redirect to the *fulfillment-URL* of *ord* once
- payment has been proven under *session-ID*.
+ 3. Prompt the URI
- If there is a non-null *already-paid-order-ID* for *session-ID*, redirect
- to the *fulfillment-URL* of *already-paid-order-ID*
+ ::
+
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.**
Discussion / Q&A
================
+Notes
+-----
+
+* The *timeout_ms* argument is expected to be ignored when generating HTML.
+ Long-polling simply makes no sense if a browser accesses the site directly.
+
+
Covered Scenarios
-----------------
@@ -144,6 +176,14 @@ Covered Scenarios
Problematic Scenarios
---------------------
+Link sharing
+^^^^^^^^^^^^
+
+Right now, sharing the /orders/{order-ID} link with the session ID will
+allow someone who did not purchase the order to still get a 'paid' response
+from the backend. (Will fulfillment then work? => Check!)
+
+
Bookmarks of Lost Purchases / Social Sharing of Fulfillment URLs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
- [taler-docs] branch master updated (069bf92 -> 551739c),
gnunet <=