[taler-docs] branch master updated: add Scenario 1: Simple File Purchase

[gnunet]

This is an automated email from the git hooks/post-receive script.

ttn pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 5af4767  add Scenario 1: Simple File Purchase
5af4767 is described below

commit 5af47674fa39b81596771b48d66ef32f00e05ce4
Author: Thien-Thi Nguyen <ttn@gnuvola.org>
AuthorDate: Wed Mar 24 07:00:00 2021 -0400

    add Scenario 1: Simple File Purchase
    
    NB: This has quite a few FIXMEs still.
---
 taler-mcig.rst | 174 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 171 insertions(+), 3 deletions(-)

diff --git a/taler-mcig.rst b/taler-mcig.rst
index 9e4ec0f..1497fed 100644
--- a/taler-mcig.rst
+++ b/taler-mcig.rst
@@ -358,7 +358,175 @@ This is because the ``total_stock`` field has value 
``-1`` (meaning "infinite")
 since the product is a PDF file.
 
 
-Scenarios
----------
+Scenario 1: Simple File Purchase
+--------------------------------
 
-TODO/FIXME: Add various scenarios (including JSON).
+The first scenario is a simple file purchase, without shopping cart,
+similar to the `GNU Essay demo <https://shop.demo.taler.net/en/>`_ experience.
+
+.. We hardcode "en/" for now because support for other
+   languages is not yet available (at time of writing).
+   (FIXME: Drop "en/" when other languages are supported.)
+
+Because there are infinite supplies of product ``f001``,
+there is really no need for inventory management.
+However, you choose to anyway generate a separate order ID
+in the backend for accounting purposes.
+Also, since the product is an easily reproduced digital good,
+you decline to offer the customer the ability to select a "quantity"
+other than 1 (one), and decide that "all sales are final"
+(no refund possible).
+On the other hand, you wish to enable repurchase detection /
+prevention feature, so that once customers pay for the PDF file,
+they need never pay again for it.
+
+When the customer clicks on the product's "buy" button,
+you first POST to ``/private/orders`` to create an order:
+
+M: :http:post:`/instances/default/private/orders`
+
+.. code-block:: javascript
+
+   // PostOrderRequest
+   {
+     "order":
+     // Order (MinimalOrderDetail)
+     {
+       "amount": "KUDOS:9.87",
+       "summary": "Beethoven Sonatas",
+       "fulfillment_URI": "https://example.com/f001?${ORDER_ID}";
+     },
+     "create_token": true
+   }
+
+Notes:
+- There is no ``refund_delay`` field (no refunds possible).
+- We show the ``create_token`` field with value ``true`` even though
+  that is the default (for illustrative purposes).
+- The ``order`` value is actually a ``MinimalOrderDetail`` object.
+- The ``fulfillment_URI`` value includes the product ID and the literal
+  string ``${ORDER_ID}``, to be replaced by the backend-generated order ID.
+
+The backend returns ``200 OK`` with the body:
+
+.. code-block:: javascript
+
+   // PostOrderResponse
+   {
+     "order_id": "G93420934823",
+     "token": "TEUFHEFBQALK"
+   }
+
+Notes:
+- The backend-generated order ID is ``G93420934823``.
+- The claim token is ``TEUFHEFBQALK``.
+
+(FIXME: Replace w/ more realistic examples?)
+
+Now that there is an order in the system, the wallet *claims* the order.
+
+W: :http:post:`/orders/G93420934823/claim`
+
+.. code-block:: javascript
+
+   // ClaimRequest
+   {
+     "nonce": "lksjdflaksjfdlaksjf",
+     "token": "TEUFHEFBQALK"
+   }
+
+Notes:
+- The ``nonce`` value is a randomly-generated string.
+- The POST endpoint includes the order ID ``G93420934823``.
+- The ``token`` value is the claim token ``TEUFHEFBQALK``
+  received in the ``PostOrderResponse``.
+
+The backend returns ``200 OK`` with body:
+
+.. code-block:: javascript
+
+   // ContractTerms
+   {
+     "summary": "one copy of Beethoven Sonatas",
+     "order_id": "G93420934823",
+     "amount": "KUDOS:9.87000000",
+     "fulfillment_url": "https://example.com/f001?G93420934823";,
+     "max_fee": FIXME,
+     "max_wire_fee": FIXME,
+     "wire_fee_amortization": 1,
+     "products": [
+       // Product
+       {
+         "product_id": "f001",
+         "description": "Beethoven Sonatas"
+       }
+     ],
+     "timestamp": "2021-03-23T22:14:25",
+     "refund_deadline": "2021-03-23T22:14:25",
+     "pay_deadline": "2021-03-23T22:15:25",
+     "wire_transfer_deadline": "2021-03-23T22:16:25",
+     "merchant_pub": FIXME,
+     "merchant_base_url": "https://example.com/";,
+     "merchant":
+       // Merchant
+       {
+       },
+     "h_wire": FIXME,
+     "wire_method": FIXME,
+     "auditors": [
+       // Auditor
+     ],
+     "exchanges": [
+       // Exchange
+     ],
+     "nonce": "lksjdflaksjfdlaksjf"
+   }
+
+Notes:
+- The ``order_id`` value is the one given in the ``PostOrderResponse``.
+- The ``refund_deadline`` value is the same as the ``timestamp`` value
+  (no refunds possible).
+- The ``pay_deadline`` value is one minute after the ``timestamp`` value.
+- The ``wire_transfer_deadline`` value is two minutes after
+  the ``timestamp`` value.
+- The ``products`` value is a list of one element (one ``Product`` object),
+  which omits the ``price`` field since that is included in the
+  ``ContractTerms.amount`` value.  Also, its ``quantity`` defaults to 1 (one).
+- The ``nonce`` value is the same one specified by the wallet.
+
+At this point, the wallet displays the contract terms (or a subset of them)
+to the customer, who now has the option to accept the contract or reject it
+(either explicitly by pressing a "cancel" button, or implicitly by waiting
+for the offer to time out).
+
+The customer accepts the contract:
+
+W: :http:post:`/orders/G93420934823/pay`
+
+.. code-block:: javascript
+
+   // PayRequest
+   {
+     "coins": FIXME,
+     "session_id": FIXME
+   }
+
+The backend returns ``200 OK`` with body:
+
+.. code-block:: javascript
+
+   // PaymentResponse
+   {
+     "sig": FIXME
+   }
+
+FIXME: At this point, does the wallet need to query (status)?
+Also, does the frontend need to do anything else?
+
+The wallet then redirects to the fulfillment URI, which displays
+(or makes available for download) the PDF file "Beethoven Sonatas".
+
+
+
+
+TODO/FIXME: Add more scenarios (including JSON).

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.