a-c2ec.tex (6508B)
1 \section{C2EC} 2 3 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. 4 5 \subsection{Endpoints} 6 \label{sec-implementation-endpoints} 7 8 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. 9 10 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}. 11 12 \newpage 13 \KOMAoptions{paper=landscape,pagesize} 14 \recalctypearea 15 \thispagestyle{empty} 16 \newgeometry{left=4cm, right=4cm, top=3cm, bottom=0cm} 17 18 \begin{figure}[H] 19 \centering 20 \includegraphics[width=1.7\textwidth]{pictures/diagrams/c2ec_apis.png} 21 \caption{C2EC and its interactions with various components} 22 \label{fig-diagram-c2ec-apis-sequence} 23 \end{figure} 24 25 \restoregeometry 26 \newpage 27 \KOMAoptions{paper=portrait,pagesize} 28 \recalctypearea 29 30 \subsubsection{Decoupling Withdrawal Steps} 31 32 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. 33 34 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. 35 36 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. 37 38 Following a short list of state transitions and from whom they are triggered and who awaits them: 39 40 \begin{itemize} 41 \item From pending to selected 42 \begin{itemize} 43 \item Description: Registration of the withdrawal operation parameters. 44 \item Triggered by: Wallet 45 \item Awaited by: Terminal 46 \end{itemize} 47 \item From selected to confirming 48 \begin{itemize} 49 \item Description: Payment confirmation request sent to the Terminals API of C2EC. 50 \item Triggered by: Terminal 51 \item Awaited by: Confirmation process 52 \end{itemize} 53 \item From selected to confirmed 54 \begin{itemize} 55 \item Description: Payment confirmation success will send a withdrawal operation status update event. 56 \item Triggered by: Confirmation process 57 \item Awaited by: Consumer wallets (via Bank-Integration-API) 58 \end{itemize} 59 \item From selected to aborted 60 \begin{itemize} 61 \item Description: Payment confirmation failure will trigger a retry event. 62 \item Triggered by: Confirmation process 63 \item Awaited by: Retry process 64 \end{itemize} 65 \item Refunds as transfer requests 66 \begin{itemize} 67 \item Description: Transfers which represent refunds in C2EC. 68 \item Triggered by: Exchange (using the Wire Gateway API of C2EC) 69 \item Awaited by: Transfer process 70 \end{itemize} 71 \end{itemize} 72 73 \subsection{Abort Handling} 74 75 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. 76 77 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. 78 79 \newpage 80 \include{content/implementation/a-terminal-api} 81 82 \newpage 83 \include{content/implementation/a-bank-integration-api} 84 85 \newpage 86 \include{content/implementation/a-wire-gateway-api} 87 88 \newpage 89 \include{content/implementation/a-processes} 90 91 \newpage 92 \include{content/implementation/a-providers} 93 94 \newpage 95 \include{content/implementation/a-fees}