commit af3256d381a0e8fa505b7e0fa683a7540beb2357
parent 26cf1bb931c46ba5cdfe679a9e402c14be252091
Author: Joel-Haeberli <haebu@rubigen.ch>
Date: Sat, 1 Jun 2024 14:42:56 +0200
docs: feedback from Meret
Diffstat:
9 files changed, 77 insertions(+), 67 deletions(-)
diff --git a/docs/content/abstract.tex b/docs/content/abstract.tex
@@ -1 +1 @@
-In order to withdraw digital cash in GNU Taler, the GNU Taler Exchange needs guarantees to legally secure the transaction. Withdrawing digital cash using Taler physically establishes direct trust, since cash can be used in order to withdraw digital cash and the transaction is completed. If you want to withdraw digital cash using cashless systems like credit cards, the GNU Taler Exchange has no proof that the payment has succeeded. In order to fill this cap, this thesis specifies and implements a framework allowing cashless withdrawals using GNU Taler. The reference implementation establishes a trust relationship between the payment service provider Wallee and the GNU Taler Exchange through a newly created component called \textit{C2EC}. This enables a trust relationship between the GNU Taler Exchange and the terminal operator which allows withdrawing Taler without using cash. The liability for the transaction is on the side of the payment service provider, which establishes the guarantees for the GNU Taler Exchange.
+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
diff --git a/docs/content/architecture/c2ec.tex b/docs/content/architecture/c2ec.tex
@@ -1,27 +1,27 @@
\section{C2EC}
-The \textbf{c}ashless\textbf{2ec}ash (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 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 docs 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 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}.
\subsection{C2EC Perspective}
From the perspective of C2EC, the system looks as follows:
\begin{itemize}
- \item Is requested by the Taler wallet to register a new \textit{wopid} to reserve public key mapping.
- \item Is notified by the terminal (e.g. a Wallee terminal) about a payment.
- \item Confirms a payment by requesting the payment confirmation from the payment service provider backend (e.g. Wallee backend)
- \item Supplies the Taler Wire Gateway API that the respective Taler Exchange can retrieve fresh transactions and create reserves which are then created and can be withdrawn by the Taler wallet.
+ \item The C2EC component is requested by the Taler wallet to register a new \textit{WOPID} to reserve public key mapping.
+ \item Then, the C2EC component is notified by the terminal (e.g. a Wallee terminal) about a payment.
+ \item The C2EC component confirms a payment by requesting the payment confirmation from the payment service provider backend (e.g. Wallee backend)
+ \item The C2EC component runs the Taler Wire Gateway API that the respective Taler Exchange can retrieve fresh transactions and create reserves. This reserves are eventually withdrawn by the customer using their Taler wallet.
\end{itemize}
\subsection{Withdrawal-Operation state transitions}
\label{sec-architecture-state-transitions}
-Basically C2EC mediates between the stakeholders of a withdrawal in order to maintain the correct state of the withdrawal. It decides when a withdrawal's status can be transitioned. The diagram in \autoref{fig-withdrawal-operation-state-transition-diagram} shows the transitions of states in which a withdrawal operation can be and which events will trigger a transition. The term confirmation in this context means, that the backend of the provider was asked and the transaction was successfully processed (or not). So if a transaction was successfully processed by the provider, the final state is the success case \textit{confirmed}, where the Exchange will create a reserve and allow the withdrawal. If the confirmation fails, thus the provider could not process the transaction successfully, the failure case \textit{aborted}, is reached as final state.
+The C2EC component mediates between the stakeholders of a withdrawal in order to maintain the correct state of the withdrawal. It decides when a withdrawal's status can be transitioned. The diagram in \autoref{fig-withdrawal-operation-state-transition-diagram} shows the transitions of states in which a withdrawal operation can be and which events will trigger a transition. The term confirmation in this context means, that the backend of the provider was asked and the transaction was successfully processed (or not). So if a transaction was successfully processed by the provider, the final state is the success case \textit{confirmed}, where the Exchange will create a reserve and allow the withdrawal. If the confirmation fails, indicating the provider could not process the transaction successfully, the failure case is \textit{aborted}. \textit{confirmed} and \textit{aborted} are the final states.
-\begin{figure}[h]
+\begin{figure}[H]
\centering
\includegraphics[width=0.7\textwidth]{pictures/diagrams/withdrawal-op-state-transition.png}
\caption{Withdrawal Operation state transition diagram}
@@ -34,7 +34,7 @@ Terminals and the Exchange Wire Watch which authenticate against the C2EC API us
\subsection{The C2EC RESTful API}
-All components involved in the withdrawal process must interact with the C2EC component. Therefore this section describes the various API implemented in the C2EC component. The description contains a short list of the consumers of the respective API. Consumer in this context does not necessarily mean that data is consumed but rather that the consumer uses the API to either gather data or send reqeusts or data to C2EC.
+All components involved in the withdrawal process must interact with the C2EC component. Therefore this section describes the various API implemented in the C2EC component. The description contains a short list of the consumers of the respective API. Consumer in this context does not necessarily mean that data is consumed but rather that the consumer uses the API to either gather data or send requests or data to C2EC.
\subsubsection{Terminals API}
\label{sec-architecture-c2ec-terminals-api}
@@ -51,7 +51,7 @@ That terminals can initiate and serve withdrawals in Taler, the Terminals API \c
\textbf{Fees}
-An important aspect of the withdrawal flow using established third party providers are the fees. When the withdrawal operation is not supplied by some Exchanges as standard service, the provider possibly wants to charge fees to the customer in order to make a profit and cover its costs. It is likely that these costs are rolled over to the customer in form of fees. This means that a terminal must have the capability to inform the Terminals API about fees. This can be achieved through the confirmation request in the Terminals API. For example cashback is causing a lot of fees to the merchants supporting it:
+Fees are an important aspect of the withdrawal flow using established payment service providers. When the withdrawal operation is not supplied by some Exchanges as standard service, the provider possibly wants to charge fees to the customer in order to make a profit and cover its costs. It is likely that these costs are rolled over to the customer in form of fees. This means that a terminal must have the capability to inform the Terminals API about fees. This can be achieved through the confirmation request in the Terminals API. Also the Exchange operator itself wants to charge fees to cover its costs. For example cashback is causing a lot of fees to the merchants supporting it:
\begin{quote}
\textit{de:}Die Händler zahlen jedoch für den Cashback-Service bereits Gebühren an
@@ -65,33 +65,33 @@ Withdrawals by the wallet with a C2EC are based on withdrawal operations which r
\subsection{Taler Wirewatch Gateway API}
-The Taler Wirewatch Gateway \cite{taler-wire-gateway-api} must be implemented in order to capture incoming transactions and allow the withdrawal of digital cash. The specification of the Taler Wirewatch Gateway can be found in the official Taler documentation \cite{taler-wire-gateway-api}.
+The Taler Wirewatch Gateway API \cite{taler-wire-gateway-api} must be implemented in order to capture incoming transactions and allow the withdrawal of digital cash. The specification of the Taler Wirewatch Gateway can be found in the official Taler documentation \cite{taler-wire-gateway-api}.
-The wirewatch gateway helps the Exchange communicate with the C2EC component using a the API. It helps the Exchange to fetch guarantees, that a certain transaction went through and that the reserve can be created and withdrawn. This will help C2EC to capture the transaction of the Terminal Backend to the Exchange's account and therefore allow the withdrawal by the customer. Therefore the wirewatch gateway API is implemented as part of C2EC. When the wirewatch gateway can get the proof, that a transaction was successfully processed, the Exchange will create a reserve with the corresponding reserve public key.
+The Wirewatch Gateway helps the Exchange communicate with the C2EC component using the API. It helps the Exchange to fetch guarantees, that a certain transaction went through and that the reserve can be created and withdrawn. This will help C2EC to capture the transaction of the Terminal Backend to the Exchange's account and therefore allow the withdrawal by the customer. The Wirewatch Gateway API is implemented as part of C2EC. When the Wirewatch Gateway can get the proof, that a transaction was successfully processed, the Exchange will create a reserve with the corresponding reserve public key.
-For C2EC not all endpoints of the Wire Gateway API are needed. Therefore the endoints which are not needed will be implemented but always return http status code 400 with explanatory error details as specified by the specification.
+For C2EC not all endpoints of the Wire Gateway API are needed. Therefore the endoints which are not needed will be implemented but always return http status code 400.
\subsection{C2EC Entities}
\label{sec-architecture-entities}
-The entities of the C2EC component must track two different aspects. The first is the mapping of a nonce (the \texttt{WOPID}) to a reserve public key to enable withdrawals and the second aspect is the authentication and authorization of terminals allowing withdrawals owned by terminal providers like \textit{Wallee}.
+The entities of the C2EC component must track two different aspects. The first is the mapping of a nonce (the \textit{WOPID}) to a reserve public key to enable withdrawals and the second aspect is the authentication and authorization of terminals allowing withdrawals owned by terminal providers like \textit{Wallee}.
The detailed explanation and ERD can be found in \autoref{sec-implementation-database}.
\subsubsection{Terminal Provider}
-Entity displayed in \autoref{fig-erd-terminal-provider} describing providers of C2EC compliant terminals. The name of the provider is important, because it decides which flow shall be taken in order to attest the payment. For example will the name \textit{Wallee} signal the terminal provider to trigger the confirmation flow of \textit{Wallee} once the payment notification for the withdrawal reaches C2EC.
+\autoref{fig-erd-terminal-provider} describes the provider entity of C2EC compliant terminals. The name of the provider is important, because it decides which flow shall be taken in order to attest the payment. For example will the name \textit{Wallee} signal the terminal provider to trigger the confirmation flow of \textit{Wallee} once the payment notification for the withdrawal reaches C2EC.
\subsubsection{Terminal}
Entity displayed in \autoref{fig-erd-terminal} contains information about terminals of providers. This includes the provider they belong to and an access-token, which is generated by the operator of the C2EC component. It allows authenticating the terminal. A terminal belongs to one terminal provider.
\subsubsection{Withdrawal}
-Entity displayed in \autoref{fig-erd-withdrawal} represents the withdrawal processes initiated by terminals. This entity contains information about the withdrawal like the amount, which terminal the withdrawal was initiated from and which reserve public key is used to create a reserve in the Exchange.
+The Entity displayed in \autoref{fig-erd-withdrawal} represents the withdrawal processes initiated by terminals. This entity contains information about the withdrawal like the amount, which terminal the withdrawal was initiated from and which reserve public key is used to create a reserve in the Exchange.
\subsubsection{Relationships}
\label{sec-architecture-entities-relationships}
The structure of the three entities form a tree which is rooted at the terminal provider. Each provider can have many terminals and each terminal can have many withdrawals. The reverse does not apply. A withdrawal does always belong to exactly one terminal and a terminal is always linked to exactly one provider. These relations are installed by using foreign keys, which link the sub-entities (Terminal and Withdrawal) to their corresponding owners (Provider and Terminal). A provider owns its terminals and a terminal owns its Withdrawals.
-\begin{figure}[h]
+\begin{figure}[H]
\centering
\includegraphics[width=0.7\textwidth]{pictures/database/logical_model_relations.png}
\caption{Relationships of the entities.}
diff --git a/docs/content/architecture/overview.tex b/docs/content/architecture/overview.tex
@@ -22,11 +22,11 @@ The component diagram shows the components involved by the withdrawal using the
\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:
\begin{enumerate}
- \item Wallee terminal requests to be notified when parameters are \textit{selected} by C2EC (step 0).
+ \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 \textit{WOPID} (step 2).
+ \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 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 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}
@@ -35,9 +35,9 @@ The component diagram shows the components involved by the withdrawal using the
\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 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 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).
\end{enumerate}
\begin{figure}[h]
@@ -56,20 +56,20 @@ The process requires the terminal, the wallet, the C2EC component and the Exchan
The terminal initiates the withdrawal leveraging an application which works as follows:
\begin{enumerate}
- \item At startup of the application, the terminal loads the C2EC configuration
+ \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.
\begin{enumerate}
- \item terminal sets up a withdrawal by aksing C2EC to setup a \textit{WOPID}
+ \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 \textit{WOPID} is packed into a QR code (with Exchange and amount entered by the terminal owner)
+ \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 user accepts the offer, agrees with the ToS
- \item QR code is displayed
+ \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 his 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 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}.
\begin{enumerate}
\item It presents the result to the user.
\item It tells the C2EC, that the payment was successful.
@@ -81,23 +81,23 @@ 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 C2EC retrieves setup request for withdrawal which will lead to generation of the \textit{WOPID}.
- \item C2EC retrieves a long polling request for a \textit{WOPID} (from the terminal).
- \item C2EC retrieves a request including a \textit{WOPID} and a reserve public key.
- \item C2EC validates the request and adds the key to the mapping. This establishes the \textit{WOPID} to reserve public key mapping.
- \item C2EC ends the long polling from the terminal.
- \item C2EC receives confirmation request of the terminal.
- \item C2EC verifies the notification by asking the provider backend for confirmation.
- \item C2EC responds to an incoming transaction request of the Taler Wirewatch of the Exchange with the reserve public key of the withdrawal (which will eventually create a withdrawable reserve).
+ \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 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 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}
\subsection{The Wallet}
-The wallet must attest its presence to the terminal by registering a reserve public key with the respective \textit{WOPID} which will hold the digital cash that can eventually be withdrawn by the wallet. The process of the wallet is already implemented through the Bank-Integration API \cite{wallet-withdrawal} and only documented for completeness.
+The wallet must attest its presence to the terminal by registering a reserve public key with the respective \textit{WOPID} which will hold the digital cash that can eventually be withdrawn by the wallet. The process of the wallet is already implemented through the Bank-Integration API \cite{wallet-withdrawal} and only documented for completeness. The Bank-Integration API is implemented by C2EC.
\begin{enumerate}
- \item The wallet scans the QR Code (\textit{WOPID}, Exchange information and amount) on the terminal
- \item It creates a reserve key pair
- \item The wallet sends the reserve public key to the C2EC using the \textit{WOPID} to pin the public key to a withdrawal operation.
+ \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.
\end{enumerate}
diff --git a/docs/content/architecture/wallee.tex b/docs/content/architecture/wallee.tex
@@ -5,16 +5,16 @@ Wallee offers level 1 PCI-DSS \cite{pci-dss} compliant payment processes to its
From the perspective of Wallee, the system looks as follows:
\begin{itemize}
- \item Uses the Bank-Integration API of \textit{C2EC} to get notified about parameter selection and inform \textit{C2EC} about the payment.
- \item Needs the credit card of the customer in order to execute the payment.
- \item Uses the \textit{Wallee Backend} to execute the payment using the supplied Android Till SDK \autoref{ref-wallee-till-api}
+ \item The Wallee terminal uses the Bank-Integration API of \textit{C2EC} to get notified about parameter selection and inform \textit{C2EC} about the payment.
+ \item The Wallee terminal needs the credit card of the customer to authorize the payment.
+ \item The Wallee terminal uses the \textit{Wallee Backend} to authorize the payment using the supplied Android Till SDK \autoref{ref-wallee-till-api}
\end{itemize}
\subsection{Wallee Terminal}
-Wallee Terminals are based on android and run a modified, certified android version as operating system. Thus they can be used for payments and establish strong authentication in a trusted way.
+Wallee Terminals are based on Android and run a modified, certified android version as operating system. Thus they can be used for payments and establish strong authentication in a trusted way.
\subsubsection{Withdrawal Operation Identifier}
-The \textbf{W}ithdrawal-\textbf{OP}eration-\textbf{ID}entifier (\textit{WOPID}) is leveraged by all components to establish the connection to an entry in the withdrawal table (\autoref{fig-erd-withdrawal}) of C2EC. The \textit{WOPID} is therefore crucial and every participant of the withdrawal must eventually gain knowledge about the value of the \textit{WOPID} in order to process the withdrawal. The \textit{WOPID} is created by the Terminal and advertised to the Exchange by requesting notification, when the reserve public key belonging to the \textit{WOPID} was received and the mapping could be created.
+The \textbf{W}ithdrawal-\textbf{OP}eration-\textbf{ID}entifier (\textit{WOPID}) is leveraged by all components to establish the connection to an entry in the withdrawal table (\autoref{fig-erd-withdrawal}) of C2EC. The \textit{WOPID} is therefore crucial and every participant of the withdrawal must eventually gain knowledge about the value of the \textit{WOPID} to process the withdrawal. The \textit{WOPID} is created by the Terminal and advertised to the Exchange by requesting notification, when the reserve public key belonging to the \textit{WOPID} was received and the mapping could be created.
The Wallet gains the \textit{WOPID} value when scanning the QR code at the Terminal and then sends the \textit{WOPID} (and the other parameters) to the Exchange.
\textbf{Creation of the WOPID}
@@ -23,10 +23,10 @@ The creation of the \textit{WOPID} is a crucial step in the process. The \textit
\subsubsection{Wallee Till API}
\label{ref-wallee-till-api}
-Wallee supplies the Wallee Android Till SDK \cite{wallee-till-sdk} which allows the implementation of custom application for their android based terminals. The API facilitates the integration with the Wallee backend and using it to create payments.
+Wallee supplies the Wallee Android Till SDK \cite{wallee-till-sdk} which allows the implementation of custom application for their android based terminals. The API facilitates the integration with the Wallee backend and uses it to authorize payments.
\subsection{Wallee Backend and API}
-Terminals of Wallee are used to communicate with the customer at the shop of the merchant. The payment and processing of the transaction is run on the \textit{Wallee Backend}. The \textit{Wallee Backend} is used by C2EC to attest a payment, when a \texttt{C2ECPaymentNotification} message reaches C2EC. The \textit{Wallee Backend} is also used in order to do refunds, in case something goes wrong during the payment. Therefore the API of \textit{Wallee Backend} is used to collect this information or process a refund. Wallee structures its API using \textit{Services}. For C2EC this means that the \textit{Transaction Service} \cite{wallee-transaction-service-docs} and \textit{Refund Service} \cite{wallee-refund-service-docs} must be implemented.
+Terminals of Wallee are used to communicate with the customer at the shop of the merchant. The payment and processing of the transaction is run on the \textit{Wallee Backend}. The \textit{Wallee Backend} is used by C2EC to attest a payment, when a \texttt{C2ECPaymentNotification} message reaches C2EC. The \textit{Wallee Backend} is also used to do refunds, in case something goes wrong during the payment. Therefore the API of \textit{Wallee Backend} is used to collect this information or process a refund. Wallee structures its API using \textit{Services}. For C2EC this means that the \textit{Transaction Service} \cite{wallee-transaction-service-docs} and \textit{Refund Service} \cite{wallee-refund-service-docs} must be implemented.
\subsubsection{Transaction Service}
The \textit{Transaction Service} is used by C2EC to attest a transaction was successfully processed and the reserve can be created by the \textit{Exchange}. Therefore the \texttt{GET /api/transaction/read} API of the \textit{Transaction Service} is used. If the returned transaction is in state \textit{fulfill}, the transaction can be stored as \textit{completion\_proof} for the withdrawal as specified in the withdrawal table \autoref{fig-erd-withdrawal} and the withdrawal status can be transitioned to \textit{confirmed}. This will tell the \textit{Exchange} to create the reserve which can eventually be withdrawn by the wallet.
@@ -46,4 +46,4 @@ In case a refund becomes necessary, which might occur if a transaction does not
Wallee allows to trigger refunds using the Refund Service of the Wallee backend. The service allows to trigger a refund given a transaction identifier. Therefore the C2EC component can trigger the refund using the refund service if needed. The payto-uri retrieved as debit account by the wire gateway API, is leveraged to delegate the refund process to the Wallee Backend using the Refund Service and parsing the transaction identifier of the payto-uri.
\subsection{Extensibility}
-The flow is extensible and other providers like Wallee might be added. They might want to register their own refund payto-uri (if needed) with the GANA and then the refund process can be implemented likewise.
+The flow is extensible and other providers like Wallee might be added. New payment service providers might want to register their own refund payto-uri with the GNU Assigned Numbers Authority (GANA) if needed. This will allow an easy integration of the refund process into the system. C2EC establishes structures which abstracts the general flow and the integration of new provider is simply adding new requests within this structures.
diff --git a/docs/content/introduction/goal.tex b/docs/content/introduction/goal.tex
@@ -1,19 +1,19 @@
\section{Goal}
-The goal of this thesis is to design and implement a framework for cashless withdrawals of digital cash in GNU Taler. The implementation of the process which allows withdrawing digital cash in GNU Taler at a terminal of an established payment service provider shows how the framework can be used. The withdrawal process on the side of the provider terminal shall be implemented on the Paydroid platform supplied by the payment provider \textit{Wallee}.
+The objective of this thesis is to develop and implement a framework for the cashless withdrawal of digital cash in GNU Taler. The framework implements the process that digital cash in GNU Taler can be withdrawn at a terminal of an established payment service provider. The withdrawal process on the side of the provider terminal is implemented on the Paydroid platform, which is supplied by the payment provider \textit{Wallee}.
The framework aims to achieve the following key objectives:
\begin{enumerate}
\label{sec-goals-properties}
- \item Finality: Liability for the money is not on the side of the Taler operator
- \item Convenience: The user-experience follows established patterns
- \item Abort: Robust and secure payment flow allowing abort handling without loss of money
+ \item Finality: The operator of the taler 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}
-\subsection{C2EC}
+\subsection{cashless2ecash (C2EC)}
-To achieve these goals a new component named cashless2ecash (C2EC) is implemented as part of the 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.
+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}
diff --git a/docs/content/introduction/introduction.tex b/docs/content/introduction/introduction.tex
@@ -2,28 +2,30 @@
Which payment systems do you use in your daily live and why? Probably one you know it is universally accepted, reliable, secure and the payment goes through more or less instantly.
-An \textbf{easy onboarding} was identified as one of the most important aspects in a report which was commissioned by the ECB (European Central Bank) in march 2022 as result of a focus group concerning the acceptance of a Digital Euro \cite{panetta-speech-march-30} as new payment system. With the possibiliy of an easy onboarding of new users, the universal acceptance can be increased. The universal acceptance was identified as \textit{the} most important property amongst the general public and tech-savvy people in the report \cite{study-new-digital-payment-methods}.
+An \textbf{easy onboarding} was identified as one of the most important aspects in a report which was commissioned by the ECB (European Central Bank) in march 2022 as result of a focus group concerning the acceptance of a Digital Euro \cite{panetta-speech-march-30} as new payment system.
-In a world, where everything is connected and everything is accessible from everywhere (one might think), it is therefore very important to make it as easy as possible to on-board people on a product. This is also the case for GNU Taler. For a wide acceptance of the payment system Taler, it is important that various ways exist to withdraw digital cash in Taler.
+In March 2022, the European Central Bank (ECB) found that an easy onboarding procedure is one of the most important factors influencing the acceptance of the Digital Euro as a new payment system \cite{panetta-speech-march-30}. If the process of onboarding new users is straightforward, this will have a positive effect on the universal acceptance of digital currencies. The ECB asserts that universal acceptance, or the ability to "pay anywhere," is the most significant attribute of an effective digital payment instrument for consumers across the EU, regardless of age \cite{study-new-digital-payment-methods}. Therefore, an easy onboarding procedure is a crucial feature for digital currencies to be adopted by the public.
-This is where this thesis hooks in. Currently it is possible to withdraw digital cash using Taler at a Bank which runs a Taler Exchange and integrates the respective API. At time of this writing only one Bank is in the process of running a Taler Exchange. At the Berner Fachhochschule an Exchange is operated and digital cash can be withdrawn at the secretariat using cash.
+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.
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 withdrawal using a credit card or other means of payment possible, various loose ends must be put together. These loose ends must enable the communication between the Taler ecosystem and payment service providers and their terminals.
+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.
-The a new component C2EC shall help, establishing a trustworthy relationship, which makes it possible for the Exchange to issue digital cash to a customer. Therefore the Exchange is not putting his trust on cash received but rather on the promise of a trusted third party (a terminal provider) to put the received digital cash in a location, controlled by the Exchange eventually (e.g. a bank account owned by the Exchange).
+To address this communication gap, this thesis introduces a new component, called cashless2ecash (C2EC), which establishes a reliable connection between the Taler ecosystem and payment service provider's terminals. The C2EC component enables the Taler Exchange to issue digital cash to a customer. Therefore the Exchange is not putting his trust on cash received but rather on the promise of a a terminal provider to put the received digital cash in a location, controlled by the Exchange eventually (e.g. a bank account owned by the Exchange).
-This enables a broader group of people to leverage Taler for their payments. Which eventually leads to a wider adoption of the payment system Taler.
+Designing the user-experience along established patterns will lead to a better uptake of GNU Taler by enabling money to flow from existing payment systems into GNU Taler's digital cash.
\section{Perspectives}
-During the initial analysis of the task, three areas of work were discovered. One is the Taler Exchange, one the Application for the terminal and the Taler wallet. This led to different views on the system by two different players within it. To allow a more concise view on the system and to support the readers and implementer, two perspectives shall be kept in mind. They have different views on the process but need to interact with each other seamlessly.
+To allow a more concise view on the system and to support the readers and implementer, two perspectives shall be kept in mind. They have different views on the process but need to interact with each other seamlessly.
\subsection{Taler Exchange (C2EC)}
-The perspective of the Taler Exchange includes all processes within C2EC component and the interaction with the terminal application, terminal backend and the wallet of the user. The Taler Exchange wants to allow withdrawal of digital digital cash only to users who pay the equivalent value to the Exchange. The Exchange wants to stay out of any legal implications at all costs.
+The perspective of the Taler Exchange includes all processes within C2EC component and the interaction with the terminal application, terminal backend and the wallet of the user. The Taler Exchange wants to allow withdrawal of digital digital cash only to users who pay the equivalent value to the Exchange. The Exchange wants to stay out of any legal implications at all costs. Fees must be considered, since the withdrawal process is a service which costs the payment service provider money in form of integration and maintenance efforts. To cover its costs, the provider might want to add some fees on the withdrawal.
\subsection{Terminal Application}
The perspective of the terminal application includes all processes within the application which interacts with the user, their wallet and credit card allowing the withdrawal of digital cash. The terminal application wants to conveniently allow the withdrawal of digital cash and charge fees to cover its costs and risks.
-\subsection{Taler wallet}
-The wallet holds the digital cash owned by the customer. The wallet wants to eventually collect the digital cash from the Taler Exchange. The owner of the wallet must present their credit card at a terminal of the payment service provider and pay the Exchange as well accept optional fees of the provider. Fees must be considered, since the withdrawal process is a service which costs the payment service provider money in form of integration and maintenance efforts. To cover its costs, the provider might want to add some fees on the withdrawal.
+\subsection{Taler Wallet}
+The wallet holds the digital cash owned by the customer. The wallet wants to eventually collect the digital cash from the Taler Exchange.
diff --git a/docs/content/results/discussion.tex b/docs/content/results/discussion.tex
@@ -10,7 +10,7 @@ A challenge which was encountered during the implementation of the terminal appl
Towards the end of the implementation it became obvious that a simple authorization was not enough to imitate the real time feeling of the withdrawal. Other requests were necessary to do so. To findout which requests needed to be filed against the Wallee backend some investigation had to be made. The documentation does explain which states exists in Wallee's transaction scheme but does not explain, which operation must be triggered to transition states. This made the investigation somewhat cumbersome. Also the integration of the backend needed more investigation than I thought.
-For the analysis of the security of the system I was happy to find STRIDE which gave me some boundaries and guided me through the process. I found it hard to identify real threats and not loosing time about threats which were out of scope. In the end I think the solution is quite secure in terms of money. Of course you can steal terminals and wreck the nerves of the terminal operators but you won't be able to somehow manipulate the payment process which will allow you to
+For the analysis of the security of the system I was happy to find STRIDE which helped me to identify possible threats. I found it hard to identify real threats and not loosing time about threats which were out of scope. In the end I think the solution is quite secure in terms of money. Of course you can steal terminals and wreck the nerves of the terminal operators but you won't be able to somehow manipulate the payment process which will allow you to steal money or harm the Exchange operator.
\section{Future Work}
diff --git a/docs/project.bib b/docs/project.bib
@@ -308,6 +308,13 @@
howpublished = {\url{https://docs.taler.net/manpages/taler-exchange-wire-gateway-client.1.html}}
}
+@misc{taler-bank-gls,
+ author = {GLS Bank},
+ title = {Taler - die Zukunft des digitalen, sicheren und nachhaltigen Bezahlens},
+ url = {https://www.gls.de/privatkunden/taler},
+ howpublished = {\url{https://www.gls.de/privatkunden/taler}}
+}
+
@misc{postgres-notify,
author = {PostgreSQL},
title = {NOTIFY},
diff --git a/docs/thesis.pdf b/docs/thesis.pdf
Binary files differ.
