[taler-docs] 02/02: update taler:// URI spec

[gnunet]

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

dold pushed a commit to branch master
in repository docs.

commit 8f64b144f12ba445eae4238281c4ca763beba526
Author: Florian Dold <florian.dold@gmail.com>
AuthorDate: Fri Jul 24 16:59:57 2020 +0530

    update taler:// URI spec
---
 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 26b009e..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?
-      status: "paid";
+      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?
-      status: "unpaid";
+      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.