[taler-docs] 07/36: define merchant-bank facade

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository docs.

commit 3579cf06efb3dfe242179136e62abbb5ae51ce6a
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sun May 9 19:52:42 2021 +0200

    define merchant-bank facade
---
 core/api-bank-merchant.rst | 122 +++++++++++++++++++++++++++++++++++++++++++++
 core/index.rst             |   5 +-
 2 files changed, 125 insertions(+), 2 deletions(-)

diff --git a/core/api-bank-merchant.rst b/core/api-bank-merchant.rst
new file mode 100644
index 0000000..790d3f7
--- /dev/null
+++ b/core/api-bank-merchant.rst
@@ -0,0 +1,122 @@
+..
+  This file is part of GNU TALER.
+  Copyright (C) 2021 Taler Systems SA
+
+  TALER is free software; you can redistribute it and/or modify it under the
+  terms of the GNU 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 Lesser General Public License for more 
details.
+
+  You should have received a copy of the GNU Lesser General Public License 
along with
+  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
+
+============================
+Taler Bank Merchant HTTP API
+============================
+
+This section describes an API offered by the Taler wire gateway. The API is
+used by the merchant to query for incoming transactions.
+
+This API is TO BE implemented by the Taler Demo Bank, as well as by
+LibEuFin (work in progress).
+
+
+--------------
+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:: ${BASE_URL}/history
+
+  Return a list of transactions made from an exchange to the merchant.
+
+  Incoming transactions must contain a valid wire transfer identifier and
+  exchange base URL.  If a bank transaction does not conform to the right
+  syntax, the wire gateway must not report it to the merchant via this
+  endpoint.
+
+  The bank account of the merchant 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 `MerchantIncomingHistory`.
+  :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.
+
+  .. ts:def:: MerchantIncomingHistory
+
+    interface MerchantIncomingHistory {
+
+      // Array of incoming transactions.
+      incoming_transactions : MerchantIncomingBankTransaction[];
+
+    }
+
+  .. ts:def:: MerchantIncomingBankTransaction
+
+    interface MerchantIncomingBankTransaction {
+
+      // 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;
+
+      // Base URL of the exchange where the transfer originated form.
+      exchange_url: string;
+
+      // The wire transfer identifier.
+      wtid: WireTransferIdentifierRawP;
+    }
diff --git a/core/index.rst b/core/index.rst
index 95037d4..7ead219 100644
--- a/core/index.rst
+++ b/core/index.rst
@@ -32,12 +32,13 @@ interfaces between the core components of Taler.
   api-common
   api-error
   api-exchange
-  api-wire
   api-merchant
   api-auditor
+  api-sync
+  api-wire
+  api-bank-merchant
   api-bank-integration
   api-bank-access
   wireformats
-  api-sync
   taler-uri
   errors

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.