summaryrefslogtreecommitdiff
path: root/core
diff options
context:
space:
mode:
authorFlorian Dold <florian.dold@gmail.com>2020-07-24 16:59:57 +0530
committerFlorian Dold <florian.dold@gmail.com>2020-07-24 16:59:57 +0530
commit8f64b144f12ba445eae4238281c4ca763beba526 (patch)
treeed40f766433e85963fde5792a17dc459db2332c3 /core
parent562f52ac450515aa209500aaf28968be466e787f (diff)
downloaddocs-8f64b144f12ba445eae4238281c4ca763beba526.tar.gz
docs-8f64b144f12ba445eae4238281c4ca763beba526.tar.bz2
docs-8f64b144f12ba445eae4238281c4ca763beba526.zip
update taler:// URI spec
Diffstat (limited to 'core')
-rw-r--r--core/api-merchant.rst8
-rw-r--r--core/taler-uri.rst142
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