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

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