commit ca86b665f7b52a55800fb9389ffc8d3afa5322fd
parent 01e0c4c299617ceb9224430a7a1c5570dc92727e
Author: Joel-Haeberli <haebu@rubigen.ch>
Date: Wed, 6 Mar 2024 11:14:41 +0100
spec: fix api spec and convert to rst format
Diffstat:
3 files changed, 125 insertions(+), 2 deletions(-)
diff --git a/docs/content/appendix/meeting_notes.tex b/docs/content/appendix/meeting_notes.tex
@@ -120,7 +120,8 @@
\textbf{Topics}
\begin{itemize}
- \item API Spec
+ \item API Spec nonce2ecash
+ \item Database Spec nonce2ecash
\end{itemize}
\textbf{Questions}
@@ -132,7 +133,9 @@
\textbf{Action points}
\begin{itemize}
- \item
+ \item write API specification in .rst format (see /docs/core/api-*.rst in taler docs git)
+ \item use Bank integration API
+ \item write SQL schema and generate UML using schema-spy instead of writing UML.
\end{itemize}
\textbf{Decisions}
diff --git a/docs/thesis.pdf b/docs/thesis.pdf
Binary files differ.
diff --git a/specs/api-nonce2ecash.rst b/specs/api-nonce2ecash.rst
@@ -0,0 +1,120 @@
+..
+ This file is part of GNU TALER.
+
+ Copyright (C) 2014-2023 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Affero General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Joel Häberli
+
+==========================
+Taler nonce2ecash API
+==========================
+
+This chapter describe the APIs that third party providers need to integrate withdrawal through indirect
+payment channels like credit cards or ATM.
+
+.. contents:: Table of Contents
+
+----------------------------
+Configuration of nonce2ecash
+----------------------------
+
+.. http:get:: /config
+
+ Return the protocol version and configuration information about the nonce2ecash API.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The exchange responds with a `IntegrationConfig` object. This request should
+ virtually always be successful.
+
+ **Details:**
+
+ .. ts:def:: Nonce2ecashConfig
+
+ interface Nonce2ecashConfig {
+ // Name of the API.
+ name: "taler-nonce2ecash";
+
+ // libtool-style representation of the nonce2ecash protocol version, see
+ // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
+ // The format is "current:revision:age".
+ version: string;
+ }
+
+
+-----------------------------
+Withdrawing using nonce2ecash
+-----------------------------
+
+Withdrawals with a nonce2ecash are based on withdrawal operations which register a withdrawal identifier
+(nonce) at the nonce2ecash component. The provider must first create a unique identifier for the withdrawal
+operation (the ``WITHDRAWAL_ID``) to interact with the withdrawal operation and eventually withdraw using the wallet.
+
+.. http:post:: /withdrawal-operation
+
+ Query information about a withdrawal operation, identified by the ``WITHDRAWAL_ID``.
+
+ **Request:**
+
+ .. ts:def:: WithdrawRegistration
+
+ interface WithdrawRegistration {
+ // Maps a nonce generated by the provider to a reserve public key generated by the wallet.
+ withdrawal_id: ShortHashCode;
+
+ // Reserve public key generated by the wallet.
+ // According to TALER_ReservePublicKeyP (https://docs.taler.net/core/api-common.html#cryptographic-primitives)
+ reserve_pub_key: EddsaPublicKey;
+
+ // Optional amount for the withdrawal.
+ amount?: Amount;
+
+ // Id of the provider requesting a withdrawal by nonce.
+ providerId: SafeUint64;
+ }
+
+ **Response:**
+
+ :http:statuscode:`204 No content`:
+ The withdrawal was successfully registered
+
+.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID
+
+ Notifies nonce2ecash about an executed payment for a specific withdrawal.
+
+ **Request:**
+
+ .. ts:def:: PaymentNotification
+
+ interface PaymentNotification {
+
+ // Unique identifier of the provider transaction.
+ provider_transaction_id: string;
+
+ // Specifies the amount which was payed to the provider (without fees).
+ // This amount shall be put into the reserve linked to by the withdrawal id.
+ amount: Amount;
+
+ // Fees associated with the payment.
+ fees: Amount;
+ }
+
+ **Response:**
+
+ :http:statuscode:`204 No content`:
+ nonce2ecash received the ``PaymentNotification`` successfully and will further process
+ the withdrawal.
+ :http:statuscode:`404 Not found`:
+ nonce2ecash does not have a withdrawal registered with the specified ``WITHDRAWAL_ID``.
