clarify templating API

1 files changed, 45 insertions, 6 deletions

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 526c4532..64a7f943 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -1,6 +1,6 @@
 ..
   This file is part of GNU TALER.
-  Copyright (C) 2014-2020 Taler Systems SA
+  Copyright (C) 2014-2023 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU Affero General Public License as published by the Free Software
@@ -2986,8 +2986,48 @@ Checking tip status
 Template
 --------
 
-The template is a backend feature that is used to create an order. We use the template to have some static information that cannot be changed by the customer.
-The template is private and allows us to be flexible. The private template allows for greater security and allows us to have a minimum information we need for each store.
+The template is a backend feature that is used to allow wallets to create an
+order. This is useful in cases where a store does not have Internet
+connectivity or where a Web site wants to enable payments on a purely static
+Web page (for example to collect donations). In these cases, the GNU Taler
+wallet can be used to setup an order (and then of course pay for it).
+
+The template itself primarily provides order details that cannot be be changed
+by the customer when the wallet creates the order.  The idea is that the user
+*may* be prompted to enter certain information, such as the amount to be paid,
+or the order summary (as a reminder to themselves or a message to the store),
+while the template provides all of the other contract details.
+
+The typical user-experience with templatates is that the user first scans a QR
+code or clicks on a taler://-URI which contains a ``pay-template`` (see `LSD
+0006 <https://lsd.gnunet.org/lsd0006/>`). The URI specifies which values the
+user should supply, currently either nothing, the amount, the order summary or
+both.  The URI may also specify defaults or partial defaults for those
+values. After the user has supplied those values, the wallet will use the
+public template API to create the order, then fetch the order details, and
+proceed as if it had been given the respective ``pay`` URI in the first place:
+show the full contract details and allow the user to make a payment.  If the
+user chooses to aborts the payment, the wallet should give the user the
+opportunity to edit the values and create another order with different values.
+If the template does not include any values that the user is allowed to edit
+(so it is basically a fixed contract), the wallet should directly create the
+order and immediately proceed to the contract acceptance dialog.
+
+The business process for the templating API is also pretty simple. First, the
+private API is used to setup (or edit) the template, providing all of the
+contract terms that subsequently cannot be changed by the customer/wallet.
+This template data is then stored under the template ID which can be freely
+chosen.  The SPA should also make it easy for the merchant to convert the
+template ID into a taler://-URI and/or QR code. Here, the merchant must
+additionally specify the defaults (if any) for the customer-editable values.
+Afterwards, the merchant can print out the QR code for display at the store,
+add a link to the taler://-URI and/or embed the respective QR-code image into
+their Web page.
+
+To receive a payment confirmation, the mechant may choose to configure a
+webhook in the merchant backend on the ``pay`` action, for example to send an
+SMS to their mobile phone.  For points-of-sale without a mobile phone or
+Internet connectivity, the TBD mechanism can also be used to confirm payments.
 
 
 
@@ -3021,10 +3061,9 @@ Adding templates
       // Human-readable description for the template.
       template_description: string;
 
-      // A base64-encoded image selected by the merchant.
+      // A base64-encoded key of the point-of-sale.
       // This parameter is optional.
-      // We are not sure about it.
-      image?: ImageDataUrl;
+      pos_key?: string;
 
       // Additional information in a separate template.
       template_contract: TemplateContractDetails;