commit 19bb7824c5fa6bc73ffe299ede23d22c8cafaac3
parent b173ff6663cc761050a7b34e5dbe05a552c709f8
Author: Joel-Haeberli <haebu@rubigen.ch>
Date: Sat, 25 May 2024 17:02:25 +0200
docs: enhance introduction and architecture
Diffstat:
16 files changed, 94 insertions(+), 187 deletions(-)
diff --git a/docs/content/architecture/c2ec.tex b/docs/content/architecture/c2ec.tex
@@ -1,6 +1,6 @@
\section{C2EC}
-The C2EC (\textbf{c}ashless\textbf{2ec}ash) component is the central coordination component in the cashless withdrawal of digital cash using Taler. It initializes the parameters and mediates between the different stakeholders of a withdrawal, which finally allows the customer to withdraw digital cash from a reserve owned by the \textit{Exchange}. Therefore C2EC provides API which can be integrated and used by the \textit{Terminal}, \textit{Wallet} and the \textit{Exchange}.
+The \textbf{c}ashless\textbf{2ec}ash (C2EC) component is the central coordination component in the cashless withdrawal of digital cash using Taler. It initializes the parameters and mediates between the different stakeholders of a withdrawal, which finally allows the customer to withdraw digital cash from a reserve owned by the \textit{Exchange}. Therefore C2EC provides API which can be integrated and used by the \textit{Terminal}, \textit{Wallet} and the \textit{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}.
@@ -38,79 +38,32 @@ All components involved in the withdrawal process must interact with the C2EC co
\subsubsection{Terminals API}
-That terminal can initiate and serve withdrawals in Taler, the Terminals API \cite{taler-terminal-api} is implemented, which mirrors all actions of a terminal at the C2EC component.
+That terminal can initiate and serve withdrawals in Taler, the Terminals API \cite{taler-terminal-api} is implemented, which mirrors all actions of a terminal at the C2EC component. This covers following endpoints:
-\textbf{Config}
-\begin{itemize}
- \item \textbf{Method:} GET
- \item \textbf{Endpoint:} /config
- \item \textbf{Description:} Return the protocol version and configuration information about the C2EC API.
- \item \textbf{Response:} HTTP status code 200 OK. The exchange responds with a \texttt{TerminalsConfig} object.
- \item \textbf{Consumers:} Terminals who want to use the API and therefore want to load the config of the instance.
-\end{itemize}
-
-\textbf{Withdrawals}
\label{sec-architecture-c2ec-setup-wopid}
-\begin{itemize}
- \item \textbf{Method:} POST
- \item \textbf{Endpoint:} /withdrawals
- \item \textbf{Description:} Register a withdrawal operation at C2EC.
- \item \textbf{Response:} HTTP status code 200 OK. The \textit{WOPID} generated by C2EC. On any other status code, terminate the withdrawal.
- \item \textbf{Consumers:} Terminals who want to initiate a withdrawal operation.
-\end{itemize}
-
-\textbf{Status of the withdrawal operation}
-\begin{itemize}
- \item \textbf{Method:} GET
- \item \textbf{Endpoint:} /withdrawals/\$WOPID
- \item \textbf{Description:} Query information about a withdrawal operation, identified by the \texttt{WOPID}.
- \item \textbf{Response:} HTTP status code 200 OK and body containing a \texttt{BankWithdrawalOperationStatus} object or 404 Not found.
- \item \textbf{Consumers:} The API is used by the \textit{Terminal} and \textit{Taler Wallet} to retrieve information about the current state of the withdrawal operation. The API allows long-polling and can therefore be used by the consumer to be updated if the status of the withdrawal operation changes.
-\end{itemize}
-\textbf{Check transaction}
-\begin{itemize}
- \item \textbf{Method:} POST
- \item \textbf{Endpoint:} /withdrawals/\$WOPID/check
- \item \textbf{Description:} Notifies C2EC about an executed payment for a specific withdrawal.
- \item \textbf{Request:} The request body contains a \texttt{WithdrawalConfirmationRequest} object.
- \item \textbf{Response:} HTTP status code 204 No content, 400 Bad request, 404 Not found, or 500 Internal Server error.
- \item \textbf{Consumers:} The API is used by the \textit{Terminal} to notify the C2EC component that a payment was made and to give the C2EC component information about the payment itself (e.g. the provider specific transaction identifier or optional fees).
-\end{itemize}
+\begin{enumerate}
+ \item Config (/config)
+ \item Withdrawal setup (/withdrawals)
+ \item Status of the withdrawal (/withdrawals/\$WOPID)
+ \item Confirmation Request (/withdrawals/\$WOPID/check)
+ \item Terminal side abort (/withdrawals/\$WOPID/abort)
+\end{enumerate}
\textbf{Fees}
-An important aspect of the withdrawal flow using 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. The provider might decide to delegate those fees to the customer and therefore fees can be sent to the C2EC component through the \textit{check} API specified above. It's also possible that the service of withdrawing cash through a third party is causing costs to the merchant, which it does not want to cover on their own and therefore charge a fee to cover their costs. For example cashback is causing a lot of fees to the merchants supporting it.
+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:
\begin{quote}
- Die Händler zahlen jedoch für den Cashback-Service bereits Gebühren an
+ \textit{de:}Die Händler zahlen jedoch für den Cashback-Service bereits Gebühren an
die Banken. Aktuell sind es laut EHI im Schnitt 0,14 Prozent, insgesamt
waren das 2023 rund 17,2 Millionen Euro. \cite[Crefeld, ZEIT]{zeit-cashback}
\end{quote}
-\textbf{Terminal abortion}
-\begin{itemize}
- \item \textbf{Method:} DELETE
- \item \textbf{Endpoint:} /withdrawals/\$WOPID/abort
- \item \textbf{Description:} Aborts the withdrawal specified by the \texttt{WOPID}.
- \item \textbf{Request:} The request body contains a \texttt{WithdrawalConfirmationRequest} object.
- \item \textbf{Response:} HTTP status code 204 No content, 400 Bad request, 404 Not found, or 500 Internal Server error.
- \item \textbf{Consumers:} The API is used by the \textit{Terminal} to notify the C2EC component that a payment was made and to give the C2EC component information about the payment itself (e.g. the provider specific transaction identifier or optional fees).
-\end{itemize}
-
\subsubsection{Taler Bank Integration API}
Withdrawals by the \textit{Wallet} with a C2EC are based on withdrawal operations which register a reserve public key at the C2EC component. The provider must first create a unique identifier for the withdrawal operation (the \texttt{WOPID}) to interact with the withdrawal operation (as described in \autoref{sec-architecture-c2ec-setup-wopid}) and eventually withdraw digital cash using the \textit{Wallet}. The withdrawal operation API is an implementation of the \textit{Bank Integration API} \cite{taler-bank-integration-api}.
-\textbf{Config}
-\begin{itemize}
- \item \textbf{Method:} GET
- \item \textbf{Endpoint:} /config
- \item \textbf{Description:} Return the protocol version and configuration information about the C2EC API.
- \item \textbf{Response:} HTTP status code 200 OK. The exchange responds with a \texttt{C2ECConfig} object.
- \item \textbf{Consumers:} Wallets who want to use the API and therefore want to load the config of the instance.
-\end{itemize}
-
\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}.
@@ -119,43 +72,6 @@ The wirewatch gateway helps the Exchange communicate with the C2EC component usi
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.
-\textbf{Config}
-\begin{itemize}
- \item \textbf{Method:} GET
- \item \textbf{Endpoint:} /config
- \item \textbf{Description:} Returns a \texttt{WireConfig} object with configuration information about the Wirewatch Gateway API of the C2EC component.
- \item \textbf{Response:} HTTP status code 200 OK and the wirewatch gateway configuration
- \item \textbf{Consumers:} Components who want to use the API and therefore want to load the config of the instance.
-\end{itemize}
-
-\textbf{Transfer}
-\begin{itemize}
- \item \textbf{Method:} POST
- \item \textbf{Endpoint:} /transfer
- \item \textbf{Description:} Allows the \textit{Exchange} to make a transaction. This API is used in case of a refund. The transfer will therefore be pointed towards a provider specific payto-address (\texttt{payto://wallee-transaction} in case of Wallee).
- \item \textbf{Request:} The request contains a \texttt{TransferRequest} object.
- \item \textbf{Response:} HTTP status code 200 OK. The exchange responds with a \texttt{TransferResponse} object.
- \item \textbf{Consumers:} The \textit{Exchange Wirewatch} who wants to transfer money using C2EC.
-\end{itemize}
-
-\textbf{History of incoming transactions}
-\begin{itemize}
- \item \textbf{Method:} GET
- \item \textbf{Endpoint:} /history/incoming
- \item \textbf{Description:} Returns a list of transactions which were recently created in the C2EC component. In case of C2EC, this are withdrawal operations which are confirmed and a reserve can therefore be created by the exchange.
- \item \textbf{Response:} HTTP status code 200 OK. The exchange responds with a \texttt{C2ECConfig} object.
- \item \textbf{Consumers:} The \textit{Exchange Wirewatch} who will create the reserve which then can be withdrawn by the \textit{Taler Wallet}.
-\end{itemize}
-
-\textbf{History of outgoing transactions}
-\begin{itemize}
- \item \textbf{Method:} GET
- \item \textbf{Endpoint:} /history/outgoing
- \item \textbf{Description:} Returns a list of transfers which were executed by the C2EC component.
- \item \textbf{Response:} HTTP status code 200 OK and a list of outgoing transfers.
- \item \textbf{Consumers:} The \textit{Exchange Wirewatch} who will create the reserve which then can be withdrawn by the \textit{Taler Wallet}.
-\end{itemize}
-
\subsection{C2EC Entities}
\label{sec-architecture-entities}
@@ -174,7 +90,7 @@ Entity displayed in \autoref{fig-erd-withdrawal} represents the withdrawal proce
\subsubsection{Relationships}
\label{sec-architecture-entities-relationships}
-The structure of the three entities forms 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.
+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]
\centering
@@ -184,12 +100,12 @@ The structure of the three entities forms a tree which is rooted at the terminal
\end{figure}
\section{Payto wallee-transaction extension}
-RFC 8905 \cite{rfc8905} specifies a URI scheme (complying with RFC 3986 \cite{rfc3986}), which allows to address a creditor with theoretically any protocol that can be used to pay someone (such as IBAN, BIC etc.) in a standardized way. Therefore it introduces a registry which holds the specific official values of the standard. The registry is supervised by the GANA (GNUnet Assigned Numbers Authority) \cite{gnunet-gana}.
+RFC 8905 \cite{rfc8905} specifies a URI scheme (complying with RFC 3986 \cite{rfc3986}), which allows to address a creditor with theoretically any protocol that can be used to pay someone (such as IBAN, BIC etc.) in a standardized way. It introduces a registry which holds the specific official values of the standard. The registry is supervised by the GANA (GNUnet Assigned Numbers Authority) \cite{gnunet-gana}.
-In case a refund becomes necessary, which might occur if a credit card transaction does not succeed, a new \textit{target type} called \textit{wallee-transaction} is registered. It takes a transaction identifier as \textit{target identifier} which identifies the transaction for which a refund process shall be triggered. The idea is that the handler of the payto URI is able to deduct the transaction from the payto-uri and trigger the refund process.
+In case a refund becomes necessary, which might occur if a transaction does not succeed or a reserve is not withdrawn within the specified time, a new \textit{target type} called \textit{wallee-transaction} is registered. It takes a transaction identifier as \textit{target identifier} which identifies the transaction for which a refund process shall be triggered. The idea is that the handler of the payto URI is able to deduct the transaction from the payto-uri and trigger the refund process.
\subsection{Payto refund using Wallee}
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 must therefore 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. They might want to register their own refund payto-uri (if needed) with the GANA and then the refund process can be implemented likewise.
diff --git a/docs/content/architecture/overview.tex b/docs/content/architecture/overview.tex
@@ -7,7 +7,7 @@
\label{fig-logo-components}
\end{figure}
-The component diagram shows the components involved by the withdrawal using the terminal. Besides the credit card 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 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.
\section{Process}
\label{sec-architecture-process}
@@ -19,26 +19,25 @@ The component diagram shows the components involved by the withdrawal using the
\label{fig-diagram-all-components}
\end{figure}
-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 \textit{Exchange}, which shall 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 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.
- \item The Wallet scans the QR code at the Terminal.
- \item The Wallet registers a reserve public key and the \textit{WOPID}.
- \item The Bank-Integration API of C2EC notifies the Terminal, that the parameters were selected.
- \item The POS initiates a payment to the account of the GNU Taler Exchange. For the payment the POS terminal requests a payment card and a PIN for authorizing the payment.
- \item The Terminal triggers the payment at the Wallee Backend.
- \item The Terminal receives the result of the payment.
+ \item 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 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 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 the payment notification to the Bank Integration API of C2EC.
- \item The C2EC component approves the payment by requesting the transaction of the Wallee Backend.
- \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).
- \item Now decoupled from each other the Exchange-Wirewatch asks the Wire Gateway API of C2EC for a list of transactions and the Bank-Integration API sends a \textit{confirmed} or \textit{abort} message to the wallet.
- \item The Wallet asks the Exchange to be notified, when a reserve with the reserve public key becomes available.
- \item The Exchange can send the digital cash back to the Wallet.
+ \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)
\end{enumerate}
\begin{figure}[h]
@@ -48,29 +47,29 @@ The \autoref{fig-diagram-all-components} shows a high level overview of the comp
\label{fig-diagram-all-sequence}
\end{figure}
-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 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 which interact with each other. In this section the highlevel process as showed in \autoref{fig-diagram-all-sequence} is explained.
+The process requires the terminal, the wallet, the C2EC component and the Exchange which interact with each other. In this section the highlevel process as showed in \autoref{fig-diagram-all-sequence} is explained.
-\subsection{The Terminal}
+\subsection{The terminal}
-The Terminal initiates the withdrawal leveraging an application which works as follows:
+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 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 \textit{Exchange}.
+ \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 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 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 Terminal calculates fees and shows summary and the Terms of Service (ToS) of Taler.
+ \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
\end{enumerate}
- \item The user now scans the QR Code using his Wallet.
+ \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 \textit{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 \textit{Wallee Backend}. Possible connectors are Master Card, VISA, TWINT, Maestro, Post Finance, and others \cite{wallee-available-connectors}.
+ \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}.
\begin{enumerate}
\item It presents the result to the user.
\item It tells the C2EC, that the payment was successful.
@@ -79,11 +78,11 @@ The Terminal initiates the withdrawal leveraging an application which works as f
\subsection{The C2EC}
-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.
+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 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.
@@ -94,11 +93,11 @@ The C2EC component manages the withdrawal using a third party provider (e.g. Wal
\subsection{The Wallet}
-The Wallet must attest its presence to the terminal by registering a \textit{WOPID} and belonging reserve public key which will hold the digital cash that can eventually be withdrawn by 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.
\begin{enumerate}
- \item The Wallet scans the QR Code (\textit{WOPID}, Exchange information and amount) on the Terminal
+ \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 and the scanned \textit{WOPID} to the C2EC
- \item The Wallet can withdraw digital cash from the created reserve.
+ \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 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
@@ -35,4 +35,4 @@ The \textit{Transaction Service} is used by C2EC to attest a transaction was suc
The \textit{Refund Service} is used by C2EC in case of a refund. Therefore the C2EC gets notified by the \textit{Exchange} that the transaction shall be refunded. To trigger the refund process at the Wallee backend, the \texttt{POST /api/refund/refund} is used.
\subsubsection{Wallee Transaction State}
-In order to decide if a transaction was successful, the states of a transaction within Wallee must be mapped to the world of Taler. This means that a reserve shall only be created, if the transaction is in a state which allows Taler not having any liabilities regarding the transaction and that Wallee could process the payment successfully. The documentation states that \textit{only} in the transaction state \textit{fulfill}, the delivery of the goods (in case of withdrawal this means, that the reserve can be created) shall be started \cite{wallee-transaction-process}. For the withdrawal this means, that the only interesting state for fulfillment is the \textit{fulfill} state. Every other state means, that the transaction was not successful and the reserve shall not be created.
+To decide if a transaction was successful, the states of a transaction within Wallee must be mapped to the world of Taler. This means that a reserve shall only be created, if the transaction is in a state which allows Taler not having any liabilities regarding the transaction and that Wallee could process the payment successfully. The documentation states that \textit{only} in the transaction state \textit{fulfill}, the delivery of the goods (in case of withdrawal this means, that the reserve can be created) shall be started \cite{wallee-transaction-process}. For the withdrawal this means, that the only interesting state for fulfillment is the \textit{fulfill} state. Every other state means, that the transaction was not successful and the reserve shall not be created.
diff --git a/docs/content/architecture/wallet.tex b/docs/content/architecture/wallet.tex
@@ -1,14 +0,0 @@
-\section{Taler Wallet}
-
-The \textit{Taler Wallet} is responsible to create a reserve key pair which will allow him the withdrawal using the \textit{Exchange} using the reserve public key of the key pair.
-
-The reserve public key is created by the \textit{Taler Wallet} and sent to C2EC to establish the mapping between the \textit{wopid} and the reserve public key. The reserve public key is used to eventually create a reserve at the exchange which contains the digital cash. The \textit{Taler Wallet} can then withdraw the digital cash from this reserve using the withdrawal process of the wallet \cite{wallet-withdrawal}. The process for the case of C2EC is slightly different from the present processes because the requests to the Bank-Integration API contain different properties than the currently supported. This means the \textit{Taler Wallet} must be extended in order to allow the withdrawal using C2EC.
-
-\subsection{Taler Wallet Perspective}
-From the perspective of the Wallet, the system looks as follows:
-
-\begin{itemize}
- \item Uses the QR Code displayed on the \textit{Wallee Terminal} to identify nonce and read exchange information.
- \item Uses the Bank-Integration API of \textit{C2EC} to register the reserve public key and retrieve information about the confirmation of the withdrawal.
- \item Uses the \textit{Exchange} to withdraw the digital cash.
-\end{itemize}
-\ No newline at end of file
diff --git a/docs/content/implementation/b-terminal.tex b/docs/content/implementation/b-terminal.tex
@@ -75,22 +75,24 @@ When the transaction was processed successfully, the summary of the transaction
\label{fig-terminal-screen-authorized}
\end{figure}
-\subsection{Abortion Handling}
+\subsection{Abort Handling}
-During the flow various steps can fail or lead to the abortion of the withdrawal. Therefore these edge cases must be considered and handled the right way. Generally we can split the abortion handling on the terminal side into two different phases. The implementation of the Wallee POS Terminal therefore follows a strict \textit{abort on failure} strategy. This means that if anything goes wrong the withdrawal is aborted and must be started again. Generally the abortion handling strategy is to abort the withdrawal when in doubt and values security (of the money) over user-experience.
+During the flow various steps can fail or lead to the abort of the withdrawal. These edge cases must be considered and handled the right way. Generally we can split the abort handling on the terminal side into two different phases. The implementation of the Wallee POS Terminal follows a strict \textit{abort on failure} strategy. This means that if anything goes wrong the withdrawal is aborted and must be started again. Generally the abort handling strategy is to abort the withdrawal when in doubt and values security (of the money) over user-experience. The idea behind this strategy is, that even when a nice user-experience is implemented, nobody will use the technology if security of the money cannot be guaranteed
-\subsubsection{Abortion before authorization}
+\subsubsection{Abort before authorization}
-The first phase are abortions \textit{before} the payment is authorized. In this case the withdrawal operation can be aborted using the \textit{abort} operation described in \autoref{sec-implementation-terminal-api}. Every problem which cannot be recovered or not further processed must therefore lead to the abortion of the withdrawal.
+The first phase are abortions \textit{before} the payment is authorized. In this case the withdrawal operation can be aborted using the \textit{abort} operation described in \autoref{sec-implementation-terminal-api}. Every problem which cannot be recovered or not further processed must lead to the abort of the withdrawal.
-\subsubsection{Abortion after authorization}
+\subsubsection{Abort after authorization}
When the transaction was authorized, the process is a little bit more complex. The customer has two possibilities. The first one is automatically covered with the given implementation, while the second is not guaranteed and needs manual interaction of the customer with the Taler Exchange operator.
\textbf{Wait for automatic refund due to closing of the reserve}
-The Taler Exchange configures a duration for which a reserve is kept open (and therefore can be withdrawn). When the configured duration exceeds the reserve is closed autmatically and the money transferred back to the customer. In the case of Wallee payments, this is realized through a refund request at the provider backend upon receiving a transfer request at the wire-gateway API \autoref{sec-implementation-wire-gateway-api} of the C2EC component.
+The Taler Exchange configures a duration for which a reserve is kept open (and can be withdrawn). When the configured duration exceeds the reserve is closed autmatically and the money transferred back to the customer. In the case of Wallee payments, this is realized through a refund request at the provider backend upon receiving a transfer request at the wire-gateway API \autoref{sec-implementation-wire-gateway-api} of the C2EC component.
\textbf{Manual request to refund money}
Depending on the operator of the Taler Exchange it might be possible to somehow manually trigger a refund and get back the money spent for the withdrawal.
+% TODO new section for Authorize -> Complete -> Execute Final Balance flow
+
\newpage
\ No newline at end of file
diff --git a/docs/content/introduction/goal.tex b/docs/content/introduction/goal.tex
@@ -1,10 +1,19 @@
\section{Goal}
-The goal of this thesis is to propose a framework for cashless withdrawals and implement the process which allows withdrawing Taler using a credit card at a terminal of the terminal provider \textit{Wallee}.
+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 framework aims to achieve the following key objectives:
+
+\begin{enumerate}
+ \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
+\end{enumerate}
\subsection{C2EC}
-Therefore a new component, named C2EC, will be implemented as part of the Taler Exchange. C2EC will mediate between the Taler Exchange and the terminal provider. This includes checking that the transaction of the debitor reaches the account of the Exchange and therefore the digital currency can be withdrawn by the user, using its Wallet.
+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.
+
+\subsection{Paydroid POS Terminal}
-\subsection{Wallee POS Terminal}
-The Wallee payment terminal, also called Point of Sales (POS) terminal, interfaces with payment cards (Credit Cards, Debit Cards) to make electronic fund transfers, i.e. a fund transfer to a given GNU Taler Exchange. For our purpose, we will 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, 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.
diff --git a/docs/content/introduction/introduction.tex b/docs/content/introduction/introduction.tex
@@ -2,28 +2,28 @@
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.
-The \textbf{universal acceptance} was identified as one of the most important aspects in a report which was published on behalf of 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. The universal acceptance was even 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. 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}.
-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 Taler. For a wide acceptance of the payment system Taler, it is important that various ways exist to withdraw digital cash in Taler.
+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.
-This is where this thesis hooks in. Currenlty it is possible to withdraw digital cash using Taler at a Bank which runs a \textit{Taler Exchange} and integrates the respective API. At time of this writing only one Bank is in the process of running a \textit{Taler Exchange}. At the Berner Fachhochschule an \textit{Exchange} is operated and digital cash can be withdrawn at the secretariat using cash.
+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.
-To make the access to digital cash using Taler easier and allow faster spreading 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 the society.
-To make the withdrawals using a credit card possible, various loose ends must be put together within the Taler ecosystem and the terminal provider.
+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.
-Therefore a new component C2EC shall help, establishing a trustworthy relationship, which makes it possible for the \textit{Exchange} to issue digital cash to a customer. Therefore the \textit{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 \textit{Exchange} eventually (e.g. a bank account owned by the \textit{Exchange}).
+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).
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.
\section{Perspectives}
-During the initial analysis of the task, three areas of work were discovered. One is the \textit{Taler Exchange}, one the Application for the terminal and the (Taler) \textit{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.
+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.
\subsection{Taler Exchange (C2EC)}
-The perspective of the \textit{Taler Exchange} includes all processes within C2EC component and the interaction with the terminal application, terminal backend and the wallet of the user. The \textit{Taler Exchange} wants to allow withdrawal of digital digital cash only to users who pay the equivalent value to the \textit{Exchange}. The \textit{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.
\subsection{Terminal Application}
-The perspective of the terminal application includes all processes within the application which interacts with the user, their \textit{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.
+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 \textit{Wallet} holds the digital cash owned by the customer. The \textit{Wallet} wants to eventually gather the digital cash from the \textit{Taler Exchange}. The owner of the \textit{Wallet} must therefore present their credit card at a \textit{Terminal} of the terminal provider and pay the \textit{Exchange} as well accept the fees of the provider.
+\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.
diff --git a/docs/pictures/diagrams/c2ec.png b/docs/pictures/diagrams/c2ec.png
Binary files differ.
diff --git a/docs/pictures/diagrams/system_overview.png b/docs/pictures/diagrams/system_overview.png
Binary files differ.
diff --git a/docs/thesis.pdf b/docs/thesis.pdf
Binary files differ.
diff --git a/docs/thesis.tex b/docs/thesis.tex
@@ -196,7 +196,6 @@
\chapter{Architecture}
\label{sec-architecture}
\input{content/architecture/c2ec}
-\input{content/architecture/wallet}
\input{content/architecture/wallee}
\chapter{Implementation}
diff --git a/poster/cashless2ecash_poster.pdf b/poster/cashless2ecash_poster.pdf
Binary files differ.
diff --git a/poster/cashless2ecash_poster.tex b/poster/cashless2ecash_poster.tex
@@ -25,7 +25,6 @@
columns=5,
rows=8,
spacing=1cm,
- %showframe, %Gitter einblenden. Für Platzierung häufig hilfreich
}]
\begin{posterboxenv}[title=Motivation]{name=intro,column=1,row=1,span=3,rowspan=2}
@@ -140,7 +139,7 @@
\end{posterboxenv}
-\space
+ \space
\begin{posterboxenv}[title=C2EC is extensible]{name=Integrate your platform, column=1,row=8,span=5,rowspan=1}
diff --git a/simulation/c2ec-simulation b/simulation/c2ec-simulation
Binary files differ.
diff --git a/specs/c2ec.plantuml b/specs/c2ec.plantuml
@@ -13,32 +13,30 @@ User -> TerminalOwner: "Hi, I want to withdraw 20 CHF using Taler with my Credit
TerminalOwner -> Terminal: start Taler Withdrawal Application and enters amount
Terminal -> Terminal: Generate WOPID
Terminal -> C2EC: (0) Setup Withdrawal
-Terminal -> C2EC: (1) Start long polling (WOPID)
+Terminal -> C2EC: Start long polling (WOPID)
activate C2EC
Terminal -> Terminal: Create QR code (WOPID, Exchange, Amount)
-Terminal -> Wallet: (2) Scan QR code
+Terminal -> Wallet: (1) Scan QR code
activate Wallet
Wallet -> Wallet: If ToS for Exchange not yet accepted, do here.
Wallet -> Wallet: Create Reserve Key-Pair
-Wallet -> C2EC: (3) Register reserve public key
+Wallet -> C2EC: (2) Register reserve public key
C2EC -> C2EC: Link WOPID to reserve public key
-C2EC --> Terminal: (4) End long polling (selected)
+C2EC --> Terminal: (3) End long polling (selected)
deactivate C2EC
-Terminal -> Terminal: Show summary with Fees (if any)
-User -> Terminal: (5) Approve and authorize transaction
-Terminal -> TerminalBackend: (6) Execute transaction
-TerminalBackend --> Terminal: (7) transaction response (success/failure)
+Terminal -> Terminal: Show summary with Fees (optional)
+User -> Terminal: (4) Approve and authorize transaction
+Terminal -> TerminalBackend: (5) Execute transaction
+TerminalBackend --> Terminal: (6) transaction response (success/failure)
+Terminal -> C2EC: (7) Send Confirmation Request (SUCCESS)
+C2EC -> TerminalBackend: (8) Verify transaction
alt transaction successful
- Terminal -> C2EC: (8) Send Confirmation Request (SUCCESS)
- C2EC -> TerminalBackend: (9) Verify transaction
- C2EC -> C2EC: (10) confirm or abort withdrawal
- Exchange -> C2EC: (11) get transaction history
+ C2EC -> C2EC: (9a) confirm withdrawal
+ Exchange -> C2EC: (10) get transaction history
Exchange -> Exchange: Create Reserve with amount and reserve public key.
- Wallet -> Exchange: (12) Await creation of the reserve
- Wallet -> Exchange: (13) Withdraw digital cash
+ Wallet -> Exchange: (11) Withdraw digital cash when reserve is ready
deactivate Wallet
else transaction not successful
- Terminal -> C2EC: (8) Send Confirmation Request (UNSUCESSFUL)
- C2EC -> C2EC: Transition withdrawal to abort state.
+ C2EC -> C2EC: (9b) abort withdrawal
end
@enduml
diff --git a/specs/system_overview.odg b/specs/system_overview.odg
Binary files differ.
