summaryrefslogtreecommitdiff
path: root/core/taler-uri.rst
blob: ddb61322256508a40e8061c86425e6ad1ee9679f (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
.. _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}

--------------------
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}{?insecure}{#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 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


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}{?insecure}{#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 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
---------

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}/{?insecure}{#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
* ``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
-------

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}/{?insecure}{#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

----------------------------
Special URLs for fulfillment
----------------------------

The special ``fulfillment-success`` action can be used in a fulfillment URI to indicate success
with a message, without directing the user to a website.  This is useful in applications that are not Web-based:

When wallets encounter this URI in any other circumstance than going to a fulfillment URL, they must raise an error.

Example:

.. code:: none

  taler://fulfillment-success/Thank+you+for+donating+to+GNUnet