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:

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.

1.11.1. Requesting a Payment¶

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

1.11.2. Withdrawing (Initiation)¶

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

1.11.3. Withdrawing (Confirmation)¶

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.

1.11.4. Refunding¶

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

1.11.5. Tipping¶

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

1.11.6. 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.

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

1.11.7. 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.

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

1.11.8. 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:

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

Table Of Contents