summaryrefslogtreecommitdiff
path: root/core/taler-uri.rst
blob: 80e8c7aaa8cd6266a4d1c1d9442a961606dd1db4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
.. _taler-uri-scheme:

=======================
The taler:// URI scheme
=======================

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}/{+rest}

The alternative scheme name ``taler+http`` indicates that the referenced resource is to be accessed
via plain HTTP instead of HTTPS.  This **should** only be used for testing.  A production
version of the wallet **may** reject such URIs.

--------------------
Requesting a Payment
--------------------

Payments are requested with the ``pay`` action.  The parameters are a hierarchical identifier for the requested payment:

.. code:: none

  taler://pay/{merchant_host}{/merchant_prefix_path*}/{order_id}/{session_id}{?c}{#ssid}

* ``merchant_host`` is the hostname (and optionally port) 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.
* ``c`` is the optional high-entropy order `ClaimToken`.
* ``ssid`` is the optional WLAN SSID that the merchant can offer the wallet to connect to for Internet connectivity.

Examples:

.. code:: none

  # 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 used to trigger a bank-integrated withdrawal operation.

.. code:: none

  taler://withdraw/{bank_host}{/bank_prefix_path*}/{withdrawal_uid}{#ssid}

* ``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)
--------------------------

.. code:: none

  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 then re-checks the status of all unconfirmed reserves.

Optionally, ``reserve_pub`` can be specified to also indicate the reserve that
has been updated.


---------
Refunding
---------

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_prefix_path*}/{order_id}/{#ssid}
  taler+http://refund/{merchant_host}{/merchant_prefix_path*}/{order_id}/{#ssid}

* ``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.
* ``ssid`` is the optional WLAN SSID that the merchant can offer the wallet to connect to for Internet connectivity.


-------
Tipping
-------

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_host}{/merchant_prefix_path*}/{tip_id}/{#ssid}

* ``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.


---------------------
Peer-to-peer payments
---------------------

A ``taler://pay-push/{exchange_host}{/exchange_prefix_path*}/{contract_priv}`` URI
instructs the wallet to accept a P2P push payment.

* ``exchange_host`` is the hostname of the exchange.
* ``exchange_prefix_path`` is an optional list of path components that identifies the path prefix of the exchange base URL.
* ``contract_priv`` is the private key of the peer push payment contract stored at the exchange

----------------
Adding exchanges
----------------

A ``taler://exchange/`` URI instructs the wallet to display a prompt to the user, asking
the user to confirm/decline adding the exchange to the list of trusted exchanges.

.. code:: none

  taler://exchange/{exchange_host}{/exchange_prefix_path*}/

---------------
Adding auditors
---------------

A ``taler://auditor/`` URI instructs the wallet to display a prompt to the user, asking
the user to confirm/decline adding the auditor to the list of trusted auditors.

.. code:: none

  taler://auditor/{auditor_host}{/auditor_prefix_path*}/