diff options
author | Thien-Thi Nguyen <ttn@gnuvola.org> | 2021-03-24 07:00:00 -0400 |
---|---|---|
committer | Thien-Thi Nguyen <ttn@gnuvola.org> | 2021-03-24 07:00:00 -0400 |
commit | 5af47674fa39b81596771b48d66ef32f00e05ce4 (patch) | |
tree | 664965f5f81a29b71e6388c194a75b79ce3111f3 /taler-mcig.rst | |
parent | 9873d9a4cc3a4e405fa7a0281b6b121a1f9fdb56 (diff) | |
download | docs-5af47674fa39b81596771b48d66ef32f00e05ce4.tar.gz docs-5af47674fa39b81596771b48d66ef32f00e05ce4.tar.bz2 docs-5af47674fa39b81596771b48d66ef32f00e05ce4.zip |
add Scenario 1: Simple File Purchase
NB: This has quite a few FIXMEs still.
Diffstat (limited to 'taler-mcig.rst')
-rw-r--r-- | taler-mcig.rst | 174 |
1 files changed, 171 insertions, 3 deletions
diff --git a/taler-mcig.rst b/taler-mcig.rst index 9e4ec0ff..1497fedd 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). |