a-terminal-api.tex (4376B)
1 \subsubsection{Terminal API} 2 \label{sec-implementation-terminal-api} 3 4 This section describes the Implementation of the Terminal API \cite{taler-terminal-api}. 5 6 The C2EC Terminals API implements following endpoints: 7 8 \begin{itemize} 9 \item GET /config 10 \item POST /withdrawals 11 \item GET /withdrawals/[WOPID] 12 \item GET /withdrawals/[WOPID]/check 13 \end{itemize} 14 15 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. 16 17 \textbf{Configuration (/config)} 18 19 This endpoint returns the configuration for the respective terminal. To support multi-provider setup, the respective provider is read from the basic-auth credentials \autoref{sec-terminal-api-auth}. This means that the configuration response will be different when requesting the endpoint using a terminal from provider A than requesting from a terminal of provider B. This configuration also supplies the base fees of the Exchange operator. These fees shall be communicated to the customer on the terminal and must be added to the withdraw amount. These fees are only the Exchange fees. The payment service provider might want to add their own (see \autoref{sec-implementation-fees}). 20 21 \textbf{Setting up a withdrawal (/withdrawals)} 22 23 The setup of a withdrawal generates the \textit{WOPID} which is a cryptographically sound 32-byte nonce and will be encoded using the base 32 crockford encoding \cite{crockford}. The cryptographical strength is crucial, because otherwise risks as described in \autoref{sec-security-wopid} can materialise themself. 24 25 Terminals are advised to always set the \textit{amount} field of the request, if they can define a fixed amount. This will force the Wallet to withdraw this exact amount and cannot be overwritten by it. The \textit{suggested amount} field should only be used when the terminal cannot know how much money will be withdrawn (such as an ATM or similar). 26 27 \textbf{Status of withdrawal (/withdrawals/[WOPID])} 28 29 When the terminal setup the withdrawal successful and received the \textit{WOPID}, the terminal wants to wait before effectively authorizing the transaction until the Wallet has registered the parameters for the withdrawal. This endpoint allows this and supports long-polling such that the terminal may directly ask for the status after setting up the withdrawal. The endpoint is an exact replication of the Bank-Integration API status endpoint as described in \autoref{sec-implementation-bank-integration-api-status} 30 31 \textbf{Trigger Confirmation (/withdrawals/[WOPID]/check)} 32 33 Once the terminal authorized the transaction at the providers backend and received the notification, that the transaction was processed at the providers backend, the terminal can trigger the confirmation of the transaction by calling this endpoint. This is also the point where the terminal can know the fees of the provider (if any) and send them to the C2EC component. If for some reason it is not possible to know the fees here, potential fees can also be considered during the confirmation of the payment (this will lead to bad user-experience \autoref{sec-implementation-fees}). 34 35 \textbf{Terminal side abort (/withdrawals/[WOPID]/abort)} 36 \label{sec-implementation-terminal-api-abort} 37 38 As long as the withdrawal was not authorized, it can be aborted by the terminal through this API. If the withdrawal was already authorized, the abort operation will not work and the refund process must be used to revert the authorized payment. 39 40 \textbf{Taler Integration (/taler-integration/*)} 41 42 Under the \textit{/taler-integration/} sub-path the Bank-Integration API is reachable. Endpoints under this subpath are used by the Wallet to register parameters of a withdrawal and ask for the status of a withdrawal operation. The endpoints of the Bank-Integration API are described in \autoref{sec-implementation-bank-integration-api} 43 44 \textbf{Taler Integration (/taler-wire-gateway/*)} 45 46 The sub-path \textit{/taler-wire-gateway/} defines the location of the wire-gateway API used by the Taler Wirewatch component of the Exchange. It is used by the exchange to allow creation of withdrawable reserves. Therefore the wire gateway API was implemented as described in section \autoref{sec-implementation-wire-gateway-api}