new file: taler-mcig.rst

This is not (yet) added to the Table of Contents.

1 files changed, 302 insertions, 0 deletions

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 <http://www.gnu.org/licenses/>
+
+  @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).