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
|
..
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 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
============================
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 <https://tools.ietf.org/html/rfc7617>`_.
--------------------------------
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;
}
|
