document merchant MUST templates

1 files changed, 73 insertions, 5 deletions

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