document merchant MUST templates

2 files changed, 89 insertions, 21 deletions

diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
index 088f71d2..ecb88807 100644
--- a/taler-exchange-manual.rst
+++ b/taler-exchange-manual.rst
@@ -1953,7 +1953,7 @@ provided language preferences in the HTTP header and the respective language
 exists, the correct language will be automatically served.
 
 The following subsections give details about each of the templates. Most
-subsection title are the ``$NAME`` of the respective template.
+subsection titles are the ``$NAME`` of the respective template.
 
 
 Generic Errors Templates
@@ -1985,7 +1985,7 @@ kycaid-invalid-request
 The KYCaid plugin does not support requests to the
 ``/kyc-proof/`` endpoint (HTTP 400 bad request).
 
-This templates is instantiated using the following information:
+This template is instantiated using the following information:
 
   * ec: Integer; numeric Taler error code, should be shown to indicate the
     error compactly for reporting to developers
@@ -2008,7 +2008,7 @@ The OAuth2 server said that the request was not
 properly authenticated (HTTP 403 Forbidden).
 
 
-This templates is instantiated using the following information:
+This template is instantiated using the following information:
 
   * ec: Integer; numeric Taler error code, should be shown to indicate the
     error compactly for reporting to developers
@@ -2024,7 +2024,7 @@ The OAuth2 server refused to return the KYC data
 because the authorization code provided was
 invalid (HTTP 403 Forbidden).
 
-This templates is instantiated using the following information:
+This template is instantiated using the following information:
 
   * ec: Integer; numeric Taler error code, should be shown to indicate the
     error compactly for reporting to developers
@@ -2043,7 +2043,7 @@ oauth2-authorization-failure-malformed
 The server refused the authorization, but then provided
 a malformed response (HTTP 502 Bad Gateway).
 
-This templates is instantiated using the following information:
+This template is instantiated using the following information:
 
   * ec: Integer; numeric Taler error code, should be shown to indicate the
     error compactly for reporting to developers
@@ -2061,7 +2061,7 @@ oauth2-bad-request
 
 The client made an invalid request (HTTP 400 Bad Request).
 
-This templates is instantiated using the following information:
+This template is instantiated using the following information:
 
   * ec: Integer; numeric Taler error code, should be shown to indicate the
     error compactly for reporting to developers
@@ -2078,7 +2078,7 @@ oauth2-conversion-failure
 Converting the KYC data into the exchange's internal
 format failed (HTTP 502 Bad Gateway).
 
-This templates is instantiated using the following information:
+This template is instantiated using the following information:
 
   * ec: Integer; numeric Taler error code, should be shown to indicate the
     error compactly for reporting to developers
@@ -2101,7 +2101,7 @@ oauth2-provider-failure
 We did not get an acceptable response from the OAuth2
 provider (HTTP 502 Bad Gateway).
 
-This templates is instantiated using the following information:
+This template is instantiated using the following information:
 
   * ec: Integer; numeric Taler error code, should be shown to indicate the
     error compactly for reporting to developers
@@ -2117,7 +2117,7 @@ persona-exchange-unauthorized
 
 The Persona server refused our request (HTTP 403 Forbidden from Persona, returned as a HTTP 502 Bad Gateway).
 
-This templates is instantiated using the following information:
+This template is instantiated using the following information:
 
   * ec: Integer; numeric Taler error code, should be shown to indicate the
     error compactly for reporting to developers
@@ -2135,7 +2135,7 @@ persona-load-failure
 
 The Persona server refused our request (HTTP 429 Too Many Requests from Persona, returned as a HTTP 503 Service Unavailable).
 
-This templates is instantiated using the following information:
+This template is instantiated using the following information:
 
   * ec: Integer; numeric Taler error code, should be shown to indicate the
     error compactly for reporting to developers
@@ -2153,7 +2153,7 @@ persona-exchange-unpaid
 
 The Persona server refused our request (HTTP 402 Payment REquired from Persona, returned as a HTTP 503 Service Unavailable).
 
-This templates is instantiated using the following information:
+This template is instantiated using the following information:
 
   * ec: Integer; numeric Taler error code, should be shown to indicate the
     error compactly for reporting to developers
@@ -2172,7 +2172,7 @@ persona-logic-failure
 
 The Persona server refused our request (HTTP 400, 403, 409, 422 from Persona, returned as a HTTP 502 Bad Gateway).
 
-This templates is instantiated using the following information:
+This template is instantiated using the following information:
 
   * ec: Integer; numeric Taler error code, should be shown to indicate the
     error compactly for reporting to developers
@@ -2191,7 +2191,7 @@ persona-invalid-response
 The Persona server refused our request in an
 unexpected way; returned as a HTTP 502 Bad Gateway.
 
-This templates is instantiated using the following information:
+This template is instantiated using the following information:
 
   * ec: Integer; numeric Taler error code, should be shown to indicate the
     error compactly for reporting to developers
@@ -2209,7 +2209,7 @@ persona-network-timeout
 
 The Persona server refused our request (HTTP 408 from Persona, returned as a HTTP 504 Gateway Timeout).
 
-This templates is instantiated using the following information:
+This template is instantiated using the following information:
 
   * ec: Integer; numeric Taler error code, should be shown to indicate the
     error compactly for reporting to developers
@@ -2227,7 +2227,7 @@ persona-kyc-failed
 
 The Persona server indicated a problem with the KYC process, saying it was not completed.
 
-This templates is instantiated using the following information:
+This template is instantiated using the following information:
 
   * persona_inquiry_id: String; internal ID of the inquiry within Persona, useful for further diagnostics by staff
 
@@ -2240,7 +2240,7 @@ persona-provider-failure
 
 The Persona server refused our request (HTTP 500 from Persona, returned as a HTTP 502 Bad Gateway).
 
-This templates is instantiated using the following information:
+This template is instantiated using the following information:
 
   * ec: Integer; numeric Taler error code, should be shown to indicate the
     error compactly for reporting to developers
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index 97a422d0..d1520d02 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -1114,15 +1114,83 @@ Legal conditions for using the service
 
 .. include:: frags/legal.rst
 
+.. _MerchantTemplateCustomization:
 
-Mustach HTML Templates
+Template Customization
 ----------------------
 
-The installation process will install various HTML templates to be served
-to trigger the wallet interaction. You may change those templates to your
-own design. The templating language used is Mustach, and the templates
-are in the ``share/taler/merchant/templates/`` directory.
+The installation process will install various HTML templates to be served to
+trigger the wallet interaction. You may change those templates to your own
+design. The templating language used is `Mustach
+<https://gitlab.com/jbol/mustach>`__, and the templates are in the
+``share/taler/merchant/templates/`` directory.
 
+The file names must be of the form ``$NAME.$LANG.must`` where ``$NAME`` is the
+name of the template and ``$LANG`` is the 2-letter language code of the
+template. English templates must exist and will be used as a fallback.  If the
+browser (user-agent) has provided language preferences in the HTTP header and
+the respective language exists, the correct language will be automatically
+served.
+
+The following subsections give details about each of the templates. The
+subsection titles are the ``$NAME`` of the respective template.
+
+request_payment
+^^^^^^^^^^^^^^^
+
+Page shown to request the user to make a payment.
+
+This template is instantiated using the following information:
+
+  * taler_pay_uri: String; the ``taler://pay/`` URI that must be given
+    to the wallet to initiate the payment
+
+  * taler_pay_qrcode_svg: Image; an SVG image of the QR code with the
+    ``taler_pay_uri``.
+
+  * order_summary: String; a text summarizing the order
+
+  * order_status_url: URL of the merchant backend where the order status
+    can be found, useful for long-polling to check if the order has been paid
+
+
+offer_refund
+^^^^^^^^^^^^
+
+Page shown to offer a customer a refund.
+
+This template is instantiated using the following information:
+
+  * taler_refund_uri: String; the ``taler://pay/`` URI that must be given
+    to the wallet to initiate the payment
+
+  * taler_refund_qrcode_svg: Image; an SVG image of the QR code with the
+    ``taler_pay_uri``.
+
+  * refund_amount: Amount; how much did the merchant refund
+
+  * refund_taken: Amount; how much did the customer already take back in refunds
+
+  * order_summary: String; a text summarizing the order
+
+
+
+show_order_details
+^^^^^^^^^^^^^^^^^^
+
+Page shown to the user when they go back to the payment page but
+no payment is required and no refund is present.
+
+This template is instantiated using the following information:
+
+  * order_summary: String; a text summarizing the order
+
+  * contract_terms: Object; the full contract terms (shoud probably
+    not be shown in full!)
+
+  * refund_amount: Amount; how much did the merchant refund
+
+  * refund_taken: Amount; how much did the customer already take back in refunds
 
 Static files
 ------------