From 3ec3cb94f02af7f44ef87a980965a1f1ea3b8496 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 17 Feb 2024 19:32:46 +0100 Subject: document merchant MUST templates --- taler-exchange-manual.rst | 32 +++++++++---------- taler-merchant-manual.rst | 78 ++++++++++++++++++++++++++++++++++++++++++++--- 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 +`__, 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 ------------ -- cgit v1.2.3