update taler:// URI spec

1 files changed, 58 insertions, 84 deletions

diff --git a/core/taler-uri.rst b/core/taler-uri.rst
index 6d59bda7..765c6dc2 100644
--- a/core/taler-uri.rst
+++ b/core/taler-uri.rst
@@ -4,11 +4,15 @@
 The taler:// URI scheme
 =======================
 
-The ``taler`` URI scheme represents actions that are processed by a Taler wallet.  The basic syntax is as follows:
+The ``taler`` URI scheme represents actions that are processed by a Taler
+wallet.  This document uses `RFC 6570 URI templates
+<https://tools.ietf.org/html/rfc6570>`__ to describe the syntax.
+
+The basic syntax is as follows:
 
 .. code:: none
 
-  'taler://' action '/' params
+  taler://{action}/{+rest}
 
 --------------------
 Requesting a Payment
@@ -19,41 +23,55 @@ Payments are requested with the ``pay`` action.  The parameters are a hierarchic
 
 .. code:: none
 
-  'taler://pay/' merchant-host '/' merchant-public-prefix '/' merchant-instance '/' orderId [ '/' sessionId ]
-
-The components ``merchant-host``, ``merchant-public-prefix`` and ``orderId`` identify the URL that is used to claim the contract
-for the payment request.
+  taler://pay/{merchant_host}{/merchant_prefix_path*}/{order_id}/{session_id}{?insecure}{#ssid}
 
-To make the URI shorter (which is important for QR code payments), ``merchant-public-prefix`` and/or ``merchant-instance`` can be substituted by ``-`` (minus) to get a default value
-for these components:
+* `merchant_host` is the hostname of the merchant
+* `merchant_prefix_path` is an optional list of path components that identifies the path prefix of the merchant base URL.
+* `order_id` is the order ID that the customer is asked to pay for
+* `session_id` is the optional session ID under which the payment takes place
+* `insecure` is an optional query parameter.  When "1", the `merchant_host` is contacted via HTTP.
+  When absent or "0", the `merchant_host` is contacted via HTTPS.
+* `ssid` is the optional WLAN SSID that the merchant can offer the wallet to connect to for internet connectivity
 
-* the default for ``merchant-public-prefix`` is ``public``
-* the default for ``merchant-instance`` is ``default``
 
-The following is a minimal example for a payment request from the demo merchant, using the default instance and no session-bound payment:
+Examples:
 
 .. code:: none
 
-  'taler://pay/backend.demo.taler.net/-/-/2019.08.26-ABCED
+  # Example 1:
+  # Order ID "ORD123", no session ID
+  # Merchant backend base URL "https://backend.test.taler.net/
+  taler://pay/test.taler.net/ORD123/
+
+  # Example 2:
+  # Order ID "ORD123", no session ID
+  # Merchant backend base URL "https://backend.test.taler.net/instances/x1/
+  taler://pay/test.taler.net/instances/x1/ORD123/
 
+  # Example 3:
+  # Order ID "ORD123", session ID "ABC123"
+  # Merchant backend base URL "https://backend.test.taler.net/
+  taler://pay/test.taler.net/ORD123/ABC123
+
+  # INVALID Example 1:
+  # When no session ID is given, the slash must still be present
+  taler://pay/test.taler.net/ORD123
 
 ------------------------
 Withdrawing (Initiation)
 ------------------------
 
-The action ``withdraw`` is invoked when a wallet urges a bank to declench the withdrawal operation by parsing its statusUrl (e.g. "https://bank.example.com/api/withdraw-operation/12345").
+The action ``withdraw`` is used to trigger a bank-integrated withdrawal operation.
 
 .. code:: none
 
-  'taler://withdraw/' bank-host '/' bank-query '/' withdraw-uid
-
-When the component ``bank-query`` is substituted by ``-`` (minus), the default ``withdraw-operation`` will be used.
+  taler://withdraw/{bank_host}{/bank_prefix_path*}/{withdrawal_uid}{?insecure}{#ssid}
 
-Example for a withdrawal request from the Taler demo bank using the default instance:
-
-.. code:: none
-
-  'taler://withdraw/bank.taler.net/-/ABDE123
+* `bank_host` is the hostname of the merchant
+* `bank_prefix_path` is an optional list of path components that identifies the path prefix of the bank integration API base URL.
+* `withdrawal_uid` is the unique ID of the withdrawal operation
+* `ssid` is the optional WLAN SSID that the bank (typically in an ATM scenario) can offer the wallet
+  to connect to for internet connectivity
 
 --------------------------
 Withdrawing (Confirmation)
@@ -61,13 +79,13 @@ Withdrawing (Confirmation)
 
 .. code:: none
 
-  'taler://notify-reserve/' [ reserve-pub ]
+  taler://notify-reserve/{reserve_pub}
 
 This action notifies the wallet that the status of a reserve has changed. It is used
 by the bank to indicate that the withdrawal has been confirmed by the user (e.g. via 2FA / mTAN / ...).
 The wallet the re-checks the status of all unconfirmed reserves.
 
-Optionally, ``reserve-pub`` can be specified to also indicate the reserve that
+Optionally, ``reserve_pub`` can be specified to also indicate the reserve that
 has been updated.
 
 
@@ -75,81 +93,37 @@ has been updated.
 Refunding
 ---------
 
-Refunding is an action which is applied when merchants decide to recline from contracts or to reduce the sum to be paid by the customer.
-The refund URI can be parsed with or without the component ``merchant-instance``.
+A ``taler://refund`` URI instructs the wallet to download and apply available refunds for an already paid order.
 
 .. code:: none
 
-  'taler://refund/' merchant-host '/' merchant-public-prefix '/' merchant-instance '/' orderId
-  
-To make the URI shorter, ``merchant-public-prefix`` and/or ``merchant-instance`` can be substituted by ``-`` (minus) to get a default value
-for these components:
+  taler://refund/{merchant_host}{/merchant_prefix_path*}/{order_id}/{?insecure}{#ssid}
 
-* the default for ``merchant-public-prefix`` is ``public``
-* the default for ``merchant-instance`` is ``default``
-
-The following is a minimal example for a refunding request by the Taler demo merchant using the default instance:
-
-.. code:: none
-
-  taler://refund/merchant.example.com/-/-/1234
-
-And this is an example for a refunding request by the Taler demo merchant parsing with a specified instance:
-
-.. code:: none
-
-  'taler://refund/merchant.example.com/-/myinst/1234
+* `merchant_host` is the hostname of the merchant
+* `merchant_prefix_path` is an optional list of path components that identifies the path prefix of the merchant base URL.
+* `order_id` is the order ID to check for refunds
+* `insecure` is an optional query parameter.  When "1", the `merchant_host` is contacted via HTTP.
+  When absent or "0", the `merchant_host` is contacted via HTTPS.
+* `ssid` is the optional WLAN SSID that the merchant can offer the wallet to connect to for internet connectivity
 
 
 -------
 Tipping
 -------
 
-Tipping is an action declenched by merchants' website servers to transfer to their visitors little values as a recompensation for bearing ads or committing services to the website (leaving comments on bought products or submitting data into forms...). The URI is named "taler tip pickup uri".
-
-.. code:: none
-
-  'taler://tip/' merchant-host '' merchant-public-prefix '/' merchant-instance '/' tipid
-  
-The tipping URI can be parsed without an instance, with an instance or with the instances AND prefixes specified, which means either the component ``merchant-instance`` OR the components ``merchant-public-prefix`` and ``merchant-instance`` can be left out to make the URI shorter.
-
-
-* the default for ``merchant-public-prefix`` is ``public``
-* the default for ``merchant-instance`` is ``default``
-
-The following is a minimal example for a tipping request by the Taler demo merchant using the default instance:
-
-.. code:: none
-
-  'taler://tip/merchant.example.com/-/-/tipid
-
-This is an example for a tipping request by the Taler demo merchant parsing with a specified instance:
+A tipping URI instructs the wallet to download information about a tip from
+a merchant and ask the user to accept/decline it.
 
 .. code:: none
 
-  'taler://tip/merchant.example.com/-/tipm/tipid
-
-And this is an example for a tipping request by the Taler demo merchant parsing with specified prefix and instance:
-
-.. code:: none
-
-  'taler://tip/merchant.example.com/my%2fpfx/tipm/tipid
-
-
--------------------------
-Low-level Reserve Actions
--------------------------
-
-The following actions are deprecated.  They might not be supported
-in newer wallets.
-
-.. code:: none
-
-  'taler://reserve-create/' reserve-pub
-
-.. code:: none
+  taler://tip/{merchant_host}{/merchant_prefix_path*}/{tip_id}/{?insecure}{#ssid}
 
-  'taler://reserve-confirm/' query
+* `merchant_host` is the hostname of the merchant
+* `merchant_prefix_path` is an optional list of path components that identifies the path prefix of the merchant base URL.
+* `tip_id` uniquely identifies the tip
+* `insecure` is an optional query parameter.  When "1", the `merchant_host` is contacted via HTTP.
+  When absent or "0", the `merchant_host` is contacted via HTTPS.
+* `ssid` is the optional WLAN SSID that the merchant can offer the wallet to connect to for internet connectivity
 
 ----------------------------
 Special URLs for fulfillment