.. _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 `__ 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 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}/{#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 ---------------- 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*}/