1.11. The taler:// URI scheme

The taler URI scheme represents actions that are processed by a Taler wallet. The basic syntax is as follows:

'taler://' action '/' params

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-public-prefix '/' merchant-instance '/' orderId [ '/' sessionId ]

The components merchant-host, merchant-public-prefix and orderId identify the URL that is used to claim the contract for the payment request.

To make the URI shorter (which is important for QR code payments), merchant-public-prefix and/or merchant-instance can be substituted by - (minus) to get a default value for these components:

  • the default for merchant-public-prefix is public
  • the default for merchant-instance is default

The following is a minimal example for a payment request from the demo merchant, using the default instance and no session-bound payment:

'taler://pay/backend.demo.taler.net/-/-/2019.08.26-ABCED

1.11.2. Withdrawing (Initiation)

The action withdraw is invoked when a wallet urges a bank to declench the withdrawal operation by parsing its statusUrl (e.g. “https://bank.example.com/api/withdraw-operation/12345”).

'taler://withdraw/' bank-host '/' bank-query '/' withdraw-uid

When the component bank-query is substituted by - (minus), the default withdraw-operation will be used.

Example for a withdrawal request from the Taler demo bank using the default instance:

'taler://withdraw/bank.taler.net/-/ABDE123

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

Refunding is an action which is applied when merchants decide to recline from contracts or to reduce the sum to be paid by the customer. The refund URI can be parsed with or without the component merchant-instance.

'taler://refund/' merchant-host '/' merchant-public-prefix '/' merchant-instance '/' orderId

To make the URI shorter, merchant-public-prefix and/or merchant-instance can be substituted by - (minus) to get a default value for these components:

  • the default for merchant-public-prefix is public
  • the default for merchant-instance is default

The following is a minimal example for a refunding request by the Taler demo merchant using the default instance:

taler://refund/merchant.example.com/-/-/1234

And this is an example for a refunding request by the Taler demo merchant parsing with a specified instance:

'taler://refund/merchant.example.com/-/myinst/1234

1.11.5. Tipping

Tipping is an action declenched by merchants’ website servers to transfer to their visitors little values as a recompensation for bearing ads or committing services to the website (leaving comments on bought products or submitting data into forms…). The URI is named “taler tip pickup uri”.

'taler://tip/' merchant-host '' merchant-public-prefix '/' merchant-instance '/' tipid

The tipping URI can be parsed without an instance, with an instance or with the instances AND prefixes specified, which means either the component merchant-instance OR the components merchant-public-prefix and merchant-instance can be left out to make the URI shorter.

  • the default for merchant-public-prefix is public
  • the default for merchant-instance is default

The following is a minimal example for a tipping request by the Taler demo merchant using the default instance:

'taler://tip/merchant.example.com/-/-/tipid

This is an example for a tipping request by the Taler demo merchant parsing with a specified instance:

'taler://tip/merchant.example.com/-/tipm/tipid

And this is an example for a tipping request by the Taler demo merchant parsing with specified prefix and instance:

'taler://tip/merchant.example.com/my%2fpfx/tipm/tipid

1.11.6. Low-level Reserve Actions

The following actions are deprecated. They might not be supported in newer wallets.

'taler://reserve-create/' reserve-pub
'taler://reserve-confirm/' query

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