api-bank-revenue.rst (5277B)
1 .. 2 This file is part of GNU TALER. 3 Copyright (C) 2021-2023 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 2.1, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 16 .. _taler-bank-merchant-http-api: 17 18 =========================== 19 Taler Bank Revenue HTTP API 20 =========================== 21 22 This section describes an API offered by libeufin-nexus and libeufin-bank. The API is 23 used by the merchant (or other parties) to query for incoming transactions to their account. 24 25 26 --------------- 27 Version History 28 --------------- 29 30 The current protocol version is **v1**. 31 32 * The merchant is currently targeting protocol version **v1**. 33 34 **Version history:** 35 36 * ``v1``: pagination API consistency fixes 37 38 **Upcoming versions:** 39 40 * None anticipated. 41 42 **Ideas for future version:** 43 44 * ``vXXX``: marker for features not yet targeted for release 45 46 47 .. http:get:: /config 48 49 Return the protocol version and configuration information about the bank. 50 51 **Response:** 52 53 :http:statuscode:`200 OK`: 54 The exchange responds with a `RevenueConfig` object. This request should 55 virtually always be successful. 56 57 **Details:** 58 59 .. ts:def:: RevenueConfig 60 61 interface RevenueConfig { 62 // Name of the API. 63 name: "taler-revenue"; 64 65 // libtool-style representation of the Bank protocol version, see 66 // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning 67 // The format is "current:revision:age". 68 version: string; 69 70 // Currency used by this gateway. 71 currency: string; 72 73 // URN of the implementation (needed to interpret 'revision' in version). 74 // @since v0, may become mandatory in the future. 75 implementation?: string; 76 } 77 78 79 -------------- 80 Authentication 81 -------------- 82 83 The bank library authenticates requests to the bank merchant API using 84 `HTTP basic auth <https://tools.ietf.org/html/rfc7617>`_. 85 86 -------------------------------- 87 Querying the transaction history 88 -------------------------------- 89 90 .. http:get:: /history 91 92 Return a list of transactions made to an account. 93 94 The bank account is determined via the base URL and/or the 95 user name in the ``Authorization`` header. In fact, the transaction history 96 might come from a "virtual" account, where multiple real bank accounts are 97 merged into one history. 98 99 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. 100 101 **Request:** 102 103 :query limit: *Optional.* 104 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. 105 :query offset: *Optional.* 106 Starting ``row_id`` for :ref:`pagination <row-id-pagination>`. Since protocol v1. 107 :query timeout_ms: *Optional.* 108 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. 109 :query delta: *Optional.* 110 Deprecated in protocol **v1**. Use *limit* instead. 111 :query start: *Optional.* 112 Deprecated in protocol **v1**. Use *offset* instead. 113 :query long_poll_ms: *Optional.* 114 Deprecated in protocol **v1**. Use *timeout_ms* instead. 115 116 **Response:** 117 118 :http:statuscode:`200 OK`: 119 JSON object of type `RevenueIncomingHistory`. 120 :http:statuscode:`400 Bad request`: 121 Request malformed. The bank replies with an `ErrorDetail` object. 122 :http:statuscode:`401 Unauthorized`: 123 Authentication failed, likely the credentials are wrong. 124 :http:statuscode:`404 Not found`: 125 The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object. 126 127 **Details:** 128 129 .. ts:def:: RevenueIncomingHistory 130 131 interface RevenueIncomingHistory { 132 // Array of incoming transactions. 133 incoming_transactions : RevenueIncomingBankTransaction[]; 134 135 // Full payto URI to identify the receiver of funds. 136 // Credit account is shared by all incoming transactions 137 // as per the nature of the request. 138 credit_account: string; 139 } 140 141 .. ts:def:: RevenueIncomingBankTransaction 142 143 interface RevenueIncomingBankTransaction { 144 // Opaque identifier of the returned record. 145 row_id: SafeUint64; 146 147 // Date of the transaction. 148 date: Timestamp; 149 150 // Amount received before credit_fee. 151 amount: Amount; 152 153 // Fee payed by the creditor. 154 // If not null, creditor actually received amount - credit_fee 155 // @since **v1** 156 credit_fee?: Amount; 157 158 // Full payto URI to identify the sender of funds. 159 debit_account: string; 160 161 // The wire transfer subject. 162 subject: string; 163 }