From 8f64b144f12ba445eae4238281c4ca763beba526 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Fri, 24 Jul 2020 16:59:57 +0530 Subject: update taler:// URI spec --- core/api-merchant.rst | 8 +-- core/taler-uri.rst | 142 +++++++++++++++++++++----------------------------- 2 files changed, 62 insertions(+), 88 deletions(-) (limited to 'core') diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 26b009e2..4adf9874 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 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 +`__ 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 -- cgit v1.2.3