expand terminology section

1 files changed, 73 insertions, 0 deletions

diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index 2d674014..072f4ad7 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -260,6 +260,61 @@ After the *legal expiration* (by default: a decade), contract information is
 deleted when running the garbage collector using ``taler-merchant-dbinit``.
 
 
+.. _template:
+
+Templates
+---------
+
+.. index:: Template
+
+Usually, a merchant must use an authenticated endpoint to create an order and
+then share the link to the order with a wallet. Templates are a mechanism that
+allows wallets to create their own orders directly, using a public endpoint.
+The template fixes some properties of the contracts created from it, while
+other details may be left for the customer to provide.  Templates are useful
+in cases where the point-of-sale of a merchant is offline (and thus cannot
+setup an order), or even in cases where a simple static QR code is desired to
+accept payments or donations.
+
+When generating a template, the "summary" text of the contract and the
+"amount" to be paid by the customer can be fixed or left for the customer to
+specify.  If the customer is expected to provide either or both of these
+values, the template link (or QR code) can specify a default value. For
+example, a cafeteria with a fixed price lunch may use a "lunch" template with
+both values fixed to the lunch price and the "lunch" product, a bakery might
+fix the summary to "baked goods" but allow the customer to enter the amount
+based on the total price of the items being bought, and a charity may allow
+donating an arbitrary amount and summary message while also suggesting default
+values.
+
+If an offline merchant wants to confirm that a customer did actually pay the
+agreed amount using an order derived from a template, they can associate an
+OTP device with the template.
+
+
+.. _otp-device:
+
+OTP Devices
+-----------
+
+.. index:: OTP
+.. index:: TOTP
+
+A One-Time-Password (OTP) generator is a device or application that generates
+a 4 to 8 digit code typically used for authentication. The widely used TOTP
+standard is described in `RFC 6238 <https://www.rfc-editor.org/rfc/rfc6238>`_.
+For GNU Taler merchant backends, OTP devices are used as a way to assure a
+merchant without network connectivity that a customer made a digital
+payment. The idea is described in depth in our `SUERF Policy Brief
+<https://www.suerf.org/suer-policy-brief/69851/practical-offline-payments-using-one-time-passcodes>`_.
+To use this method, a merchant must configure the OTP device's shared secret
+in the merchant backend, and then associate the OTP device with a
+:ref:`template`.  Once the customer has paid, they are given a list of OTP
+codes which must be shown to the merchant who can check that at least one of
+the codes matches their OTP device, proving that the customer made the
+payment.
+
+
 Transfers
 ---------
 
@@ -275,6 +330,9 @@ backend with wire *transfer* data that specifies the *wire transfer subject*
 and the amount that was received. Given this information, the backend can
 detect and report any irregularities that might arise.
 
+
+.. _rewards:
+
 Rewards
 -------
 
@@ -296,6 +354,8 @@ the reward.
     if they see compliance issues). In this case, the reward feature will
     not be available.
 
+.. _merchant-reserves:
+
 
 Reserves
 --------
@@ -315,6 +375,19 @@ While exchange APIs exists to (1) explicitly *open* a reserve to prevent it
 from being automatically closed and to (2) explicitly *close* a reserve at any
 time, the current merchant backend does not make use of these APIs.
 
+Webhooks
+--------
+
+.. index:: webhook
+
+A webhook is a pre-defined HTTP request that the GNU Taler merchant backend
+will make upon certain events, such as an order being paid or refunded. When
+the configured event happens, the merchant backend will make an HTTP request
+to the endpoint configured in the webhook configuration, possibly sending
+selected data about the event to the respective Web service. Webhooks can be
+used to trigger additional business logic outside of the GNU Taler merchant
+backend.
+
 
 Installation
 ============