move terminal APIs to separate API

4 files changed, 310 insertions, 86 deletions

diff --git a/core/api-bank-integration.rst b/core/api-bank-integration.rst
index caf706a7..8f422fe5 100644
--- a/core/api-bank-integration.rst
+++ b/core/api-bank-integration.rst
@@ -242,80 +242,6 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
       transfer_done: boolean;
     }
 
-.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID/confirm
-
-  Endpoint for providers to notify the bank about a payment having happened.
-  This will cause the bank to validate the transaction and allow the
-  withdrawal to proceed. The API is idempotent, meaning sending a payment
-  notification for the same ``WITHDRAWAL_ID`` return successfuly but not
-  change anything.  This endpoint is always *optional*, the bank, exchange and
-  wallet should all eventually notice the wire transfer with or without this
-  endpoint being called.  However, by calling this endpoint checks that might
-  otherwise only happen periodically can be triggered immediately.
-
-  .. note::
-
-    A bank shall **never** just accept this claim that the payment was
-    confirmed, but instead needs to internally attest that the payment was
-    successful using provider-specific transaction validation logic!  The point
-    of this endpoint is merely to trigger this validation **now**.
-
-  Since protocol **vC2EC**.
-
-  FIXME: If this is *just* a trigger, what is the point in supplying the body?
-  After all, a wallet could just do the same POST and then we'd store/process
-  completely bogus information!
-
-  FIXME: why not use /accounts/$USERNAME/withdrawals/$WITHDRAWAL_ID/confirm (and/or /accounts/$USERNAME/withdrawals?) instead?
-
-  **Request:**
-
-  The body of the request must be a `BankWithdrawalConfirmationRequest`.
-
-  **Response:**
-
-  :http:statuscode:`204 No content`:
-    The payment notification was processed successfully.
-  :http:statuscode:`404 Not found`:
-    The withdrawal operation was not found.
-  :http:statuscode:`409 Conflict`:
-    The withdrawal operation has been aborted previously and can't be aborted
-
-  **Details:**
-
-  .. ts:def:: BankWithdrawalConfirmationRequest
-
-    interface WithdrawalConfirmationRequest {
-
-      // The provider specific transaction identifier.
-      // This identifier is used by the bank to attest the
-      // payment at the providers backend.
-      //
-      // FIXME: how is this used?
-      // FIXME: what if it is wrong?
-      provider_transaction_id: string;
-
-      // An identifier, which identifies the device
-      // processing the payment for the withdrawal
-      // triggering the confirmation (e.g. Terminal
-      // or ATM). This is needed to link the withdrawal
-      // to a terminal owned by a specific provider.
-      // This will decide about how the withdrawal
-      // is attested. The device must be known to
-      // the exchange and be somehow registered.
-      //
-      // FIXME: probably more general to use a *string*.
-      // FIXME: how is this used?
-      terminal_id: number;
-
-      // The amount to withdraw. Fees are to be sent in the
-      // separate field 'fees' and not included in the amount.
-      amount: Amount;
-
-      // The fees, the customer paid at the providers facility.
-      card_fees: Amount;
-    }
-
 
 .. http:post:: /withdrawal-operation/$WITHDRAWAL_ID/abort
 
diff --git a/core/api-corebank.rst b/core/api-corebank.rst
index 80424464..4a0288a4 100644
--- a/core/api-corebank.rst
+++ b/core/api-corebank.rst
@@ -718,18 +718,6 @@ Account withdrawals
       // @since **vC2EC**
       suggested_amount?: Amount;
 
-      // KYC data in case where enable somebody else
-      // to withdraw from "our" account?
-      // FIXME: what would be a good ID?
-      // FIXME: need a way to determine
-      // and return limits per ID!
-      // FIXME: for C2EC we only learn the card at the
-      // *end* of the process, while with NDA we learn
-      // a user ID at the *beginning* of the process.
-      // How to handle both cases nicely?
-      // @since **vC2EC**
-      kyc_link?: TBD;
-
       // The non-Taler card fees the customer will have
       // to pay to the account owner, bank and/or
       // payment service provider
diff --git a/core/api-terminal.rst b/core/api-terminal.rst
new file mode 100644
index 00000000..b89a31af
--- /dev/null
+++ b/core/api-terminal.rst
@@ -0,0 +1,309 @@
+..
+  This file is part of GNU TALER.
+
+  Copyright (C) 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/>
+
+.. target audience: developer, core developer
+
+.. _corebank-api:
+
+============
+Terminal API
+============
+
+.. contents:: Table of Contents
+  :local:
+
+Introduction
+------------
+
+Terminals are devices where users can withdraw digital cash.
+
+This API is offered by a payment service backend and is used by such
+terminals.  It enables imposing limits on withdrawals per unique user ID (and
+communicating such limits to the terminals) as well as setting up and
+triggering withdrawal operations.
+
+Implementations of this API typically interact with a terminal-specific
+payment service (or a bank) to realize the service.
+
+
+Authentication
+--------------
+
+Most requests require the client to authenticate using a bearer token.
+The bearer token is expected to be part of the service configuration.
+
+
+Config
+------
+
+.. http:get:: /config
+
+  Return the protocol version and configuration information about the bank.
+  This specification corresponds to ``current`` protocol being version **0**.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    Response is a `TerminalConfig`.
+
+  **Details:**
+
+  .. ts:def:: TerminalConfig
+
+    interface TerminalConfig {
+      // Name of the API.
+      name: "taler-terminal";
+
+      // libtool-style representation of the Bank protocol version, see
+      // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
+      // The format is "current:revision:age".
+      version: string;
+
+      // Terminal provider display name to be used in user interfaces.
+      provider_name: string;
+
+      // Currency supported by this terminal.
+      // FIXME: needed?
+      currency: string;
+
+      // Wire transfer type supported by the terminal.
+      // FIXME: needed?
+      wire_type: string;
+    }
+
+
+.. http:get:: /quotas/$UUID
+
+  Obtain the current transaction limit for the given $UUID.
+  The UUID should be an encoding of a unique identifier of
+  the user.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    Response is a `WithdrawLimit`.
+
+  **Details:**
+
+  .. ts:def:: WithdrawLimit
+
+    interface WithdrawLimit {
+      // Maximum amount that can be withdrawn now.
+      limit: Amount;
+
+      // Time when the limit may increase.
+      expiration: Timestamp;
+    }
+
+
+.. http:post:: /quotas/$UUID/lock
+
+  This endpoint allows a terminal to reserve a given amount
+  from the user's quota, ensuring that a subsequent operation
+  will not fail due to a quota violation.
+
+  **Request:**
+
+  The request should be a `WithdrawLimitLock`.
+
+  **Response:**
+
+  :http:statuscode:`204 No content`:
+    The change was accepted.
+  :http:statuscode:`409 Conflict`:
+    The proposed lock would push the user above the limit.
+
+  **Details:**
+
+  .. ts:def:: WithdrawLimitLock
+
+    interface WithdrawLimitLock {
+
+      // Amount that should be reserved from the quota.
+      limit: Amount;
+
+      // ID for the lock.  FIXME: could also be 32-byte nonce?
+      lock: String;
+
+      // How long should the lock be held?
+      expiration: Timestamp;
+    }
+
+.. http:delete:: /quotas/$UUID/lock/$LOCK
+
+  This endpoint allows the terminal to clear a lock it may have
+  previously created.
+
+  **Response:**
+
+  :http:statuscode:`204 No content`:
+    The lock was cleared.
+  :http:statuscode:`404 Not found`:
+    The lock is unknown.
+  :http:statuscode:`409 Conflict`:
+    The lock was already used in a withdrawal operation.
+
+
+.. http:post:: /withdrawals
+
+  This endpoint allows the terminal to set up a new withdrawal
+  operation.
+
+  **Request:**
+
+  The request should be a `TerminalWithdrawalSetup`.
+
+  **Response:**
+
+  :http:statuscode:`200 Ok`:
+    The operation was created.  The response will be
+    a `BankWithdrawalOperationStatus`.
+  :http:statuscode:`404 Not found`:
+    A lock was specified but the lock is not known for
+    the given user.
+  :http:statuscode:`409 Conflict`:
+    A conflicting withdrawal operation already exists or
+    the amount would violate the quota for the specified user.
+
+  **Details:**
+
+  .. ts:def:: TerminalWithdrawalSetup
+
+    interface TerminalWithdrawalSetup {
+
+      // Amount to withdraw.  If given, the wallet
+      // cannot change the amount!
+      amount?: Amount;
+
+      // Suggested amount to withdraw. If given, the wallet can
+      // still change the suggestion.
+      suggested_amount?: Amount;
+
+      // A provider-specific transaction identifier.
+      // This identifier may be used to attest the
+      // payment at the provider's backend. Optional,
+      // as we may not know it at this time.
+      provider_transaction_id?: string;
+
+      // An identifier, which identifies the device
+      // processing the payment for the withdrawal
+      // triggering the confirmation (e.g. Terminal
+      // or ATM). This is useful to internally link
+      // the withdrawal to a terminal owned by a
+      // specific provider.
+      terminal_id?: string;
+
+      // The non-Taler card fees the customer will have
+      // to pay to the service provider
+      // they are using to make this withdrawal.
+      card_fees: Amount;
+
+      // ID identifying the withdrawal operation being created.
+      withdrawal_id: string;
+
+      // Unique user ID of the user.  Optional
+      // in case a user Id is not (yet) known.
+      user_uuid?: string;
+
+      // ID identifying a lock on the quota that the client
+      // may wish to use in this operation.  May only be
+      // present if ``user_uuid`` is also given.
+      lock?: string;
+
+    }
+
+
+.. http:post:: /withdrawals/$WITHDRAWAL_ID/confirm
+
+  Endpoint for providers to notify the terminal backend about a payment having
+  happened.  This will cause the bank to validate the transaction and allow
+  the withdrawal to proceed. The API is idempotent, meaning sending a payment
+  notification for the same ``WITHDRAWAL_ID`` return successfuly but not
+  change anything.  This endpoint is always *optional*: the bank, exchange and
+  wallet should all eventually notice the wire transfer with or without this
+  endpoint being called.  However, by calling this endpoint checks that might
+  otherwise only happen periodically can be triggered immediately.
+
+  The endpoint may also be used to associate a user ID at a very late stage
+  with the withdrawal --- and still get an immediate failure if we are above
+  the quota.
+
+  .. note::
+
+    The backend shall **never** just accept this claim that the payment was
+    confirmed, but instead needs to internally attest that the payment was
+    successful using provider-specific transaction validation logic!  The point
+    of this endpoint is merely to trigger this validation **now**.
+
+  **Request:**
+
+  The body of the request must be a `TerminalWithdrawalConfirmationRequest`.
+
+  **Response:**
+
+  :http:statuscode:`204 No content`:
+    The payment notification was processed successfully.
+  :http:statuscode:`404 Not found`:
+    The withdrawal operation was not found.
+  :http:statuscode:`409 Conflict`:
+    The withdrawal operation has been previously aborted
+    and cannot be confirmed anymore.
+  :http:statuscode:`451 Unavailable for Legal Reasons`:
+    The withdrawal operation cannot be confirmed because
+    it would put the user above the legal limit.  The
+    payment service will eventually bounce the transfer
+    (if it were to become effective), but the user should
+    already be shown an error.
+
+  **Details:**
+
+  .. ts:def:: TerminalWithdrawalConfirmationRequest
+
+    interface TerminalWithdrawalConfirmationRequest {
+
+      // A provider-specific transaction identifier.
+      // This identifier may be used to facilitate the
+      // backend to check that the credit was confirmed.
+      provider_transaction_id?: string;
+
+      // A user-specific identifier for quota checks.
+      user_uuid?: string;
+
+      // ID identifying a lock on the quota that the client
+      // may wish to use in this operation.  May only be
+      // present if ``user_uuid`` is also given.
+      lock?: string;
+
+    }
+
+
+
+Endpoints for Integrated Sub-APIs
+---------------------------------
+
+.. http:any:: /taler-integration/*
+
+  All endpoints under this prefix are specified by the.
+  :doc:`GNU Taler bank integration API </core/api-bank-integration>`.
+  This API handles the communication with Taler wallets.
+
+
+.. http:any:: /accounts/$USERNAME/taler-wire-gateway/*
+
+   All endpoints under this prefix are specified
+   by the :doc:`GNU Taler wire gateway API </core/api-bank-wire>`.
+
+   The endpoints are only available for accounts configured with ``is_taler_exchange=true``.
diff --git a/core/index-bank-apis.rst b/core/index-bank-apis.rst
index f108df32..1097126a 100644
--- a/core/index-bank-apis.rst
+++ b/core/index-bank-apis.rst
@@ -33,6 +33,7 @@ Bank RESTful APIs
   api-bank-revenue
   api-bank-integration
   api-bank-conversion-info
+  api-terminal
 
 .. toctree::
   :hidden: