summaryrefslogtreecommitdiff
path: root/core/taler-uri.rst
diff options
context:
space:
mode:
Diffstat (limited to 'core/taler-uri.rst')
-rw-r--r--core/taler-uri.rst88
1 files changed, 73 insertions, 15 deletions
diff --git a/core/taler-uri.rst b/core/taler-uri.rst
index a8930634..6d59bda7 100644
--- a/core/taler-uri.rst
+++ b/core/taler-uri.rst
@@ -19,35 +19,37 @@ Payments are requested with the ``pay`` action. The parameters are a hierarchic
.. code:: none
- 'taler://pay/' merchant-host '/' merchant-public-prefix '/' merchant-instance '/' order-id [ '/' session-id ]
+ 'taler://pay/' merchant-host '/' merchant-public-prefix '/' merchant-instance '/' orderId [ '/' sessionId ]
-The components ``merchant-host``, ``merchant-prefix`` and ``order-id`` identify the URL that is used to claim the contract
-for this payment request.
+The components ``merchant-host``, ``merchant-public-prefix`` and ``orderId`` identify the URL that is used to claim the contract
+for the payment request.
-To make the URI shorter (which is important for QR code payments), ``-`` (minus) can be substituted to get a default value
-for some components:
+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:
-* the default for ``merchant-instance`` is ``default``
* 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:
.. code:: none
- taler://pay/backend.demo.taler.net/-/-/2019.08.26-ABCED
+ 'taler://pay/backend.demo.taler.net/-/-/2019.08.26-ABCED
------------------------
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").
+
.. code:: none
'taler://withdraw/' bank-host '/' bank-query '/' withdraw-uid
-When ``bank-query`` is ``-``, the default ``withdraw-operation`` will be used.
+When the component ``bank-query`` is substituted by ``-`` (minus), the default ``withdraw-operation`` will be used.
-Example:
+Example for a withdrawal request from the Taler demo bank using the default instance:
.. code:: none
@@ -61,22 +63,78 @@ Withdrawing (Confirmation)
'taler://notify-reserve/' [ reserve-pub ]
-Notify the wallet that the status of a reserve has changed. 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.
+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
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``.
+
+.. 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:
+
+* 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
+
+
-------
-Refunds
+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://refund/' merchant-host '/' merchant-public-prefix '/' merchant-instance '/' order-id
+ 'taler://tip/merchant.example.com/-/-/tipid
+
+This is an example for a tipping request by the Taler demo merchant parsing with a specified instance:
+
+.. 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