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:
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.
Payments are requested with the pay
action. The parameters are a hierarchical identifier for the requested payment:
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:
# 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
The action withdraw
is used to trigger a bank-integrated withdrawal operation.
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.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.
A taler://refund
URI instructs the wallet to download and apply available refunds for an already paid order.
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.A tipping URI instructs the wallet to download information about a tip from a merchant and ask the user to accept/decline it.
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.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.
taler://exchange/{exchange_host}{/exchange_prefix_path*}/
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.
taler://auditor/{auditor_host}{/auditor_prefix_path*}/