[taler-docs] branch master updated (53f0512 -> 8f64b14)

[gnunet]

This is an automated email from the git hooks/post-receive script.

dold pushed a change to branch master
in repository docs.

    from 53f0512  use strings as union tag
     new 562f52a  more string tags
     new 8f64b14  update taler:// URI spec

The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 core/api-merchant.rst |   8 +--
 core/taler-uri.rst    | 142 +++++++++++++++++++++-----------------------------
 2 files changed, 62 insertions(+), 88 deletions(-)

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 7c5e097..4adf987 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -1219,7 +1219,7 @@ Payment processing
 
     interface CheckPaymentPaidResponse {
       // did the customer pay for this contract
-      status: "paid";
+      order_status: "paid";
 
       // Was the payment refunded (even partially)
       refunded: boolean;
@@ -1262,7 +1262,7 @@ Payment processing
   .. ts:def:: CheckPaymentUnpaidResponse
 
     interface CheckPaymentUnpaidResponse {
-      status: "unpaid";
+      order_status: "unpaid";
 
       // URI that the wallet must process to complete the payment.
       taler_pay_uri: string;
@@ -1366,7 +1366,7 @@ Payment processing
 
     interface StatusPaid {
       // Has the payment for this order (ever) been completed?
-      paid: true;
+      order_status: "paid";
 
       // Was the payment refunded (even partially, via refund or abort)?
       refunded: boolean;
@@ -1386,7 +1386,7 @@ Payment processing
 
     interface StatusUnpaid {
       // Has the payment for this order (ever) been completed?
-      paid: false;
+      order_status: "unpaid";
 
       // URI that the wallet must process to complete the payment.
       taler_pay_uri: string;
diff --git a/core/taler-uri.rst b/core/taler-uri.rst
index 6d59bda..765c6dc 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

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.