]> BFH

Höheweg 80 Biel/Bienne CH-2501 CH christian.grothoff@bfh.ch

Taler Systems SA

7, rue de Mondorf Erpeldange L-5421 LU dold@taler.net

General Independent Stream payments This document defines the 'taler' Uniform Resource Identifier (URI) scheme for triggering interactions with a GNU Taler wallet. This URI scheme allows applications to trigger interactions with the GNU Taler wallet, such as withdrawing money, making payments, receiving refunds and restoring a wallet from a backup. Applications may receive such URIs in many ways (including via NFC, QR codes, Web links or messaging applications), or might generate them internally to interact with a wallet. By having a Taler wallet handle the respective URIs, applications can integrate Taler payments without having to support the Taler protocol directly. Furthermore, by passing control to a Taler wallet process, the wallet's database with its financial data might be better protected from application failures.

This document defines the 'taler' Uniform Resource Identifier (URI) scheme for triggering interactions with GNU Taler wallets.

A 'taler' URI always instructs a GNU Taler wallet to perform a particular operation. A 'taler' URI consists of an action and optional parameters. The interpretation of the optional parameters depends on the action.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

This document uses the Augmented Backus-Naur Form (ABNF) of .

'path-abempty' is defined in in Section 3.3. 'pchar' is defined in , Appendix A.

The action of a Taler URI identifies the operation requested from the Taler wallet. Actions are not case-sensitive. The actions are defined in the "Taler URI Actions" sub-registry, see . The path component of the URI typically provides a network address needed to locate additional information or services relevant to the requested operation. Paths are case-sensitive, but may contain case-insensitive portions, such as domain names. The query component of the URI provides immediate additional parameters or options for the operation. The query is case-sensitive. The default operation of applications that invoke a URI with the taler scheme MUST be to launch a Taler wallet (if available). If no taler URI handler is available, an application SHOULD show a QR code with the contents of the URI. If multiple Taler wallets are registered, the user SHOULD be able to choose which application to launch. This allows users with multiple wallets (each possibly with its own money) to choose which wallet to perform the operation with. An application SHOULD allow dereferencing a "taler://" URI even if the action of that URI is not registered in the "Taler URI Actions" sub-registry. Wallets seeing a "taler://" URI MUST use HTTP over TLS when talking to the respective network service. Wallets seeing a "taler+http://" URI MUST use HTTP without TLS when talking to the respective network service. Wallets SHOULD support "taler+http://"-URIs only when run in developer or debug mode.

A registry of Taler URI Actions is described in . The registration policy for this registry is "Expert Review", as described in . When requesting new entries, careful consideration of the following criteria is strongly advised: The description clearly defines the semantics of the action and optional parameters if applicable. The name states the unique name for the action that must be part of the URI. The syntax defines the format of the action-specific part of the URI. Relevant references are provided if they are available. The chosen name is appropriate for the operation, and avoids potential to confuse users. A libre software reference implementation is available. Documents that support requests for new registry entries should provide the following information for each entry: Description: A description of the action, including the semantics of the path in the URI if applicable. Name: The name of the Taler URI action (case insensitive ASCII string, restricted to alphanumeric characters, dots and dashes) Syntax: summary of the syntax of the URI as a one-liner. Example: At least one example URI to illustrate the action. Contact: The contact information of a person to contact for further information References: Optionally, references describing the action (such as an RFC) and target-specific options. This document populates the registry with $COUNT entries as follows (see also ).

The action "withdraw" is used to trigger a bank-integrated withdrawal operation. This means that the user has been interacting with some online banking App and wants to instruct the bank to transfer money from the user's bank account into a the GNU Taler wallet. The wallet now needs to allow the user to select the GNU Taler exchange, and then ultimately provide the bank with its reserve public key and await the completion of the wire transfer. The specific arguments of a "withdraw" action are: bank_host: hostname of the bank (optionally including a port number) bank_prefix_path: list of path components that identifies the path prefix of the bank integration API base URL withdrawal_uid: the unique ID of the withdrawal operation Name: withdraw Syntax: taler://withdraw/{bank_host}{/bank_prefix_path*}/{withdrawal_uid} Example: taler://withdraw/bank.example.com/wid Contact: N/A References: [this.I-D]

Payments are requested with the "pay" action. The parameters are a hierarchical identifier for the requested payment, and must include a hostname, order ID and session ID (which may be an empty string). Additionally, a claim token and a prefix path to be used as part of the HTTP REST API request to the hostname may be specified. The specific arguments of a "pay" action are: merchant_host: hostname of the GNU Taler REST service of merchant (may optionally include a port number) merchant_prefix_path: list of path components that identifies the path prefix of the merchant base URL order_id: the order ID that the customer is asked to pay for session_id: the session ID under which the payment takes place ct: a high-entropy order "ClaimToken" Name: pay Syntax: taler://pay/{merchant_host}{/merchant_prefix_path*}/{order_id}/{session_id}{?c=ct} Example: taler://pay/merchant.example.com/42/ Contact: N/A References: [this.I-D]

A "refund" action instructs the wallet to download information about an available refund. Wallet SHOULD consult the user about the refund and then obtain the refund for an already paid order. The specific arguments of a "refund" action are: merchant_host: hostname of the merchant (possibly including a port number) merchant_prefix_path: list of path components that identifies the path prefix of the merchant base URL order_id: the order ID to check for refunds Name: refund Syntax: taler://refund/{merchant_host}{/merchant_prefix_path*}/{order_id}/ Example: taler://refund/shop.example.com/42/ Contact: N/A References: [this.I-D]

A tipping URI instructs the wallet to download information about a tip from a merchant and to ask the user to accept/decline the tip. The specific arguments of a "tip" action are: merchant_host: hostname of the merchant (possibly including a port number) merchant_prefix_path: list of path components that identifies the path prefix of the merchant base URL tip_id: identifier that uniquely identifies the tip Name: tip Syntax: taler://tip/{merchant_host}{/merchant_prefix_path*}/{tip_id}/ Example: taler://tip/merchant.com/FIXME Contact: N/A References: [this.I-D]

A pay-push URI instructs the wallet to ask the user about accepting a P2P payment. The wallet should download, decrypt and display the underlying contract and accept the offered money if the user agrees to the contract. The specific arguments of a "pay-push" action are: exchange_host: the hostname of the exchange (possibly including a port number) exchange_prefix_path: list of path components that identifies the path prefix of the exchange base URL merge_priv: private key that grants the capability to take the money in the purse Name: pay-push Syntax: taler://pay-push/{exchange_host}{/exchange_prefix_path*}/{merge_priv} Example: taler://pay-push/exchange.example.com/KAMRGDM8FNQ82HSBVDEH8MCAF13Q0B51P4R35RFG2CBVHKGT321G Contact: N/A References: [this.I-D]

A pay-pull URI instructs the wallet about a request made to the user to pay an invoice (or to simply send money to another wallet). The wallet should download, decrypt and display the underlying contract and ask the user if they agree to pay the invoice. The specific arguments of a "pay-pull" action are: exchange_host: the hostname of the exchange (possibly including a port number) exchange_prefix_path: list of path components that identifies the path prefix of the exchange base URL contract_priv: the private key of the peer push payment contract stored at the exchange Name: pay-pull Syntax: taler://pay-pull/{exchange_host}{/exchange_prefix_path*}/{contract_priv} Example: taler://pay-pull/exchange.example.com/PN3W8SN6N8V1V5MTEZRPJJ2ANY8GGZMB1MBXC7NMSRXJN6MZ5SWG Contact: N/A References: [this.I-D]

A "pay-template" action instructs the wallet to ask its user to manually complete an order template and submit the information to the merchant to obtain a "pay" request. Contract fields that are not specified in the argument list must not be submitted. Wallets MAY to support users entering all possible fields of a contract. Keys that MUST be supported at this time are the "amount" and the "summary" fields. The wallet MUST validate that the amount entered by the user is well-formed. For the amount, it is possible that the QR code already specifies the currency (e.g. "amount=CHF" or "amount=CHF:5") in which case the wallet MUST only allow the user to enter an amount in that currency. If the amount entered by the user exceeds the wallet balance, the wallet SHOULD NOT allow the user to submit the action. A QR code may not specify any keys for manual entry. In this case, the wallet MUST immediately submit the request (with an empty body) to the merchant to obtain a dynamically generated "taler://pay/" URI based on the template. The specific arguments of a "pay-template" action is: merchant_host: hostname of the merchant merchant_prefix_path: list of path components that identifies the path prefix of the merchant base URL template_id: identifier that uniquely identifies the template key: possible contract detail to prompt the user for value: default value to use for the respective key Name: pay-template Syntax: taler://pay-template/{merchant_host}{/merchant_prefix_path*}/{template_id}[?key[=value]}{&key[=value]}* Example: taler://pay-template/merchant.example.com/FEGHYJY48FEGU6WETYIOIDEDE2QW3OCZVY?amount=KUDOS:5 Contact: N/A References: [this.I-D]

An "exchange" action 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. The specific arguments of an "exchange" action are: exchange_host: hostname of the exchange (possibly including a port number) exchange_prefix_path: list of path components that identifies the path prefix of the exchange base URL exchange_pub: the public key of the exchange Name: exchange Syntax: taler://exchange/{exchange_host}{/exchange_prefix_path*}/{exchange_pub} Example: taler://exchange/exchange.example.com/ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOP Contact: N/A References: [this.I-D]

An "auditor" action 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. The specific arguments of an "auditor" action are: auditor_host: the hostname of the auditor (possibly including a port number) auditor_prefix_path: list of path components that identifies the path prefix of the auditor base URL auditor_pub: the public key of the auditor Name: auditor Syntax: taler://auditor/{auditor_host}{/auditor_prefix_path*}/{auditor_pub} Example: taler://auditor/auditor.example.com/ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOP Contact: N/A References: [this.I-D]

A "restore" action instructs the wallet to restore a wallet backup and merge it into its current state. The specific arguments of a "restore" action are: sync_rootkey: Root sync key of the wallet, used to derive the symmetric key to encrypt the backup with individual providers. sync_provider_list: Comma-separated list of provider http or https URLs. If no scheme part is specified, https is assumed. Each URL is URI-encoded for all characters except "A-Z a-z 0-9 - _ . ! ~ * ' ( )" (matching the HTML5 encodeURIComponent). Name: restore Syntax: taler://auditor/{sync_rootkey}/{sync_provider_list} Example: taler://restore/backup.example.com/GJKG23V4ZBHEH45YRK7TWQE8ZTY7JWTY5094TQJSRZN5DSDBX8E0/prov1.example.com,prov2.example.com Contact: N/A References: [this.I-D]

An "dev-experiment" action instructs the wallet to simulate a particular error scenario. This action can be used to test the user interface. Wallets that are not in developer mode should not run the specified action and instead inform the user that "dev-experiment" actions are only supported in developer mode. The specific arguments of a "dev-experiment" action are: name: specifies the specific type of dev experiment Name: dev-experiment Syntax: payto://dev-experiment/{name} Example: payto://dev-experiment/xxx Contact: N/A References: [this.I-D]

Interactive applications handling the taler URI scheme MUST NOT initiate any unsafe payment operations prior review and confirmation from the user, and MUST take measures to prevent clickjacking . The authentication/authorization mechanisms and transport security services used to process a payment encoded in a taler URI are handled by the application and are not in scope of this document.

IANA maintains a registry called the "Uniform Resource Identifier (URI) Schemes" registry.

IANA maintains the "Uniform Resource Identifier (URI) Schemes" registry that contains an entry for the 'taler' URI scheme. IANA is requested to update that entry to reference this document when published as an RFC.

This document specifies a list of Taler URI Actions. It is possible that future work will need to specify additional actions. The GNUnet Assigned Numbers Authority (GANA) operates the "taler-uri-actions" registry to track the following information for each payment target type: Name: The name of the action (case insensitive ASCII string, restricted to alphanumeric characters, dots and dashes) Contact: The contact information of a person to contact for further information References: Optionally, references describing the payment target type (such as an RFC) and target-specific options, or references describing the payment system underlying the payment target type. The entries that have been made for the "taler-uri-actions" defined in this document are as follows:

Name | Contact | Reference ---------------+-------------------------+------------ pay | N/A | [This.I-D] withdraw | N/A | [This.I-D] refund | N/A | [This.I-D] tip | N/A | [This.I-D] pay-pull | N/A | [This.I-D] pay-push | N/A | [This.I-D] pay-template | N/A | [This.I-D] exchange | N/A | [This.I-D] auditor | N/A | [This.I-D] restore | N/A | [This.I-D] dev-experiment | N/A | [This.I-D]

&RFC2119; &RFC3986; &RFC5234; &RFC8126; &RFC8174; GNUnet e.V.