summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorThien-Thi Nguyen <ttn@gnuvola.org>2021-03-24 07:00:00 -0400
committerThien-Thi Nguyen <ttn@gnuvola.org>2021-03-24 07:00:00 -0400
commit5af47674fa39b81596771b48d66ef32f00e05ce4 (patch)
tree664965f5f81a29b71e6388c194a75b79ce3111f3
parent9873d9a4cc3a4e405fa7a0281b6b121a1f9fdb56 (diff)
downloaddocs-5af47674fa39b81596771b48d66ef32f00e05ce4.tar.gz
docs-5af47674fa39b81596771b48d66ef32f00e05ce4.tar.bz2
docs-5af47674fa39b81596771b48d66ef32f00e05ce4.zip
add Scenario 1: Simple File Purchase
NB: This has quite a few FIXMEs still.
-rw-r--r--taler-mcig.rst174
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).