From 70a6cd835580166f03b2d24be4189cf2cc8fde05 Mon Sep 17 00:00:00 2001 From: Stefan Kügel Date: Wed, 15 Apr 2020 15:08:31 +0200 Subject: Extended the URI list for the documentation website --- core/taler-uri.rst | 88 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 73 insertions(+), 15 deletions(-) (limited to 'core') 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 -- cgit v1.2.3