1 files changed, 152 insertions, 0 deletions
diff --git a/core/api-bank-revenue.rst b/core/api-bank-revenue.rst
new file mode 100644
index 00000000..98b38113
--- /dev/null
+++ b/core/api-bank-revenue.rst
@@ -0,0 +1,152 @@
+..
+  This file is part of GNU TALER.
+  Copyright (C) 2021-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/>
+
+.. _taler-bank-merchant-http-api:
+
+===========================
+Taler Bank Revenue HTTP API
+===========================
+
+This section describes an API offered by libeufin-nexus and libeufin-bank. The API is
+used by the merchant (or other parties) to query for incoming transactions to their account.
+
+.. 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`:
+    The exchange responds with a `RevenueConfig` object. This request should
+    virtually always be successful.
+
+  **Details:**
+
+  .. ts:def:: RevenueConfig
+
+    interface RevenueConfig {
+      // Name of the API.
+      name: "taler-revenue";
+
+      // 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;
+
+      // Currency used by this gateway.
+      currency: string;
+
+      // URN of the implementation (needed to interpret 'revision' in version).
+      // @since v0, may become mandatory in the future.
+      implementation?: string;
+    }
+
+
+--------------
+Authentication
+--------------
+
+The bank library authenticates requests to the bank merchant API using
+`HTTP basic auth <https://tools.ietf.org/html/rfc7617>`_.
+
+--------------------------------
+Querying the transaction history
+--------------------------------
+
+.. http:get:: /history
+
+  Return a list of transactions made to an account.
+
+  The bank account is determined via the base URL and/or the
+  user name in the ``Authorization`` header.  In fact, the transaction history
+  might come from a "virtual" account, where multiple real bank accounts are
+  merged into one history.
+
+  Transactions are identified by an opaque numeric identifier, referred to here
+  as *row ID*.  The semantics of the row ID (including its sorting order) are
+  determined by the bank server and completely opaque to the client.
+
+  The list of returned transactions is determined by a row ID *starting point*
+  and a signed non-zero integer *delta*:
+
+  * If *delta* is positive, return a list of up to *delta* transactions (all matching
+    the filter criteria) strictly **after** the starting point.  The transactions are sorted
+    in **ascending** order of the row ID.
+  * If *delta* is negative, return a list of up to *-delta* transactions (all matching
+    the filter criteria) strictly **before** the starting point.  The transactions are sorted
+    in **descending** order of the row ID.
+
+  If *starting point* is not explicitly given, it defaults to:
+
+  * A value that is **smaller** than all other row IDs if *delta* is **positive**.
+  * A value that is **larger** than all other row IDs if *delta* is **negative**.
+
+  **Request:**
+
+  :query start: *Optional.*
+    Row identifier to explicitly set the *starting point* of the query.
+  :query delta:
+    The *delta* value that determines the range of the query.
+  :query long_poll_ms: *Optional.*  If this parameter is specified and the
+    result of the query would be empty, the bank will wait up to ``long_poll_ms``
+    milliseconds for new transactions that match the query to arrive and only
+    then send the HTTP response.  A client must never rely on this behavior, as
+    the bank may return a response immediately or after waiting only a fraction
+    of ``long_poll_ms``.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    JSON object of type `RevenueIncomingHistory`.
+  :http:statuscode:`400 Bad request`:
+    Request malformed. The bank replies with an `ErrorDetail` object.
+  :http:statuscode:`401 Unauthorized`:
+    Authentication failed, likely the credentials are wrong.
+  :http:statuscode:`404 Not found`:
+    The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object.
+
+  **Details:**
+
+  .. ts:def:: RevenueIncomingHistory
+
+    interface RevenueIncomingHistory {
+      // Array of incoming transactions.
+      incoming_transactions : RevenueIncomingBankTransaction[];
+
+      // Payto URI to identify the receiver of funds.
+      // Credit account is shared by all incoming transactions
+      // as per the nature of the request.
+      credit_account: string;
+    }
+
+  .. ts:def:: RevenueIncomingBankTransaction
+
+    interface RevenueIncomingBankTransaction {
+      // Opaque identifier of the returned record.
+      row_id: SafeUint64;
+
+      // Date of the transaction.
+      date: Timestamp;
+
+      // Amount transferred.
+      amount: Amount;
+
+      // Payto URI to identify the sender of funds.
+      debit_account: string;
+
+      // The wire transfer subject.
+      subject: string;
+    }