commit 56180148c5f641cfca0b7004a7ff2756231a4a7f
parent eb578f699bcff7bfcebdb21b2314745b9761f698
Author: Joel-Haeberli <haebu@rubigen.ch>
Date: Thu, 6 Jun 2024 17:12:08 +0200
docs: feedback
Diffstat:
13 files changed, 74 insertions(+), 53 deletions(-)
diff --git a/docs/content/abstract.tex b/docs/content/abstract.tex
@@ -1 +1 @@
-This thesis develops and implements a framework that allows for cashless withdrawals using GNU Taler, with the objective of increasing the easy onboarding and acceptance of GNU Taler as payment system. Currently, the GNU Taler only permits the withdrawal of digital cash in exchange for physical cash. The act of withdrawing digital cash in a physical manner serves to establish a direct trust relationship between the parties involved, and the GNU Taler Exchange is in a position to legally guarantee the security of the transaction. However, the withdrawal of GNU Taler via cashless systems, such as credit cards, is not feasible, as the GNU Taler Exchange lacks the requisite proof of successful payment. To address this gap, this thesis introduces a novel component, called cashless2ecash (C2EC), which establishes a reliable connection between the Taler ecosystem and payment service provider's terminals. The reference implementation establishes the process between the payment service provider Wallee and the GNU Taler Exchange through a newly created component, designated as C2EC. The implemented process guarantees the finality of the transaction to the GNU Taler Exchange and the terminal operator: The finality enables the withdrawal of digital cash using GNU Taler without the use of cash. The liability for the transaction is borne by the payment service provider, which assumes the guarantees for the GNU Taler Exchange.
-\ No newline at end of file
+This thesis develops and implements a framework that allows for cashless withdrawals using GNU Taler, with the objective of increasing the easy onboarding and acceptance of GNU Taler as payment system. Currently, the GNU Taler permits the withdrawal of digital cash using different means of payment. However, GNU Taler currently lacks the possibility using cashless payment means such as credit cards to withdraw digital cash. To address this gap, this thesis introduces a novel component, called cashless2ecash (C2EC), which establishes a reliable connection between the Taler ecosystem and payment service provider's terminals. The reference implementation establishes the process between the payment service provider Wallee and the GNU Taler Exchange through a newly created component, designated as C2EC. The implemented process guarantees the finality of the transaction to the GNU Taler Exchange and the terminal operator: The finality enables the withdrawal of digital cash using GNU Taler without the use of cash. The liability for the transaction is borne by the payment service provider, which assumes the guarantees for the GNU Taler Exchange.
+\ No newline at end of file
diff --git a/docs/content/architecture/c2ec.tex b/docs/content/architecture/c2ec.tex
@@ -2,9 +2,7 @@
The C2EC component is the central component in the cashless withdrawal of digital cash using Taler. It coordinates and initializes the parameters and mediates between the different stakeholders of a withdrawal. This finally allows the customer to withdraw digital cash from a reserve owned by the Exchange. To achieve this, C2EC provides an API which can be integrated and used by the terminal, wallet and the Exchange.
-The API of the C2EC (cashless2ecash) component handles the flow from the creation of a C2EC mapping to the creation of the reserve. For the integration into the Taler ecosystem, C2EC must implement the Taler Wirewatch Gateway API \cite{taler-wire-gateway-api} and the Taler Bank Integration API \cite{taler-bank-integration-api}.
-
-The exact specification can be found in the official Taler documentation repository as part of the core specifications of the bank integration \cite{taler-bank-integration-api}, wire gateway \cite{taler-wire-gateway-api} or the terminals API \cite{taler-terminal-api}.
+The API of the C2EC (cashless2ecash) component handles the flow from the creation of a C2EC mapping to the creation of the reserve. For the integration into the Taler ecosystem, C2EC must implement the Taler Wire-Gateway API \cite{taler-wire-gateway-api} and the Taler Bank Integration API \cite{taler-bank-integration-api}. The new Terminals API \cite{taler-terminal-api} is the interface of the payment service provider terminals to the GNU Taler ecosystem.
\subsection{C2EC Perspective}
From the perspective of C2EC, the system looks as follows:
diff --git a/docs/content/architecture/overview.tex b/docs/content/architecture/overview.tex
@@ -1,52 +1,63 @@
\section{Components}
-\begin{figure}[h]
+\begin{figure}[H]
\centering
- \includegraphics[width=0.7\textwidth]{pictures/diagrams/components_images.png}
+ \includegraphics[width=1.1\textwidth]{pictures/diagrams/components_images.png}
\caption{Involved components and devices}
\label{fig-logo-components}
\end{figure}
-The component diagram shows the components involved by the withdrawal using the terminal. Besides the payment mean owned by the user, two systems are involved and within each system two components are required to fulfill the task. The Taler ecosystem which represents the Taler wallet and the Taler Exchange (C2EC is a part of the Exchange) involved in the withdrawal process. In the terminal system, the terminal and the backend system of the terminal manufacturer are leveraged in the process.
+The component diagram in \autoref{fig-logo-components} shows the components involved by the withdrawal using the terminal. Besides the mean of payment owned by the user, the Taler payment system and a payment service provider (such as Wallee) is involved.
+
+To initiate the withdrawal, the wallet scans the QR code (1) and registers a reserve public key (2). After authorizing (3) the transaction using a credit card or other supported payment means, the transaction is authorized (4) via the payment service provider backend. The payment service provider sends back an authorization result (5) before the C2EC component receives the confirmation of payment from the payment service provider (6). As soon the payment was confirmed the wallet can withdraw the digital cash from the Exchange (7).
\section{Process}
\label{sec-architecture-process}
-\begin{figure}[h]
+\begin{figure}[H]
\centering
- \includegraphics[width=0.7\textwidth]{pictures/diagrams/system_overview.png}
+ \includegraphics[width=1.1\textwidth]{pictures/diagrams/system_overview.png}
\caption{Diagram of included components and their interactions}
\label{fig-diagram-all-components}
\end{figure}
-\autoref{fig-diagram-all-components} shows a high level overview of the components involved and how they interact. In an initial step (before the process is effectively started as depicted), the customer or owner of the terminal selects the Exchange, which is to be used for the withdrawal. The process is then started. The numbers in the diagrams are picked up by the description of the steps what is done between the different components:
+\autoref{fig-diagram-all-components} shows the interactions of the components. In a initial step (before the process is effectively started as depicted), the customer or owner of the terminal selects the Exchange, which is to be used for the withdrawal. The process is then started and goes through the following steps:
\begin{enumerate}
- \item The Wallee terminal requests to be notified when parameters are \textit{selected} by C2EC (step 0).
- \item The wallet scans the QR code at the terminal (step 1).
- \item The wallet registers a reserve public key and initializes the mapping to the withdrawal operation identifier (\textit{WOPID}) (step 2).
- \item The Terminals API of C2EC notifies the terminal, that the parameters were selected (step 3).
- \item The POS terminal initiates a payment to the account of the GNU Taler Exchange. For the payment the POS terminal requests a payment mean and the verification such as a pin code to authorize the payment (step 4).
- \item The terminal triggers the payment through the Wallee backend (step 5).
- \item The terminal receives the result of the payment (step 6).
- \begin{enumerate}
- \item successful
- \item unsuccessful
- \end{enumerate}
- \item The terminal sends a payment confirmation request to the Bank Integration API of C2EC (step 7).
- \item The C2EC component seeks confirmation for the payment by requesting the transaction of the Wallee backend (step 8).
- \item The C2EC updates the database by either setting the status of the withdrawal operation to \textit{confirmed} or \textit{abort}, depending on the response of the Wallee backend (step 9).
- \item The Exchange-Wirewatch asks the Wire Gateway API of C2EC for a list of transactions. Confirmed transaction will lead to the generation of a reserve at the Exchange (step 10).
- \item The wallet asks the Exchange to be notified, when a reserve with the reserve public key becomes available. The digital cash is then withdrawn by the wallet (step 11).
+ \item[0.] The Wallee terminal requests to be notified when parameters are \textit{selected} by C2EC.
+ \item[1.] The wallet scans the QR code at the terminal.
+ \item[2.] The wallet registers a reserve public key and initializes the mapping to the withdrawal operation identifier (\textit{WOPID}).
+ \item[3.] The Terminals API of C2EC notifies the terminal, that the parameters were selected.
+ \item[4.] The payment terminal initiates a payment to the account of the GNU Taler Exchange. For the payment the payment terminal requests a payment mean and the verification such as a pin code to authorize the payment.
+ \item[5.] The terminal triggers the payment through the Wallee backend.
+ \item[6.] The terminal receives the result of the payment, which is either successful or not.
+ \item[7.] The terminal sends a payment confirmation request to the Bank Integration API of C2EC.
+ \item[8.] The C2EC component seeks confirmation for the payment by requesting the transaction of the Wallee backend.
+ \item[9.] The C2EC updates the database by either setting the status of the withdrawal operation to \textit{confirmed} or \textit{abort}, depending on the response of the Wallee backend.
+ \item[10.] The Exchange-Wirewatch asks the Wire Gateway API of C2EC for a list of transactions. Confirmed transaction will lead to the generation of a reserve at the Exchange.
+ \item[11.] The wallet asks the Exchange to be notified, when a reserve with the reserve public key becomes available. The digital cash is then withdrawn by the wallet.
\end{enumerate}
-\begin{figure}[h]
+
+\newpage
+\KOMAoptions{paper=landscape,pagesize}
+\recalctypearea
+\thispagestyle{empty}
+\newgeometry{left=4cm, right=4cm, top=3cm, bottom=0cm}
+
+\begin{figure}[H]
\centering
- \includegraphics[width=0.7\textwidth]{pictures/diagrams/c2ec.png}
+ % [width=0.7\textwidth]
+ \includegraphics[width=1.7\textwidth]{pictures/diagrams/c2ec.png}
\caption{Process of a withdrawal using a credit card}
\label{fig-diagram-all-sequence}
\end{figure}
+\restoregeometry
+\newpage
+\KOMAoptions{paper=portrait,pagesize}
+\recalctypearea
+
The diagram in \autoref{fig-diagram-all-sequence} shows the high level flow to withdraw digital cash using the credit card terminal and Taler. It shows when the components of \autoref{fig-diagram-all-components} interact with each other. It shows the implementation of the flow. terminal, wallet and Exchange are linked leveraging a \textit{WOPID} initially generated by the terminal and presented to the Exchange by the withdrawing wallet accompanied by a reserve public key.
The process requires the terminal, the wallet, the C2EC component and the Exchange who interact with each other. In this section the highlevel process is explained as showed in \autoref{fig-diagram-all-sequence}.
@@ -57,19 +68,19 @@ The terminal initiates the withdrawal leveraging an application which works as f
\begin{enumerate}
\item At startup of the application, the terminal loads the C2EC configuration.
- \item When a user wishes to do a withdrawal, the owner of the terminal opens the application and initiates a new withdrawal. A withdrawal is basically a funds transfer to the IBAN account of the Exchange.
+ \item When a user wishes to do a withdrawal, the owner of the terminal opens the application and initiates a new withdrawal entering the Amount to withdraw.
\begin{enumerate}
- \item terminal sets up a withdrawal by aksing C2EC to setup a \textit{WOPID}.
- \item The application starts long polling at the C2EC and awaits the selection of the reserve parameters mapped to the \textit{WOPID}. The parameters are sent by the wallet to C2EC.
+ \item The terminal sets up a withdrawal by asking C2EC to setup a \textit{WOPID}.
+ \item The terminal calculates fees and shows them to the customer.
\item The \textit{WOPID} is packed into a QR code (with Exchange and amount entered by the terminal owner).
- \item terminal calculates fees and shows summary and the Terms of Service (ToS) of Taler.
+ \item The application starts long polling at the C2EC and awaits the selection of the reserve parameters mapped to the \textit{WOPID}. The parameters are sent by the wallet to C2EC.
\item The user accepts the offer and agrees with the ToS.
\item The QR code is displayed.
\end{enumerate}
\item The user now scans the QR Code using his wallet.
\item The application receives the notification of the C2EC, that the parameters for the withdrawal were selected.
\item The terminal executes the payment (after user presented their credit card, using the terminal backend).
- \item The terminal initiate the fund transfer to the Exchange. The customer has to authorize the payment by presenting his payment card and authorizing the transaction with their pin. The terminal processes the payment over the an available connector configured on the Wallee backend. Possible connectors are for example Master Card, VISA, TWINT, Maestro, Post Finance, and others \cite{wallee-available-connectors}.
+ \item The terminal initiate the fund transfer to the Exchange. The customer has to authorize the payment by presenting his payment card and possibly their pin. The terminal processes the payment over the an available connector configured on the Wallee backend. Possible connectors are for example Master Card, VISA, TWINT, Maestro, Post Finance, and others \cite{wallee-available-connectors}.
\begin{enumerate}
\item It presents the result to the user.
\item It tells the C2EC, that the payment was successful.
@@ -81,12 +92,12 @@ The terminal initiates the withdrawal leveraging an application which works as f
The C2EC component manages the withdrawal using a third party provider (e.g. Wallee) and seeks guarantees in order to create a reserve containing digital cash which can be withdrawn by the wallet.
\begin{enumerate}
- \item The C2EC component retrieves the setup request for withdrawal which will lead to generation of the \textit{WOPID}.
- \item The C2EC component retrieves a long polling request for a \textit{WOPID} (from the terminal).
- \item The C2EC component retrieves a request including a \textit{WOPID} and a reserve public key.
+ \item The C2EC component receives the setup request for withdrawal which will lead to generation of the \textit{WOPID}.
+ \item The C2EC component receives a long polling request for a \textit{WOPID} (from the terminal).
+ \item The C2EC component receives a request including a \textit{WOPID} and a reserve public key.
\item The C2EC component validates the request and adds the key to the mapping. This establishes the \textit{WOPID} to reserve public key mapping.
- \item The C2EC component ends the long polling from the terminal.
- \item The C2EC component receives the confirmation request of the terminal.
+ \item The C2EC component answers the long polling from the terminal.
+ \item The C2EC component receives the confirmation request of the terminal or is requested to abort the withdrawal.
\item The C2EC component verifies the notification by asking the provider backend for confirmation.
\item The C2EC component tells the Taler Wirewatch component of the Exchange about incoming transactions including the reserve public key of the withdrawal (which will eventually create a withdrawable reserve).
\end{enumerate}
@@ -99,5 +110,5 @@ The wallet must attest its presence to the terminal by registering a reserve pub
\item The wallet scans the QR Code (\textit{WOPID}, Exchange information and amount) on the terminal.
\item The wallet creates a reserve key pair.
\item The wallet sends the reserve public key to C2EC using the \textit{WOPID} to map the public key to a withdrawal operation.
- \item The wallet can eventually withdraw digital cash from the created reserve.
+ \item The wallet will be notified by the answer to a long-polling request when the digital cash is available at the Exchange's reserve belonging to the registered reserve public key.
\end{enumerate}
diff --git a/docs/content/implementation/a-c2ec.tex b/docs/content/implementation/a-c2ec.tex
@@ -11,7 +11,7 @@ The implementation of the terminals API can be found in \autoref{sec-implementat
\begin{figure}[H]
\centering
- \includegraphics[width=0.7\textwidth]{pictures/diagrams/c2ec_apis.png}
+ \includegraphics[width=1.1\textwidth]{pictures/diagrams/c2ec_apis.png}
\caption{C2EC and its interactions with various components}
\label{fig-diagram-c2ec-apis-sequence}
\end{figure}
diff --git a/docs/content/implementation/a-providers.tex b/docs/content/implementation/a-providers.tex
@@ -48,6 +48,6 @@ To integrate Wallee as provider into C2EC, the provider client interface as desc
Additionally to the Wallee Client a Simulation Client was implemented which can be used for testing. It allows end-to-end tests of the C2EC component by stubbing the actions performed against a provider and returning accurate results.
-\subsubsection{Adding a new provider}
+\subsubsection{Adding Providers}
Adding a new provider requires the implementation of the client- and transaction-interfaces as described in \autoref{sec-provider-client-interface} and \autoref{sec-provider-transaction-interface}. The \texttt{SetupClient} function of the client interface must make sure to register itself to the global map of registered providers (accessible through \texttt{PROVIDER\_CLIENTS}). Additionally, to the newly added provider implementation, the provider must also be registered in the database (\autoref{sec-implementation-cli} describes how this could work). When the client adds itself to the registered providers clients, the application will load the provider client at startup of C2EC. If C2EC fails to find the specified provider in the database, it won't start. This behaviour makes sure, that only needed providers are running and that if a new provider was added, it is effectively registered and configured correctly (the setup function of the provider interface is responsible to check the provider specific configuration and do readiness or liveness checks if needed). If the new added provider requires a new payto target type, adding a new entry to the GANA in order to prevent conflicts in the future might be a good idea.
diff --git a/docs/content/implementation/b-terminal.tex b/docs/content/implementation/b-terminal.tex
@@ -1,4 +1,4 @@
-\section{Wallee POS Terminal}
+\section{Wallee Payment Terminal}
\subsection{Withdrawal Flow}
\label{sec-wallee-withdrawal-flow}
diff --git a/docs/content/implementation/f-deployment.tex b/docs/content/implementation/f-deployment.tex
@@ -15,12 +15,12 @@ For the deployment the it is recommended to use a Debian Linux machine. To prepa
\item Set the postgres variables \texttt{PGHOST} and \texttt{PGPORT} to the correct values if needed
\end{enumerate}
-For the deployment of the Wallee POS Terminal app, the following steps are necessary to prepare the usage of the cashless withdrawals leveraging Wallee:
+For the deployment of the Wallee payment terminal app, the following steps are necessary to prepare the usage of the cashless withdrawals leveraging Wallee:
\begin{enumerate}
\item A running deployment of C2EC must be accessible.
\item Wallee must be a registered provider at the C2EC instance.
- \item The Terminal must be registered at C2EC.
+ \item The terminal must be registered at C2EC.
\end{enumerate}
\subsection{Setup}
@@ -48,7 +48,7 @@ When the simulation shall be installed the \textit{prod}-flag in the C2EC config
When the provider and the terminal was successfully registered, the configuration located inside the \texttt{C2EC\_HOME} must be adjusted to the correct values. Once this is done, the C2EC process can be started using \texttt{./c2ec -c [PATH-TO-CONFIGFILE]}.
-The POS terminal app must be deployed by the Wallee support. The Android package (APK) will be installed over the air by them once the APK was accepted and signed by them. To get a signed APK, it must be sent to \textit{info@wallee.com}. They will first check and sign the APK. After this step another message must be sent to them with a link to the signed APK. With this request the information of the terminal to install the application on must be given. Wallee will then rollout the app on the specified device.
+The terminal app must be deployed by the Wallee support. The Android package (APK) will be installed over the air by them once the APK was accepted and signed by them. To get a signed APK, it must be sent to \textit{info@wallee.com}. They will first check and sign the APK. After this step another message must be sent to them with a link to the signed APK. With this request the information of the terminal to install the application on must be given. Wallee will then rollout the app on the specified device.
\subsubsection{Making C2EC Accessible Via Internet}
diff --git a/docs/content/introduction/goal.tex b/docs/content/introduction/goal.tex
@@ -6,7 +6,7 @@ The framework aims to achieve the following key objectives:
\begin{enumerate}
\label{sec-goals-properties}
- \item Finality: The operator of the taler is not liable for any losses incurred in connection with the payment.
+ \item Finality: The operator of the Taler Exchange is not liable for any losses incurred in connection with the payment.
\item Convenience: The user experience adheres to established patterns.
\item Abort: The payment flow is robust and secure, and the option to abort transactions without the loss of money is available.
\end{enumerate}
@@ -15,6 +15,6 @@ The framework aims to achieve the following key objectives:
To achieve these goals C2EC is implemented as part of GNU Taler. C2EC mediates between the Taler Exchange and the terminal provider. This includes checking that the transaction of the debitor reaches the account of the Exchange and the digital cash can be withdrawn by the user using their wallet.
-\subsection{Paydroid POS Terminal}
+\subsection{Paydroid Payment Terminal}
-The Wallee payment terminal, also called Point of Sales (POS) terminal, interfaces with payment cards (Credit Cards, Debit Cards) and other means of payment (e.g. Twint) to make electronic fund transfers, i.e. a fund transfer to a given GNU Taler Exchange. For our purpose, we extend the functionality of the terminal to initiate the corresponding counter payment from the Exchange to the GNU Taler wallet of the payee.
+The Wallee payment terminal, interfaces with payment cards (credit cards, debit cards) and other means of payment (e.g. Twint) to make electronic fund transfers, i.e. a fund transfer to a given GNU Taler Exchange. For our purpose, we extend the functionality of the terminal to initiate the corresponding counter payment from the Exchange to the GNU Taler wallet of the payee.
diff --git a/docs/content/introduction/introduction.tex b/docs/content/introduction/introduction.tex
@@ -6,9 +6,9 @@ In March 2022, the European Central Bank (ECB) found that an \textbf{easy onboar
The findings of the European Central Bank also extend to the GNU Taler, the software-based microtransaction and electronic payment system. For the GNU Taler to be widely accepted as a payment system, it is of utmost importance that the onboarding process for new users be as straightforward and user-friendly as possible. For this reason, it is essential that a variety of methods exist for the withdrawal of digital cash in Taler.
-This thesis develops an additional withdrawal method by implementing a framework that allows cashless withdrawals in GNU Taler. Currently, it is possible to withdraw digital cash from a bank that operates a Taler Exchange and integrates the respective API. At the time of writing, only one bank is engaged in the process of establishing a Taler Exchange; bank GLS \cite{taler-bank-gls}. Furthermore, at the Bern University of Applied Sciences, an exchange is operated, and digital cash can be withdrawn at the secretariat using cash.
+This thesis develops an additional withdrawal method by implementing a framework that allows cashless withdrawals in GNU Taler. Currently, it is possible to withdraw digital cash from a bank that operates a Taler Exchange and integrates the respective API. At the time of writing, only two banks are engaged in the process of establishing a Taler Exchange; GLS bank \cite{taler-bank-gls} and MagNet bank \cite{ngi-taler}. Furthermore, at the Bern University of Applied Sciences, an exchange is operated allowing the withdrawal of digital cash at the secretariat using cash.
-To make the access to digital cash using Taler easier and allow a faster uptake of the payment system Taler, a framework for cashless withdrawal of digital cash is proposed and implemented in order to open new doors for the integration and adoption of the Taler payment system within the society.
+To make the access to digital cash using Taler easier and allow a faster uptake of the payment system Taler, a framework for cashless withdrawal of digital cash is proposed and implemented in order to open new doors for the integration and adoption of the Taler payment system within society.
To make the withdrawal using a credit card or other means of payment possible, the GNU Taler facilities must be extended and integrated with established payment service providers. The integration must enable the communication between the Taler ecosystem and payment service providers and their terminals.
diff --git a/docs/content/results/discussion.tex b/docs/content/results/discussion.tex
@@ -27,8 +27,6 @@ Due to the short time available during the thesis, features and integrations are
\subsection{Improvements}
\begin{enumerate}
- \item Wallet integration: the integration of the wallet needs to be further tested
- \item Run the existing implementation as part of the BFH Taler CHF-Exchange
\item Paydroid app: Run a Wallee terminal on behalf of the BFH.
\item Paydroid app: The app must be released including the credentials. This is a security risk since these credentials are shipped through (secure?) channels. A way to register to an exchange in the app is a nice extension.
\item C2EC: Remove doubled provider structures. Currently providers are saved to the database and must be configured in the configuration. To make the setup and management easier, the providers can only be configured inside the configuration.
diff --git a/docs/project.bib b/docs/project.bib
@@ -458,3 +458,11 @@
publisher={Bruno Fauser, Hinterkappelen, fauser.ch},
year={2023},
}
+
+@misc{ngi-taler,
+ author ={NGI TALER},
+ title ={NGI TALER},
+ url ={https://taler.net/en/ngi-taler.html},
+ howpublished ={\url{https://taler.net/en/ngi-taler.html}},
+}
+
diff --git a/docs/thesis.pdf b/docs/thesis.pdf
Binary files differ.
diff --git a/docs/thesis.tex b/docs/thesis.tex
@@ -31,6 +31,8 @@
\usepackage{amsfonts} % set of miscellaneous TeX fonts that augment the standard CM
\usepackage{amssymb} % mathematical special characters
+\usepackage{enumerate}
+
\usepackage{siunitx}
\usepackage{graphicx} % integration of images
@@ -56,6 +58,10 @@
\usepackage{pdfpages}
\usepackage{pgfgantt}
+
+\usepackage{typearea} % landscape pages
+\usepackage{geometry} % set page margins for landscape pages
+
\usetikzlibrary{arrows.meta,fit,positioning,shapes.geometric}
%---------------------------------------------------------------------------
