From 703f53d86187c71b2f37eea04f530074e6acfd79 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Wed, 10 Mar 2021 04:34:58 -0500 Subject: new file: taler-mcig.rst This is not (yet) added to the Table of Contents. --- taler-mcig.rst | 302 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 302 insertions(+) create mode 100644 taler-mcig.rst (limited to 'taler-mcig.rst') diff --git a/taler-mcig.rst b/taler-mcig.rst new file mode 100644 index 00000000..09d8b701 --- /dev/null +++ b/taler-mcig.rst @@ -0,0 +1,302 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2021 Taler Systems SA + + TALER is free software; you can redistribute it and/or modify it under the + terms of the GNU General Public License as published by the Free Software + Foundation; either version 2.1, or (at your option) any later version. + + TALER is distributed in the hope that it will be useful, but WITHOUT ANY + WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR + A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License along with + TALER; see the file COPYING. If not, see + + @author Thien-Thi Nguyen + + +Merchant/Customer Interaction Guide +################################### + +The audience for the Mechant/Customer Interaction Guide is the merchant +who wishes to set up a "web shop" that works with the Taler payment system. + + +Introduction +============ + +.. include:: frags/taler-payment-cycle.rst + +This guide focuses on step 4, the interaction between the customer and the +merchant. In particular, we first review two basic interaction flows +(with and without shopping cart), then describe Taler features involved in the +interaction, the decisions you (the merchant) must make, and +how to configure the Taler merchant backend to best support those decisions. +Lastly, we present protocol *traces* for various fictitious interaction flows. + + +Two Basic Flows +=============== + +.. index:: shopping cart experience +.. index:: individual product selection / purchase experience +.. index:: inventory management +.. index:: repurchase detection / prevention + +There are two basic payment flows, the first involving a shopping cart, +and the second, without (individual product selection / purchase). +We distinguish these because for some purchases, a shopping cart is overkill. +In either case, Taler can integrate +with your *inventory management* system. +Additionally, Taler offers *repurchase detection / prevention*, +most suitable for digital goods. + +In the shopping cart experience, you first offer a product on the website. +The customer adds the product to their shopping cart, at which point you may +optionally *lock* the product in the inventory system for a certain period of +time. +The accumulated set of products in the shopping cart is the *order*. +This process repeats until the customer is ready to move to the +*checkout* phase. + +At checkout, you may optionally support different payment methods (and make +this choice available to the customer) for the order. +This guide assumes you and the customer agree to use the Taler payment system. + +At this point, you generate a *contract* and present it to the customer for +authorization. +The contract includes: +- some kind of identification for the selected product(s); +- an itemized price list; +- applicable taxes and fees; +- (optional) information on how you deal with *forgettable customer details*; +- (optional) the duration of the lock on the product(s); +- (optional) a *claim token* that the customer can use later; +- (optional) information on the *refund deadline*; +- (optional) information on the the *auto-refund period* (how long does + the wallet check for refunds without user prompting for it); +- the total amount due; +- the *duration* of the offer + (how long the customer has to authorize before timeout). + +If the customer does nothing (timeout / the contract expires), +you *unlock* the product(s) and end the transaction. + +On the other hand, if the customer authorizes the contract, +the customer's wallet transfers payment coins to you, +and you display to the customer the *fulfillment URI*. + +The individual product selection / purchase experience is like the shopping +cart experience with the following exceptions: +- there is no shopping cart -- the order is solely the selected product; +- Taler payment method is assumed; +- customer selection moves directly to checkout; +- there is *repurchase detection / prevention* (for digital products). + + +Taler Details +============= + +This section describes aspects of Taler involved +in the basic payment flows in more detail. +Each aspect also includes a backend API call that you can use +in the next section. + +**product locking** + Taler can integrate with your inventory system to set aside + a certain quantity of a product for some duration of time. + This is called *product locking*. + This is useful for physical goods, or for goods that have a limited supply, + such as airline tickets. + Even for digital goods, product locking may be useful to effect exclusivity. + + To lock a product, use: + :http:post:`[/instances/$INSTANCE]/private/products/$PRODUCT_ID/lock`, + specifying a ``duration`` and a ``quantity``. + + If the customer removes a product from the shopping cart, you can *unlock* + the product by using the same API call, specifying a ``quantity`` of 0 (zero). + (Products are also unlocked automatically on timeout / contract expiration.) + +**taxes** + The default taxes for each product is part of the product ``price`` + maintained by the backend. + This is set when the product is added to the inventory, + prior to any customer purchase experience + (see :http:post:`[/instances/$INSTANCE]/private/products`, + :http:get:`[/instnaces/$INSTANCE]/private/products`, + and :http:get:`[/instances/$INSTANCE]/private/products/$PRODUCT_ID`). + + FIXME: Front-end override? + +**fees** + The Taler protocol charges a *deposit fee* (see step 5, above), + which you may choose to pay or to pass on to the customer. + This can be configured to a maximum amount, per customer. + + You can set ``default_max_deposit_fee`` in :http:post:`/private/instances`, + and ``max_fee`` in the contract. + + There is also the *wire fee* (see step 6, above), + which you may choose to pay or to pass on to the customer. + + You can set ``default_max_wire_fee`` in :http:post:`/private/instances`, + and ``max_wire_fee`` in the contract. + If unspecified, the default value is zero (meaning you bear the entire fee). + + You can *amortize* the wire fee across a number of customers + by setting ``default_wire_fee_amortization`` in :http:post:`/private/instances`, + and ``wire_fee_amortization`` in the contract. + This is the number of customer transactions over which you expect to + amortize wire fees on average. + If unspecified, the default value is one. + + .. Note:: :http:post:`/private/instances` must be done at + instance-setup time (prior to any purchase). + +**forgettable customer details** + Although Taler allows the customer to remain anonymous, you may need to + collect customer details (e.g. for shipping). + Taler has support for forgetting these details, to comply with GDPR + (for example). + This can occur even in the face of refunds (see below). + + To forget a set of details, first the details that are to be forgotten + must be marked (FIXME: How?, When?). + Then, you can use: + :http:patch:`[/instances/$INSTANCE]/private/orders/$ORDER_ID/forget` + to forget those details. + +**claim token** + The claim token is a sort of handle on the order and its payment. + With it, the customer can access the fulfillment URI from a different + device than the one where the wallet is installed. + + By default, Taler creates a claim token for each order. + To disable this, you can specify ``create_token`` to be ``False`` + in :http:post:`[/instances/$INSTANCE]/private/orders`. + +**refund deadline** + The refund deadline specifies the time after which you will prohibit + refunds. + Refunds may be full or partial. + Refunds do not require customer details. + You can configure the deadline to expire immediately to effect + an "all sales are final" policy. + + To set the deadline, specify ``refund_delay`` + in :http:post:`[/instances/$INSTANCE]/private/orders`. + To disable refunds altogether, omit this field. + +**auto-refund period** + The Taler protocol can automatically offer refunds to the customer's + wallet without their explicit prompting during the auto-refund period. + FIXME: When is this useful? + + FIXME: Is this the same as the refund deadline? + + FIXME: API call? + +**repurchase detection / prevention** + Taler can detect a repurchase attempt and prevent it from going through. + This feature allows customers to purchase a digital good only once, + but to later access the same digital good repeatedly (e.g. reload + in browser, after network trouble, etc.) without having to pay again. + + This feature is automatic in the protocol; + you do not need to do anything to enable it. + +**fulfillment URI** + This may be the actual product (digital goods), + or a tracking URL (physical goods). + If you issue a claim token with the contract, the customer can + access the fulfillment URI from a different device than the + one where the wallet is installed. + + The fulfillment URI is normally included in the contract. + You specify it in :http:post:`[/instances/$INSTANCE]/private/orders`. + + +Sample Interaction Traces +========================= + +In the following descriptions, ``C`` stands for *customer*, ``W`` stands for +*customer's wallet*, ``M`` stands for *merchant* (you), and ``E`` stands for +*exchange*. +Unless otherwise noted, all API calls are directed toward the Taler backend. + +Also, all the traces share the initial pre-sales configuration step. + + +Pre-Sales Configuration +----------------------- + +In the pre-sales configuration step, you set up the *default instance*, +and add products to the inventory. + +M: :http:post:`/private/instances` + +.. code-block:: json + + // InstanceConfigurationMessage + { + "payto_uris": ["payto://iban/CH9300762011623852957"], + "id": "default", + "name": "Pretty Pianos", + "auth": + // InstanceAuthConfigurationMessage + { + "method": "external", + "token": "secret-token:eighty-eight-keys" + }, + "default_max_wire_fee": "KUDOS:5.0", + "default_wire_fee_amortization": 1, + "default_max_deposit_fee": "KUDOS:10.0", + "default_wire_transfer_delay": "2 days", + "default_pay_delay": "5 hours" + } + // (backend returns 204 No content) + + // FIXME: What about InstanceAuthConfigurationMessage? + +The fictitious store, Pretty Pianos, has only two products: +- pianos (physical good); +- *Beethoven Sonatas* (sheet music PDF files, digital good). + +M: :http:post:`/instances/default/private/products` + +.. code-block:: json + + // ProductAddDetail + { + "product_id": "p001", + "description": "piano", + "unit": "unit", // FIXME: What is a better unit? + "price": "KUDOS:20000.0", + "taxes": [], // FIXME: What is a Tax object? + "total_stock": 3, + "next_restock": "2021-04-22" + } + // (backend returns 204 No content) + +M: :http:post:`/instances/default/private/products` + +.. code-block:: json + + // ProductAddDetail + { + "product_id": "f001", + "description": "Beethoven Sonatas", + "unit": "file", // FIXME: What is a better unit? + "price": "KUDOS:9.87", + "taxes": [], // FIXME: What is a Tax object? + "next_restock": "0000-00-00" + } + // (backend returns 204 No content) + + +Scenarios +--------- + +TODO/FIXME: Add various scenarios (including JSON). -- cgit v1.2.3