[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: gnunet
Subject: [taler-docs] 07/36: define merchant-bank facade
Date: Tue, 22 Jun 2021 19:35:03 +0200

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 <>
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 
+  You should have received a copy of the GNU Lesser General Public License 
along with
+  TALER; see the file COPYING.  If not, see <>
+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).
+The bank library authenticates requests to the bank merchant API using
+`HTTP basic auth <>`_.
+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 
+    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 
+    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 
+  * A value that is **larger** than all other row IDs if *delta* is 
+  **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 
+    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-wire
+  api-sync
+  api-wire
+  api-bank-merchant
-  api-sync

To stop receiving notification emails like this one, please contact

reply via email to

[Prev in Thread] Current Thread [Next in Thread]