summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--core/api-bank-merchant.rst122
-rw-r--r--core/index.rst5
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 00000000..790d3f74
--- /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 95037d48..7ead2193 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