From 3579cf06efb3dfe242179136e62abbb5ae51ce6a Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 9 May 2021 19:52:42 +0200 Subject: define merchant-bank facade --- core/api-bank-merchant.rst | 122 +++++++++++++++++++++++++++++++++++++++++++++ core/index.rst | 5 +- 2 files changed, 125 insertions(+), 2 deletions(-) create mode 100644 core/api-bank-merchant.rst (limited to 'core') 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 + +============================ +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 `_. + +-------------------------------- +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 -- cgit v1.2.3