..
  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 **1**.

  **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 ``row_id`` numerical identifier. Its semantics (including its sorting order) are determined by the bank server and are completely opaque to the client.

  **Request:**

  :query limit: *Optional.*
    At most return the given number of results. Negative for descending by ``row_id``, positive for ascending by ``row_id``. Defaults to ``-20``. Since protocol v1.
  :query offset: *Optional.* 
    Starting ``row_id`` for :ref:`pagination <row-id-pagination>`. Since protocol v1.
  :query timeout_ms: *Optional.*
    Timeout in milliseconds, for :ref:`long-polling <long-polling>`, to wait for at least one element to be shown. Only useful if *limit* is positive. Since protocol v1.
  :query delta: *Optional.*
    Deprecated in protocol v1. Use *limit* instead.
  :query start: *Optional.*
    Deprecated in protocol v1. Use *offset* instead.
  :query long_poll_ms: *Optional.*
    Deprecated in protocol v1. Use *timeout_ms* instead.

  **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;
    }