taler
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Taler] (docs) WIP Merchant/Customer Interaction Guide


From: Thien-Thi Nguyen
Subject: [Taler] (docs) WIP Merchant/Customer Interaction Guide
Date: Fri, 26 Feb 2021 02:26:51 -0500
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux)

Please find attached the WIP Merchant/Customer Interaction Guide
(ultimately intended for "web shops" that want to implement a
Taler-compliant frontend):
$Id: mcig.rst,v 1.29 2021/02/26 07:14:36 ttn Exp $

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 describe the decisions the merchant must make and
how to configure the Taler merchant backend to best support those decisions.


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 in order to show how Taler can integrate
with your *inventory management* system.
Additionally, Taler offers *repurchase detection / prevention*,
most suitable for digital goods bought via the second flow.

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.
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).
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 contract concludes with the total amount due and 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;
- Taler payment method is assumed;
- customer selection moves directly to checkout;
- there is *repurchase detection / prevention* (for digital products).


Contract Details
================

This section describes the components of the contract in more detail.
Each element also includes a configuration variable 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.

  FIXME: cfg var?

**taxes**
  FIXME: How does Taler integrate with tax-computation systems?

  FIXME: cfg var?

**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.
  FIXME: What about *amortization*?

  There is also the *wire fee* (step 6), which is borne entirely by you.

  FIXME: cfg var?

**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).

  FIXME: cfg var?

**claim token**
  The claim token is a sort of handle on the contract and its payment.
  With it, the customer can access the fulfillment URI from a different
  device than the one where the wallet is installed.

  FIXME: cfg var?

**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.

  FIXME: cfg var?

**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: cfg var?

**repurchase detection / prevention**
  Taler can detect a repurchase attempt and prevent it from going through.
  This is useful for digital goods, primarily.

  FIXME: cfg var?

**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.

  FIXME: cfg var?
I'm mailing this out half-complete in order to request feedback
/ discussion on it: structure, content, etc.

First question: Is there a good place for wip documents in
docs.git?  Some place that is not yet "published" but is easy to
refer to (instead of emailing drafts around like the old days).

FWIW, i attach here the outline i've been working from:
$Id: various-payment-flows.org,v 1.45 2021/02/14 21:51:42 ttn Exp $

* shopping cart experience
  - seller offers product on website
  - buyer adds to shopping cart
  - (opt) seller "locks" product
  - repeat
  - <<at checkout>>
    - (opt) buyer selects Taler payment method
    - (opt) seller generates claim-token (part of contract)
    - seller sends contract to wallet -- see [[contract details]]
    - if buyer accepts (authorizes) contract
      - wallet transfers payment coins to seller
      - seller redirects to fulfillment URI
    - if timeout
      - (opt) seller "unlocks" product

* individual product selection/purchase experience
  This is like [[shopping cart experience]] except:
  - no shopping cart
  - Taler payment method assumed
  - "repeat" applies to entire [[at checkout]]
  - there is repurchase detection (digital products)

* (opt) refund experience
  - seller authorizes refund
  - seller notifies buyer of refund
  - buyer updates wallet
  - (opt) seller adjusts inventory

* summary of seller choices
  - Taler as payment method
  - product locking
  - claim-token generation
  - inventory management
  - repurchase detection
  - refund authorization
  - PII dropping (can happen anytime)

* contract details
  In addition to (some) elements in [[summary of seller choices]], there are:
  - refund deadline (how long are refunds possible)
  - offer expiration (how long are locks held)
  - fees covered by merchant, amortization
  - repurchase detection (on/off, how!)
  - forgettable details marking
  - auto-refund period (how long does the wallet
    check for refunds without user prompting for it)
Comments on that are welcome, as well.

-- 
Thien-Thi Nguyen -----------------------------------------------
 (defun responsep (query)               ; (2021) Software Libero
   (pcase (context query)               ;       = Dissenso Etico
     (`(technical ,ml) (correctp ml))
     ...))                              748E A0E8 1CB8 A748 9BFA
--------------------------------------- 6CE4 6703 2224 4C80 7502

Attachment: signature.asc
Description: PGP signature


reply via email to

[Prev in Thread] Current Thread [Next in Thread]