commit aba5647568909105f67eea5a71bf5e06c4734ce9
parent 0cc1b6d6db6c329cfc1357cbc892006e8fd684d1
Author: Joel-Haeberli <haebu@rubigen.ch>
Date: Tue, 11 Jun 2024 10:25:38 +0200
final
Diffstat:
11 files changed, 30 insertions(+), 34 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 payment system 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 C2EC, implementing the new Terminals API. 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 payment system 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 by implementing the new Terminals API in 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/wallee.tex b/docs/content/architecture/wallee.tex
@@ -1,5 +1,5 @@
\section{Wallee}
-Wallee offers level 1 PCI-DSS \cite{pci-dss} compliant payment processes to its customers \cite{wallee-pcidss-compliance} and allows an easy integration of its process into various kinds of merchant systems (e.g. websites, terminals, etc).
+Wallee offers level 1 PCI-DSS \cite{pci-dss} compliant payment processes to its customers \cite{wallee-pcidss-compliance} and allows a simple integration of its process into various kinds of merchant systems (e.g. websites, terminals, etc).
\subsection{Wallee Perspective}
From the perspective of Wallee, the system looks as follows:
@@ -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. 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.
+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 a simple 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/implementation/a-c2ec.tex b/docs/content/implementation/a-c2ec.tex
@@ -1,13 +1,13 @@
\section{C2EC}
-This section treats the implementation of the C2EC component. C2EC is the core of the withdrawal using a third party. Besides different API for different client types such as the Terminal, Wallet or the Exchange, it must also deal with background tasks as described in \autoref{sec-implementation-processes}. The component also implements a framework to extend the application to accept withdrawals through other providers than Wallee. In \autoref{sec-implementation-providers} the requirements for the integration of other providers is explained and shown at the example of Wallee.
+This section treats the implementation of the C2EC component. C2EC is the core of the withdrawal using a third party. Besides different API for different client types such as the terminal, wallet or the Exchange, it must also deal with background tasks as described in \autoref{sec-implementation-processes}. The component also implements a framework to extend the application to accept withdrawals through other providers than Wallee. In \autoref{sec-implementation-providers} the requirements for the integration of other providers is explained and shown at the example of Wallee.
\subsection{Endpoints}
\label{sec-implementation-endpoints}
-The diagram in \autoref{fig-diagram-c2ec-apis-sequence} shows the perspective of the C2EC component in the withdrawal flow. The numbers in brackets represent can be mapped to the diagram in \autoref{fig-diagram-all-sequence} of the process description in the architecture chapter at \autoref{sec-architecture-process}. The requests represented in \autoref{fig-diagram-c2ec-apis-sequence} only show the requests of the succesful path. In case of an error in the process, various other endpoints are implemented as described per client type in \autoref{sec-implementation-endpoints}
+The diagram in \autoref{fig-diagram-c2ec-apis-sequence} shows the perspective of the C2EC component in the withdrawal flow. The numbers in brackets represent the numbers of the diagram in \autoref{fig-diagram-all-sequence} depicting the process in the architecture chapter at \autoref{sec-architecture-process}. The requests represented in \autoref{fig-diagram-c2ec-apis-sequence} only show the requests of the succesful path. In case of an error in the process, abort endpoints are implemented as described per client type.
-The implementation of the terminals API can be found in \autoref{sec-implementation-terminal-api}, the bank integration API is documented in \autoref{sec-implementation-bank-integration-api} and the wire gateway API implementation is documented in \autoref{sec-implementation-wire-gateway-api}
+The implementation of the terminals API can be found in \autoref{sec-implementation-terminal-api}, the bank integration API is documented in \autoref{sec-implementation-bank-integration-api} and the wire gateway API implementation is documented in \autoref{sec-implementation-wire-gateway-api}.
\newpage
\KOMAoptions{paper=landscape,pagesize}
@@ -29,50 +29,50 @@ The implementation of the terminals API can be found in \autoref{sec-implementat
\subsubsection{Decoupling Withdrawal Steps}
-The concept of publishers and subscribers is used in the implementation. It allows decoupling different steps of the process and allows different steps to be handled and executed in their own processes. Publishers can also be called notifiers or similar, while the subscriber can also be called listener. Subscriptions are also implemented using long-polling. Long-polling imitates subscribers by rescheduling a request after some time and keeping the connection open until the specified amount of time exceeds and the requested component responds.
+The concept of publishers and subscribers is used in the implementation. It allows decoupling different steps of the process and allows different steps to be handled and executed in their own processes. Subscriptions are implemented using long-polling and listeners for Postgres notifications. Long-polling imitates subscribers by rescheduling a request after some time and keeping the connection open until the specified timespan exceeds and the requested component answers the request.
The communication of publishers and subscribers happens through channels or long-polling. A publisher will publish to a certain channel when a defined state is reached. The subscriber who listens to this channel will capture the message sent through the channel by the publisher and start processing it.
-To decouple different steps in the withdrawal process an event based architecture is implemented. This means that every action leading to a state transition of the withdrawal triggers an event. The trigger can be a real event trigger like a database trigger or a retry mechanism which periodically checks for state updates. The applications processes are listening to those events. Consuming clients such as the wallet or the terminal can wait to be notified by the API. The notification is achieved by registering the respective events via a long polling request. The long-polling request will then wait until the backend is ready to send the response. If the long-poll time exceeds and the result the consumer is looking for is not available, it must reschedule a long-poll request.
+Every action leading to a state transition of the withdrawal triggers an event. The trigger can be a real event trigger like a database trigger or a retry mechanism which periodically checks for state updates. The applications processes are listening to those events. Consuming clients such as the wallet or the terminal can wait to be notified by the API. The notification is achieved by registering the respective events via a long polling request. The long-polling request will then wait until the backend is ready to send the response. If the long-poll time exceeds and the result the consumer is looking for is not available, it must reschedule a long-poll request.
-Following a short list of events and from whom they are triggered and who listens to them:
+Following a short list of state transitions and from whom they are triggered and who awaits them:
\begin{itemize}
\item From pending to selected
\begin{itemize}
\item Description: Registration of the withdrawal operation parameters.
- \item Registered by: Wallet
- \item Listened by: Terminal
+ \item Triggered by: Wallet
+ \item Awaited by: Terminal
\end{itemize}
\item From selected to confirming
\begin{itemize}
\item Description: Payment confirmation request sent to the Terminals API of C2EC.
- \item Registered by: Terminal
- \item Listened by: Confirmation process
+ \item Triggered by: Terminal
+ \item Awaited by: Confirmation process
\end{itemize}
\item From selected to confirmed
\begin{itemize}
\item Description: Payment confirmation success will send a withdrawal operation status update event.
- \item Registered by: Confirmation process
- \item Listened by: Consumer wallets (via Bank-Integration-API)
+ \item Triggered by: Confirmation process
+ \item Awaited by: Consumer wallets (via Bank-Integration-API)
\end{itemize}
\item From selected to aborted
\begin{itemize}
\item Description: Payment confirmation failure will trigger a retry event.
- \item Registered by: Confirmation process
- \item Listened by: Retry process
+ \item Triggered by: Confirmation process
+ \item Awaited by: Retry process
\end{itemize}
- \item Refund
+ \item Refunds as transfer requests
\begin{itemize}
\item Description: Transfers which represent refunds in C2EC.
- \item Registered by: Exchange (through the Wire Gateway API)
- \item Listened by: Transfer process
+ \item Triggered by: Exchange (using the Wire Gateway API of C2EC)
+ \item Awaited by: Transfer process
\end{itemize}
\end{itemize}
\subsection{Abort Handling}
-A withdrawal might be aborted through the terminal or the wallet. These cases are implemented through the respective \textit{abort} endpoint in the bank-integration API \autoref{sec-implementation-bank-integration-api-abort} and terminals API \autoref{sec-implementation-terminal-api-abort}. If in doubt whether to abort the withdrawal or not, it should be aborted. In case of abortion and failure cases, the security of the money is weighted higher than the user-experience. If the user must restart the withdrawal in case of a failure in the process, it is less severe than opening possible security holes by somehow processing the withdrawal anyway. On the other hand the system must be as stable as possible to make this error cases very rare. If they occur too often, the customer might not use the technology and therefore would make it worthless.
+A withdrawal might be aborted through the terminal or the wallet. These cases are implemented through the respective \textit{abort} endpoint in the bank-integration API \autoref{sec-implementation-bank-integration-api-abort} and terminals API \autoref{sec-implementation-terminal-api-abort}. If in doubt whether to abort the withdrawal or not, it should be aborted. In case of abortion and failure cases, the security of the money is weighted higher than the user-experience. If the user must restart the withdrawal in case of a failure in the process, it is less severe than opening possible security holes by somehow processing the withdrawal anyway. On the other hand the system must be as stable as possible to make these error cases very rare. If they occur too often, the customer might not use the technology and therefore would make it worthless.
The withdrawal can only be aborted, when it is not yet confirmed by the confirmation process (described in \autoref{sec-implementation-processes-confirmation}). When the customer wants his money back they can wait for the reserve to be closed by the Exchange or get in touch with the operator who might trigger a manual refund. The manual refund will revert the payment and give the money back to the customer.
diff --git a/docs/content/implementation/a-fees.tex b/docs/content/implementation/a-fees.tex
@@ -1,7 +1,7 @@
\subsection{Fees}
\label{sec-implementation-fees}
-During the implementation it became obvious that there are several possible fee models, when thinking about the general case. Think of buying a bar of chocolate. From the perspective of getting what you want, you don't care if you pay 10 CHF or 10.10 CHF because in the end you get what you want - a bar of chocolate. Using a payment service provider to withdraw money, is special because if you want to withdraw 10 CHF then you want 10 CHF in your wallet and not 10 CHF minus the fees. When withdrawing money using the credit card you want the amount in your wallet you are asking for - not less. The fees must be transparently communicated to the customer, that they understand why the authorized amount will be higher than the amount they are asking to withdraw. The fees must be calculated in advance whenever possible. This leads to different models to add up fees. These four models were discovered:
+During the implementation it appeared that there are several possible fee models, when thinking about the general case. Think of buying a bar of chocolate. From the perspective of getting what you want, you don't care if you pay 10 CHF or 10.10 CHF because in the end you get what you want - a bar of chocolate. Using a payment service provider to withdraw money, is special because if you want to withdraw 10 CHF then you want 10 CHF in your wallet and not 10 CHF minus the fees. When withdrawing money using the credit card you want the amount in your wallet you are asking for - not less. The fees must be transparently communicated to the customer, that they understand why the authorized amount will be higher than the amount they are asking to withdraw. The fees must be calculated in advance whenever possible. This leads to different models to add up fees. These four models were discovered:
\subsubsection{Model 1 - Exchange Operator Fees}
diff --git a/docs/content/implementation/a-processes.tex b/docs/content/implementation/a-processes.tex
@@ -6,7 +6,7 @@ This section describes the different processes running in the background transit
\subsubsection{Confirmation}
\label{sec-implementation-processes-confirmation}
-The confirmation of a transaction is crucial, since this is the action which allows the exchange to create a reserve and can proof to the provider and customer, that the transaction was successful and therefore can put the liability for the money on the provider. The confirmation process is implemented using a provider client interface and a provider transaction interface. This allows the process to be the same for each individual provider and new providers can be added easily by providing a specific implementation of the interfaces.
+The confirmation of a transaction is crucial, since this is the action which allows the exchange to create a reserve and can proof to the provider and customer, that the transaction was successful and therefore can put the liability for the money on the provider. The confirmation process is implemented using a provider client interface and a provider transaction interface. This allows the process to be the same for each individual provider and new providers can be added by providing a specific implementation of the interfaces.
\subsubsection{Confirmation Retrier}
diff --git a/docs/content/implementation/a-terminal-api.tex b/docs/content/implementation/a-terminal-api.tex
@@ -12,7 +12,7 @@ The C2EC Terminals API implements following endpoints:
\item GET /withdrawals/[WOPID]/check
\end{itemize}
-The C2EC component does not implement the \texttt{/quotas/*} endpoints, since those are not relevant for the withdrawal using a payment terminal. Quotas are possibly checked by the payment service provider.
+The C2EC component does not implement the \texttt{/quotas/*} endpoints, since those are not relevant for the withdrawal using a payment terminal. Quotas are checked by the payment service provider authorizing the payment.
\textbf{Configuration (/config)}
diff --git a/docs/content/implementation/b-terminal.tex b/docs/content/implementation/b-terminal.tex
@@ -3,11 +3,11 @@
\subsection{Withdrawal Flow}
\label{sec-wallee-withdrawal-flow}
-The process (\autoref{fig-diagram-terminal-flow}) starts by first selecting the exchange and loading the configuration of the respective terminals-api. When this is successful, we will switch to the amount screen. Otherwise the withdrawal will be terminated.
+The process (\autoref{fig-diagram-terminal-flow}) starts by first selecting the Exchange and loading the configuration from the Terminals-API. When this is successful the terminal app will navigate to the amount screen. Otherwise the withdrawal is terminated.
On the amount screen the terminal operator enters the amount to withdraw and clicks on the "withdraw" button. If the operator clicks on the abort button, the withdrawal is terminated. When the user clicks the "withdraw" button, the terminal sets up the withdrawal at the exchanges terminals api and retrieves the wopid. When this step is unsuccessful, the withdrawal operation is aborted and terminated. Otherwise the terminal navigates to the register parameters screen.
-In the register parameters screen, a QR code is displayed, which must be scanned by the withdrawer using their wallet app. When the user scanned the QR Code and the terminal gets the withdrawal operation in state 'selected' from C2EC, the wallet has successfully registered its withdrawal parameters. In this case the terminal application changes to the authorization screen in which the withdrawing person must authorize the transaction using their credit card (or another supported payment mean). In any other case, the withdrawal operation is aborted and terminated. When the terminals backend sends the response of the authorization to the terminal, it sends the Terminals API of C2EC the confirmation request. This will start the confirmation process of the withdrawal immediately. If the confirmation request is successful, the terminal shows a summary of the transaction.
+In the register parameters screen, a QR code is displayed, which must be scanned by the withdrawer using their wallet app. When the user scanned the QR Code and the terminal gets the withdrawal operation in state 'selected' from C2EC, the wallet has successfully registered its withdrawal parameters. In this case the terminal application changes to the authorization screen in which the withdrawing person must authorize the transaction using their credit card (or another supported payment mean). In any other case, the withdrawal operation is aborted and terminated. When the terminals backend sends the response of the authorization to the terminal, it sends the Terminals API of C2EC the confirmation request. This will start the confirmation process of the withdrawal immediately. If the confirmation request is successful, the terminal shows a summary of the transaction. Otherwise it shows that the transaction was not succesful and the withdrawal is aborted.
\newpage
\KOMAoptions{paper=landscape,pagesize}
diff --git a/docs/content/implementation/c-database.tex b/docs/content/implementation/c-database.tex
@@ -3,10 +3,6 @@
The Database is implemented using Postgresql. This database is also used by other Taler components and therefore is a good fit.
-Besides the standard SQL features to insert, update and select data, Postgres also comes with handy features like LISTEN and NOTIFY.
-
-This allows the implementation of neat pub/sub models allowing better performance, separation of concerns and loose coupling.
-
\subsection{Schema}
For the C2EC component the schema c2ec is created. It holds tables to store the entities described in \autoref{sec-architecture-entities}. Additionally it contains the table for transfers which is used to capture refunds requested by the \textit{Exchange}.
diff --git a/docs/content/implementation/concepts.tex b/docs/content/implementation/concepts.tex
@@ -1 +1 @@
-The implementation is documented per component (C2EC, Terminal, Database). This means that each feature is documented from the perspective of the respective component in another section. Remarkable interactions with other components are linked with and shall support the reader to jump between the different components explanations interacting with each other. The reader is therefore advised to read the document on a digital device for easier reading. Also diagrams might be hard to see when reading the documentation from a hard copy.
-\ No newline at end of file
+The implementation is documented per component (C2EC, terminal, database). This means that each feature is documented from the perspective of the respective component in another section.
+\ No newline at end of file
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
Fees are a central aspect of the process and decide wether the implementation can be used or not. The different fee models of \autoref{sec-implementation-fees} describe how fees can add up during a withdrawal. The current implementation does not cover all fee models, because fee models two to four also depend on the payment system provider used for a specific withdrawal. The checks that C2EC can make to secure its own fees are implemented. Fee model one seems to be the most secure and easy to implement fee model. It can be covered by the core implementation of C2EC and does not rely on the payment system provider specific implementation. Using other fee models requires great care during the integration and adds complexity. For the thesis, model one was implemented because Wallee uses this model. These models also resolve the discussion of the midterm meeting with Dr. Alain Hiltgen.
-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 assumed. This also led to the
+Towards the end of the implementation it became obvious that a simple authorization of the payment 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 assumed. This also led to the
The new cashless approach to withdraw digital cash makes a faster uptake of GNU Taler possible. Potential customers will only need a supported payment mean to withdraw digital cash. They can now use C2EC and the terminal app for Wallee to withdraw digital cash using GNU Taler.
diff --git a/docs/thesis.pdf b/docs/thesis.pdf
Binary files differ.
