docs: add nonce2ecash docs

1 files changed, 163 insertions, 0 deletions

diff --git a/core/api-nonce2ecash.rst b/core/api-nonce2ecash.rst
new file mode 100644
index 00000000..9e69e954
--- /dev/null
+++ b/core/api-nonce2ecash.rst
@@ -0,0 +1,163 @@
+..
+  This file is part of GNU TALER.
+
+  Copyright (C) 2014-2024 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
+
+===========================
+The nonce2ecash RESTful API
+===========================
+
+.. note::
+  
+  **This API is experimental and not yet implemented**
+
+This chapter describe the APIs that third party providers need to integrate to allow 
+withdrawals through indirect payment channels like credit cards or ATM.
+
+.. contents:: Table of Contents
+
+--------------
+Authentication
+--------------
+
+Terminals which authenticate against the nonce2ecash API must provide their respective 
+access token. Therefore they provide a ``Authorization: Bearer $ACCESS_TOKEN`` header, 
+where `$ACCESS_TOKEN`` is a secret authentication token configured by the exchange and
+must begin with the RFC 8959 prefix.
+
+----------------------------
+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 `Nonce2ecashConfig` 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
+
+  Initiate the 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 terminal of the provider requesting a withdrawal by nonce.
+      // Assigned by the exchange.
+      provider_terminal_id: SafeUint64;
+    }
+
+  **Response:**
+
+  :http:statuscode:`204 No content`:
+    The withdrawal was successfully registered.
+  :http:statuscode:`400 Bad request`:
+    The ``WithdrawRegistration`` request was malformed or contained invalid parameters.
+  :http:statuscode:`500 Internal Server error`:
+    The registration of the withdrawal failed due to server side issues.
+
+.. http:get:: /withdrawal-operation/$WITHDRAWAL_ID
+
+  Query information about a withdrawal operation, identified by the ``WITHDRAWAL_ID``.
+
+  **Response:**
+
+  :http:statuscode:`200 Ok`:
+    The withdrawal was found and is returned in the response body as ``Withdrawal``.
+  :http:statuscode:`404 Not found`:
+    nonce2ecash does not have a withdrawal registered with the specified ``WITHDRAWAL_ID``.
+
+  **Details**
+
+    .. ts:def:: Withdrawal
+
+      interface Withdrawal {
+
+        // 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;
+      }
+
+.. 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:`400 Bad request`:
+    The ``PaymentNotification`` request was malformed or contained invalid parameters.
+  :http:statuscode:`404 Not found`:
+    nonce2ecash does not have a withdrawal registered with the specified ``WITHDRAWAL_ID``.
+  :http:statuscode:`500 Internal Server error`:
+    The ``PaymentNotification`` could not be processed due to server side issues.