3.1.5. Understanding fulfillment URLs

Taler orders and contracts must contain either a fulfillment_url or a fulfillment_message, which are used by the wallet after the contract has been paid. This tutorial explains how to properly set these values.

3.1.5.1. Fulfillment message

This field is simply a message that will be shown to the user by the Taler wallet after the user completed the purchase. It can be set to any kind of UTF-8 text and it supposed to be used as a friendly final message from the merchant at the end of the business transaction.

Megjegyzés

Whe wallets do learn the text before the purchase is made, so users could obtain the fulfillment message before the actual purchase. As a result, it should not contain any actual credentials or information that the user might be buying with the contract.

Fulfillment messages are used when the merchant does not have a fulfillment URL to redirect the user to.

3.1.5.2. Fulfillment URLs

Contracts can contain a fulfillment_url instead of a fulfillment_message. The fulfillment_url must refer to a Web site (start with http:// or https://) and the user will be redirected there immediately after they completed the purchase and possibly later from the purchase details dialog in their wallet’s transaction history.

Fulfillment URLs serve a second purpose, which is that they are also used for repurchase detection. Thus, care must be taken to use fulfillment URLs correctly. We explain the two relevant scenarios and their motivation in the next two sections.

3.1.5.3. Repurchase detection

A digitális cikkekhez való hozzáférést értékesítő kereskedők számára problémát jelenthet, hogy a vásárló fizetett egy cikkért egy eszközön, de aztán egy másik eszközön szeretné elolvasni, esetleg olyan eszközön, amelyen nincs is telepítve Taler pénztárca.

Naturally, at this point the customer would at first still be prompted to pay for the article again. If the customer then opens the taler:// link in the wallet that did previously pay for the article (for example by scanning the QR code on the desktop with the Android App), the wallet will claim the contract, detect that the fulfillment URL is identical to one that it already has made a payment for in the past, and initiate repurchase redirection: Here, the wallet will contact the merchant and replay the previous payment, except this time using the (current) session ID of the browser (it learns the session ID from the QR code).

A kereskedői háttértár ezután frissíti a meglévő megrendelés munkamenet-azonosítóját a böngésző aktuális munkamenet-azonosítójára. Amikor az „új” nem fizetett megrendelés fizetési státuszát ellenőrzik (vagy már a hosszú lekérdezés során), a backend észleli, hogy a böngésző session ID-je és teljesítési URL-je esetében van egy meglévő fizetett szerződés. Ezután utasítja a böngészőt, hogy azonnal irányítsa át a teljesítési URL-re, ahol a már kifizetett cikk elérhető.

It is thus crucial that merchants consistently use the same fulfillment URL for the same digital product where repurchase detection is desired.

Megjegyzés

Changing the session ID to a different device requires the involvement of the original wallet that made the payment, thus reasonably limiting the possibility of broadly sharing the digital purchases.

3.1.5.4. Allowing repeated purchases

To ensure repurchase detection does not prevent customers from buying the same service or physical good a second time, merchants must make sure to not use the same fulfillment URL for different products or for physical products where customers may be expected to buy the article repeatedly.

A convenient way to create a unique fulfillment URL is to embed the order ID in the fulfillment URL. To enable using the order ID in a fulfillment URL even if the order_id field is not set by the merchant when POSTing a new order (and thus the actual order ID will be chosen by the merchant backend), you can use the placeholder text ${ORDER_ID} in the fulfillment_url when posting it to the merchant backend. The merchant backend will then immediately substitute ${ORDER_ID} in the URL with the actual order ID (before persisting the contract terms locally).