From 3ef07c6c9f11585b5826bbc3eac6fe90d2a9467a Mon Sep 17 00:00:00 2001
From: Florian Dold <florian.dold@gmail.com>
Date: Tue, 23 Aug 2016 15:34:59 +0200
Subject: http payment request - contract

---
 articles/ui/ui.tex | 42 ++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 40 insertions(+), 2 deletions(-)

(limited to 'articles/ui/ui.tex')

diff --git a/articles/ui/ui.tex b/articles/ui/ui.tex
index 57232c7fd..aaaf6e363 100644
--- a/articles/ui/ui.tex
+++ b/articles/ui/ui.tex
@@ -769,10 +769,29 @@ detect the presence of a Taler wallet (Figure~\ref{listing:presence}),
 so that the selection of alternative payment methods can be skipped if
 a Taler wallet is installed (as it is in Figure~\ref{fig:shopping}).
 
-% FIXME: add figure for 402 payment!
+\begin{figure*}[h!]
+  \lstset{language={}}
+\begin{lstlisting}
+HTTP/1.1 402 Payment Required
+Content-Type: text/html; charset=UTF-8
+X-Taler-Contract-Url: https://myshop/generate-contract?product=42
+...
+
+<!DOCTYPE html>
+<html>
+  ...
+  You don't seem to have Taler installed, here are
+  other payment options:
+  ...
+</html>
+\end{lstlisting}
+ \caption{Sample HTTP response for a web resource that requires a payment.}
+  \label{listing:http-contract}
+\end{figure*}
+
 The offer URL of the Web shop can then initiate payments by sending a
 \emph{contract proposal} to the wallet, either via the HTTP status
-code {\tt 402 Payment Required}, or via Taler's JavaScript API
+code {\tt 402 Payment Required} (Figure~\ref{listing:http-contract}), or via Taler's JavaScript API
 (Figure~\ref{listing:contract}).  The wallet then presents the
 contract to the user.  The format of the contract is in an extensible
 JSON-based format defined by Taler and not HTML, as the rendering of
@@ -841,6 +860,25 @@ URL in a browser will show the resource associated with the purchase.
 This resource can be a digital good such as a news article, or simply
 a confirmation for products that are delivered by other means.
 
+\begin{figure*}[h!]
+  \lstset{language={}}
+\begin{lstlisting}
+HTTP/1.1 402 Payment Required
+Content-Type: text/html; charset=UTF-8
+X-Taler-Contract-Url: https://myshop/generate-contract?product=42
+...
+
+<html>
+  ...
+  You don't seem to have Taler installed, here are
+  other payment options:
+  ...
+</html>
+\end{lstlisting}
+ \caption{Sample HTTP response for a web resource that requires a payment.}
+  \label{listing:http-contract}
+\end{figure*}
+
 In order to ensure that only the paying customer has access to the Web
 resources behind the fulfillment URL, the Web store's server must
 check the browser's session state.  If the merchant can confirm that
-- 
cgit v1.2.3


From fff1f61f49347d2c13f4a20322eaa56fe0854c12 Mon Sep 17 00:00:00 2001
From: Florian Dold <florian.dold@gmail.com>
Date: Tue, 23 Aug 2016 15:53:28 +0200
Subject: refunds code sample

---
 articles/ui/ui.tex | 39 +++++++++++++++++----------------------
 1 file changed, 17 insertions(+), 22 deletions(-)

(limited to 'articles/ui/ui.tex')

diff --git a/articles/ui/ui.tex b/articles/ui/ui.tex
index aaaf6e363..a6cbc88a7 100644
--- a/articles/ui/ui.tex
+++ b/articles/ui/ui.tex
@@ -860,25 +860,6 @@ URL in a browser will show the resource associated with the purchase.
 This resource can be a digital good such as a news article, or simply
 a confirmation for products that are delivered by other means.
 
-\begin{figure*}[h!]
-  \lstset{language={}}
-\begin{lstlisting}
-HTTP/1.1 402 Payment Required
-Content-Type: text/html; charset=UTF-8
-X-Taler-Contract-Url: https://myshop/generate-contract?product=42
-...
-
-<html>
-  ...
-  You don't seem to have Taler installed, here are
-  other payment options:
-  ...
-</html>
-\end{lstlisting}
- \caption{Sample HTTP response for a web resource that requires a payment.}
-  \label{listing:http-contract}
-\end{figure*}
-
 In order to ensure that only the paying customer has access to the Web
 resources behind the fulfillment URL, the Web store's server must
 check the browser's session state.  If the merchant can confirm that
@@ -968,6 +949,20 @@ it has the following key advantages:
 
 \subsection{Giving change and refunds}
 
+\begin{figure*}[h!]
+  \lstset{language={HTML5}}
+\begin{lstlisting}
+<script src="taler-wallet-lib.js"></script>
+<script>
+  taler.offerRefundFrom("https://myshop/purchase/42/refund", (err) => {
+    alert("An error occured while attempting a refund");
+  });
+</script>
+\end{lstlisting}
+ \caption{Sample JavaScript code to trigger a refund}
+  \label{listing:refund}
+\end{figure*}
+
 An important cryptographic difference between Taler and previous
 transaction systems based on blind signing is that Taler is able to
 provide unlinkable change and refunds.  From the user's point of view,
@@ -984,9 +979,9 @@ coins.  Consequently, the major cryptographic advances of Taler are
 invisible to the user.
 
 Taler's refresh protocol~\cite{talercrypto} also allows merchants to
-give refunds to customers. For this, the merchant merely has to send a
-signed message to the exchange confirming the refund, and notify the
-customer's wallet that the respective transaction was refunded.  This
+give refunds to customers. For this, the merchant signs a message
+that the customer's wallet processes (Figure~\ref{listing:refund}) and sends to the exchange in order
+to obtain new coins as a refund.  This
 can even be done with anonymous customers, as refunds are given as
 additional change to the owner of the coins that were originally spent
 to pay for the refunded transaction.
-- 
cgit v1.2.3


From 28e392c5e797424e7a9c2b122cc4441ba2751afd Mon Sep 17 00:00:00 2001
From: Florian Dold <florian.dold@gmail.com>
Date: Tue, 23 Aug 2016 16:04:01 +0200
Subject: HTTP 402 - payment execution mechanism sample

---
 articles/ui/ui.tex | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

(limited to 'articles/ui/ui.tex')

diff --git a/articles/ui/ui.tex b/articles/ui/ui.tex
index a6cbc88a7..f9da6ca15 100644
--- a/articles/ui/ui.tex
+++ b/articles/ui/ui.tex
@@ -860,6 +860,28 @@ URL in a browser will show the resource associated with the purchase.
 This resource can be a digital good such as a news article, or simply
 a confirmation for products that are delivered by other means.
 
+\begin{figure*}[h!]
+  \lstset{language={}}
+\begin{lstlisting}
+HTTP/1.1 402 Payment Required
+Content-Type: text/html; charset=UTF-8
+X-Taler-Contract-Hash: RA67CB1...
+X-Taler-Offer-Url: https://myshop/article/42
+...
+
+<!DOCTYPE html>
+<html>
+  ...
+  You don't seem to have Taler installed, here are
+  other payment options:
+  ...
+</html>
+\end{lstlisting}
+ \caption{Sample HTTP response when the user agent navigates to a fulfillment URL without
+  the session state that indicates they have paid for the resource.}
+  \label{listing:http-execute}
+\end{figure*}
+
 In order to ensure that only the paying customer has access to the Web
 resources behind the fulfillment URL, the Web store's server must
 check the browser's session state.  If the merchant can confirm that
@@ -869,7 +891,7 @@ for example because the session state was lost,\footnote{This can
   happen when when privacy conscious users delete their cookies.
   Also, some user agents (such as the TOR browser) do not support
   persistent (non-session) cookies.} it {\em again} triggers a payment
-process (either via JavaScript or using {\tt 402 Payment Required}).
+process (either via JavaScript or using {\tt 402 Payment Required}, see Figure~\ref{listing:http-execute}).
 If the wallet remembers paying for the contract previously, this
 causes the wallet to retransmit the signed coins that are associated
 with the purchase to the merchant.
-- 
cgit v1.2.3


From 92a68087c8b4975ed21d1e8f480a2dc7da139f4a Mon Sep 17 00:00:00 2001
From: Florian Dold <florian.dold@gmail.com>
Date: Wed, 24 Aug 2016 13:53:08 +0200
Subject: describe refunds as discussed

---
 articles/ui/ui.tex | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

(limited to 'articles/ui/ui.tex')

diff --git a/articles/ui/ui.tex b/articles/ui/ui.tex
index f9da6ca15..b927fe034 100644
--- a/articles/ui/ui.tex
+++ b/articles/ui/ui.tex
@@ -976,12 +976,15 @@ it has the following key advantages:
 \begin{lstlisting}
 <script src="taler-wallet-lib.js"></script>
 <script>
-  taler.offerRefundFrom("https://myshop/purchase/42/refund", (err) => {
+  // Obtain refund permissions from the merchant backend
+  // ...
+  let refundPermissions = /* ... */;
+  taler.acceptRefunds(refundPermissions, (err) => {
     alert("An error occured while attempting a refund");
   });
 </script>
 \end{lstlisting}
- \caption{Sample JavaScript code to trigger a refund}
+ \caption{Sample JavaScript code to trigger a refund from the merchant's web shop}
   \label{listing:refund}
 \end{figure*}
 
@@ -1000,13 +1003,11 @@ the exchange providers and fee structure, but not the cryptographic
 coins.  Consequently, the major cryptographic advances of Taler are
 invisible to the user.
 
-Taler's refresh protocol~\cite{talercrypto} also allows merchants to
-give refunds to customers. For this, the merchant signs a message
-that the customer's wallet processes (Figure~\ref{listing:refund}) and sends to the exchange in order
-to obtain new coins as a refund.  This
-can even be done with anonymous customers, as refunds are given as
-additional change to the owner of the coins that were originally spent
-to pay for the refunded transaction.
+Taler's refresh protocol~\cite{talercrypto} also allows merchants to give
+refunds to customers. To refund a purchase, the merchant obtains a signed refund permission
+from the exchange, which the customer's wallet processes
+(Figure~\ref{listing:refund}) to obtain new, unlinkable coins as refund.
+This process allows the customer to say anonymous when receiving refunds.
 
 Taler's refresh protocol ensures unlinkability for both change and
 refunds, thereby assuring that the user has key conveniences of other
-- 
cgit v1.2.3


From a72d7a7e6c02e40d141f36b4fc2fa7bfa0047609 Mon Sep 17 00:00:00 2001
From: Florian Dold <florian.dold@gmail.com>
Date: Wed, 24 Aug 2016 14:01:46 +0200
Subject: Add contract example, remove legacy example

---
 articles/ui/figs/taler-contract.html |  6 ++++++
 articles/ui/figs/taler-contract.js   | 42 ------------------------------------
 articles/ui/ui.tex                   | 32 ++++++++++++++++++++++++---
 3 files changed, 35 insertions(+), 45 deletions(-)
 create mode 100644 articles/ui/figs/taler-contract.html
 delete mode 100644 articles/ui/figs/taler-contract.js

(limited to 'articles/ui/ui.tex')

diff --git a/articles/ui/figs/taler-contract.html b/articles/ui/figs/taler-contract.html
new file mode 100644
index 000000000..7d4b8d5bf
--- /dev/null
+++ b/articles/ui/figs/taler-contract.html
@@ -0,0 +1,6 @@
+<script src="taler-wallet-lib.js"></script>
+<script>
+  taler.offerContractFrom("https://myshop/products/article/42", (err) => {
+    alert("Error while offering contract");
+  });
+</script>
diff --git a/articles/ui/figs/taler-contract.js b/articles/ui/figs/taler-contract.js
deleted file mode 100644
index 3c0079226..000000000
--- a/articles/ui/figs/taler-contract.js
+++ /dev/null
@@ -1,42 +0,0 @@
-/* Trigger Taler contract generation on the server, and pass the
-   contract to the extension once we got it. */
-function taler_pay(form) {
-  var contract_request = new XMLHttpRequest();
-
-  /* Note that the URL we give here is simply an example
-     and not dictated by the protocol: each web shop can
-     have its own way of generating and transmitting the
-     contract, there just must be a way to get the contract
-     and to pass it to the wallet when the user selects 'Pay'. */
-  contract_request.open("GET", "generate-taler-contract", true);
-  contract_request.onload = function (e) {
-    if (contract_request.readyState == 4) {
-      if (contract_request.status == 200) {
-        /* Send contract to the extension. */
-        handle_contract(contract_request.responseText);
-      } else {
-        /* There was an error obtaining the contract from the merchant,
-           obviously this should not happen. To keep it simple, we just
-           alert the user to the error. */
-        alert("Failure to download contract " +
-              "(" + contract_request.status + "):\n" +
-              contract_request.responseText);
-      }
-    }
-  };
-  contract_request.onerror = function (e) {
-    /* There was an error obtaining the contract from the merchant,
-       obviously this should not happen. To keep it simple, we just
-       alert the user to the error. */
-      alert("Failure requesting the contract:\n" +
-            contract_request.statusText);
-  };
-  contract_request.send();
-}
-
-<script src="taler-wallet-lib.js"></script>
-<script>
-  taler.offerContractFrom("https://myshop/products/article/42", (err) => {
-    alert("Error while offering contract");
-  });
-</script>
diff --git a/articles/ui/ui.tex b/articles/ui/ui.tex
index b927fe034..47c9e01d2 100644
--- a/articles/ui/ui.tex
+++ b/articles/ui/ui.tex
@@ -747,8 +747,8 @@ merchant, the customer may choose to cover them.
 
 
 \begin{figure*}[h!]
- \lstset{language=JavaScript}
- \lstinputlisting{figs/taler-contract.js}
+ \lstset{language=HTML5}
+ \lstinputlisting{figs/taler-contract.html}
  \caption{Sample code to pass a contract to the Taler wallet.
           Here, the contract is fetched on-demand from the server.
           The {\tt taler\_pay()} function needs to be invoked
@@ -769,6 +769,32 @@ detect the presence of a Taler wallet (Figure~\ref{listing:presence}),
 so that the selection of alternative payment methods can be skipped if
 a Taler wallet is installed (as it is in Figure~\ref{fig:shopping}).
 
+\begin{figure*}[h!]
+  \lstset{language=JavaScript}
+\begin{lstlisting}
+{
+  "H_wire":"JCDAV...",
+  "amount":{"currency":"KUDOS","fraction":100000,"value":0},
+  "auditors":[],
+  "exchanges":[{"master_pub":"CQA...","url":"https://myexchange/"}],
+  "expiry":"/Date(1480119270)/",
+  "fulfillment\_url": "https://myshop/essay/...",
+  "max_fee":{"currency":"KUDOS","fraction":0,"value":3},
+  "merchant":{"address":"Somewhere","jurisdiction":"none","name":"Kudos Inc."},
+  "merchant_pub":"YDP...",
+  "products":[{
+    "description":"Essay: The GNU Project",
+    "price":{"currency":"KUDOS","fraction":100000,"value":0},
+    "product_id":0,"quantity":1}],
+  "refund_deadline":"/Date(1471522470)/",
+  "timestamp":"/Date(1471479270)/",
+  "transaction_id":249960194066269
+}
+\end{lstlisting}
+ \caption{Minimal Taler contract.}
+  \label{listing:contract}
+\end{figure*}
+
 \begin{figure*}[h!]
   \lstset{language={}}
 \begin{lstlisting}
@@ -790,7 +816,7 @@ X-Taler-Contract-Url: https://myshop/generate-contract?product=42
 \end{figure*}
 
 The offer URL of the Web shop can then initiate payments by sending a
-\emph{contract proposal} to the wallet, either via the HTTP status
+\emph{contract proposal} (Figure~\ref{listing:contract}) to the wallet, either via the HTTP status
 code {\tt 402 Payment Required} (Figure~\ref{listing:http-contract}), or via Taler's JavaScript API
 (Figure~\ref{listing:contract}).  The wallet then presents the
 contract to the user.  The format of the contract is in an extensible
-- 
cgit v1.2.3


From 9df967c6a090994a21139da56ee83a576cc63922 Mon Sep 17 00:00:00 2001
From: Florian Dold <florian.dold@gmail.com>
Date: Wed, 24 Aug 2016 14:20:42 +0200
Subject: contract description

---
 articles/ui/ui.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'articles/ui/ui.tex')

diff --git a/articles/ui/ui.tex b/articles/ui/ui.tex
index 47c9e01d2..dbe89e143 100644
--- a/articles/ui/ui.tex
+++ b/articles/ui/ui.tex
@@ -791,7 +791,7 @@ a Taler wallet is installed (as it is in Figure~\ref{fig:shopping}).
   "transaction_id":249960194066269
 }
 \end{lstlisting}
- \caption{Minimal Taler contract.}
+  \caption{Minimal Taler contract over a digital article with a value of \EUR{0.10}}
   \label{listing:contract}
 \end{figure*}
 
-- 
cgit v1.2.3


From 6ffbfff68334884bcef2fc894e4739b5d8aa71c8 Mon Sep 17 00:00:00 2001
From: Florian Dold <florian.dold@gmail.com>
Date: Wed, 24 Aug 2016 14:21:04 +0200
Subject: no escaping in lstlisting

---
 articles/ui/ui.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'articles/ui/ui.tex')

diff --git a/articles/ui/ui.tex b/articles/ui/ui.tex
index dbe89e143..0f0d66882 100644
--- a/articles/ui/ui.tex
+++ b/articles/ui/ui.tex
@@ -778,7 +778,7 @@ a Taler wallet is installed (as it is in Figure~\ref{fig:shopping}).
   "auditors":[],
   "exchanges":[{"master_pub":"CQA...","url":"https://myexchange/"}],
   "expiry":"/Date(1480119270)/",
-  "fulfillment\_url": "https://myshop/essay/...",
+  "fulfillment_url": "https://myshop/essay/...",
   "max_fee":{"currency":"KUDOS","fraction":0,"value":3},
   "merchant":{"address":"Somewhere","jurisdiction":"none","name":"Kudos Inc."},
   "merchant_pub":"YDP...",
-- 
cgit v1.2.3


From 0faf47cf88ba1a09efa3237508730399a8c30e9a Mon Sep 17 00:00:00 2001
From: Florian Dold <florian.dold@gmail.com>
Date: Wed, 24 Aug 2016 14:25:29 +0200
Subject: fix duplicate label

---
 articles/ui/ui.tex | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'articles/ui/ui.tex')

diff --git a/articles/ui/ui.tex b/articles/ui/ui.tex
index 0f0d66882..07be16254 100644
--- a/articles/ui/ui.tex
+++ b/articles/ui/ui.tex
@@ -792,7 +792,7 @@ a Taler wallet is installed (as it is in Figure~\ref{fig:shopping}).
 }
 \end{lstlisting}
   \caption{Minimal Taler contract over a digital article with a value of \EUR{0.10}}
-  \label{listing:contract}
+  \label{listing:json-contract}
 \end{figure*}
 
 \begin{figure*}[h!]
@@ -816,7 +816,7 @@ X-Taler-Contract-Url: https://myshop/generate-contract?product=42
 \end{figure*}
 
 The offer URL of the Web shop can then initiate payments by sending a
-\emph{contract proposal} (Figure~\ref{listing:contract}) to the wallet, either via the HTTP status
+\emph{contract proposal} (Figure~\ref{listing:json-contract}) to the wallet, either via the HTTP status
 code {\tt 402 Payment Required} (Figure~\ref{listing:http-contract}), or via Taler's JavaScript API
 (Figure~\ref{listing:contract}).  The wallet then presents the
 contract to the user.  The format of the contract is in an extensible
-- 
cgit v1.2.3


From fc4ea95df55a93ffb3843badf084036fdf1b65d9 Mon Sep 17 00:00:00 2001
From: Florian Dold <florian.dold@gmail.com>
Date: Wed, 24 Aug 2016 14:26:30 +0200
Subject: use EUR and not KUDOS in the example

---
 articles/ui/ui.tex | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

(limited to 'articles/ui/ui.tex')

diff --git a/articles/ui/ui.tex b/articles/ui/ui.tex
index 07be16254..36ac35252 100644
--- a/articles/ui/ui.tex
+++ b/articles/ui/ui.tex
@@ -774,17 +774,17 @@ a Taler wallet is installed (as it is in Figure~\ref{fig:shopping}).
 \begin{lstlisting}
 {
   "H_wire":"JCDAV...",
-  "amount":{"currency":"KUDOS","fraction":100000,"value":0},
+  "amount":{"currency":"EUR","fraction":100000,"value":0},
   "auditors":[],
   "exchanges":[{"master_pub":"CQA...","url":"https://myexchange/"}],
   "expiry":"/Date(1480119270)/",
   "fulfillment_url": "https://myshop/essay/...",
-  "max_fee":{"currency":"KUDOS","fraction":0,"value":3},
+  "max_fee":{"currency":"EUR","fraction":0,"value":3},
   "merchant":{"address":"Somewhere","jurisdiction":"none","name":"Kudos Inc."},
   "merchant_pub":"YDP...",
   "products":[{
     "description":"Essay: The GNU Project",
-    "price":{"currency":"KUDOS","fraction":100000,"value":0},
+    "price":{"currency":"EUR","fraction":100000,"value":0},
     "product_id":0,"quantity":1}],
   "refund_deadline":"/Date(1471522470)/",
   "timestamp":"/Date(1471479270)/",
-- 
cgit v1.2.3

