1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
\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 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-wirewatch-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 \cite{taler-c2ec-spec}
\subsection{C2EC Perspective}
From the perspective of C2EC, the system looks as follows:
\begin{itemize}
\item Is requested by the \textit{Taler Wallet} to register a new \textit{wopid} to reserve public key mapping.
\item Is notified by the \textit{Wallee Terminal} about a payment.
\item Attests a payment by requesting the payment proof at the \textit{Wallee Backend}
\item Supplies the Taler Wire Gateway API that the respective \textit{Exchange} can retrieve new transactions and create reserves which are then created and can be withdrawn by the \textit{Taler Wallet}.
\end{itemize}
\subsection{Withdrawal-Operation state transitions}
Basically C2EC mediates between the stakeholders of a withdrawal in order to maintain the correct state of the withdrawal. Therefore 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 attestation 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 \textit{Exchange} will create a reserve and allow the withdrawal. If the attestation fails, thus the provider could not process the transaction successfully, the failure case \textit{aborted}, is reached as final state.
\begin{figure}[h]
\centering
\includegraphics[width=0.7\textwidth]{pictures/diagrams/withdrawal-op-state-transition.png}
\caption{Withdrawal Operation state transition diagram}
\label{fig-withdrawal-operation-state-transition-diagram}
\end{figure}
\subsection{Authentication}
Terminals and the Exchange which authenticate against the C2EC API must provide their respective access token. Therefore, they provide a \texttt{Authorization: Bearer \$ACCESS\_TOKEN} header, where \texttt{\$ACCESS\_TOKEN} is a secret authentication token configured by the exchange and must begin with the prefix specified in RFC 8959 \cite{rfc8959}: \textit{secret-token}.
\subsection{The C2EC RESTful API}
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 data to C2EC.
\subsubsection{Taler Bank Integration API}
Withdrawals with a C2EC are based on withdrawal operations which register a withdrawal identifier (nonce) 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 and eventually withdraw using the wallet. The withdrawal operation API is an implementation of the \textit{Bank Integration API} \cite{taler-bank-integration-api}.
\textbf{GET - 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:} Components who want to use the API and therefore want to load the config of the instance.
\end{itemize}
\textbf{POST - withdrawal-operation}
This API is not specified within the standard Bank Integration API and therefore an extension to the official specification. The Wallet must implement the initialization through this flow.
\begin{itemize}
\item \textbf{Method:} POST
\item \textbf{Endpoint:} /withdrawal-operation
\item \textbf{Description:} Initiate the withdrawal operation, identified by the \texttt{WOPID}.
\item \textbf{Request:} The request body contains a \texttt{C2ECWithdrawRegistration} object.
\item \textbf{Response:} The response is HTTP status code 204 No Content on success and a 400 or 500 status code on failure (with respective \texttt{ErrorDetail})
\item \textbf{Consumers:} The \textit{Taler Wallet} registers and initializes the withdrawal operation through this API.
\end{itemize}
\textbf{GET - withdrawal-operation by wopid}
\begin{itemize}
\item \textbf{Method:} GET
\item \textbf{Endpoint:} /withdrawal-operation/\$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{C2ECWithdrawalStatus} 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{POST - withdrawal-operation by wopid}
\begin{itemize}
\item \textbf{Method:} POST
\item \textbf{Endpoint:} /withdrawal-operation/\$WOPID
\item \textbf{Description:} Notifies C2EC about an executed payment for a specific withdrawal.
\item \textbf{Request:} The request body contains a \texttt{C2ECPaymentNotification} 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).
\end{itemize}
\subsection{Taler Wirewatch Gateway API}
The Taler Wirewatch Gateway \cite{taler-wirewatch-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-wirewatch-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.
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{GET - 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. The exchange responds with a \texttt{C2ECConfig} object.
\item \textbf{Consumers:} Components who want to use the API and therefore want to load the config of the instance.
\end{itemize}
\textbf{POST - transfer}
\begin{itemize}
\item \textbf{Method:} GET
\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 pointed towards a \texttt{payto://wallee-transaction} address.
\item \textbf{Request:} The request contains a \texttt{TransferRequest} object.
\item \textbf{Response:} HTTP status code 200 OK. The exchange responds with a \texttt{C2ECConfig} object.
\item \textbf{Consumers:} The \textit{Exchange} who wants to transfer digital cash to a account which can be handled by the C2EC component.
\end{itemize}
\textbf{GET - 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} who will create the reserve which then can be withdrawn by the \textit{Taler Wallet}.
\end{itemize}
\subsection{The C2EC database}
The database 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 of terminals allowing withdrawals owned by terminal providers like \textit{Wallee}.
\subsubsection{Terminal Provider}
Table 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 attestation flow of \textit{Wallee} once the payment notification for the withdrawal reaches C2EC.
\begin{figure}[h]
\centering
\includegraphics[width=0.7\textwidth]{pictures/database/table_terminal_provider.png}
\caption{Terminal Provider Table}
\label{fig-erd-terminal-provider}
\end{figure}
\subsubsection{Terminal}
Table in \autoref{fig-erd-terminal} contains information about terminals of providers. This includes the provider they belong to and an authentication token, which is generated by the Exchange and allows authenticating the terminal. A terminal belongs to one terminal provider.
\begin{figure}[h]
\centering
\includegraphics[width=0.7\textwidth]{pictures/database/table_terminal.png}
\caption{Terminal Table}
\label{fig-erd-terminal}
\end{figure}
\subsubsection{Withdrawal}
Table in \autoref{fig-erd-withdrawal} represents the withdrawal processes initiated by terminals. This table therefore 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.
\begin{figure}[h]
\centering
\includegraphics[width=0.7\textwidth]{pictures/database/table_withdrawal.png}
\caption{Withdrawal Table}
\label{fig-erd-withdrawal}
\end{figure}
\subsubsection{Relationships}
The structure of the three tables 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.
\begin{figure}[h]
\centering
\includegraphics[width=0.7\textwidth]{pictures/database/relationships.png}
\caption{Relationships of the entities.}
\label{fig-erd-relationships}
\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}.
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.
\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, and the payto-uri retrieved as debit account by the wirewatch 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 with the GANA and then the refund process can be implemented likewise.
|
