1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
..
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 **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 <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 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;
}
|
