..
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
.. _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 **0**.
**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 `_.
--------------------------------
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 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 `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;
}