api-bank-revenue.rst (4995B)
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 .. http:get:: /config 26 27 Return the protocol version and configuration information about the bank. 28 This specification corresponds to ``current`` protocol being version **1**. 29 30 **Response:** 31 32 :http:statuscode:`200 OK`: 33 The exchange responds with a `RevenueConfig` object. This request should 34 virtually always be successful. 35 36 **Details:** 37 38 .. ts:def:: RevenueConfig 39 40 interface RevenueConfig { 41 // Name of the API. 42 name: "taler-revenue"; 43 44 // libtool-style representation of the Bank protocol version, see 45 // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning 46 // The format is "current:revision:age". 47 version: string; 48 49 // Currency used by this gateway. 50 currency: string; 51 52 // URN of the implementation (needed to interpret 'revision' in version). 53 // @since v0, may become mandatory in the future. 54 implementation?: string; 55 } 56 57 58 -------------- 59 Authentication 60 -------------- 61 62 The bank library authenticates requests to the bank merchant API using 63 `HTTP basic auth <https://tools.ietf.org/html/rfc7617>`_. 64 65 -------------------------------- 66 Querying the transaction history 67 -------------------------------- 68 69 .. http:get:: /history 70 71 Return a list of transactions made to an account. 72 73 The bank account is determined via the base URL and/or the 74 user name in the ``Authorization`` header. In fact, the transaction history 75 might come from a "virtual" account, where multiple real bank accounts are 76 merged into one history. 77 78 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. 79 80 **Request:** 81 82 :query limit: *Optional.* 83 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. 84 :query offset: *Optional.* 85 Starting ``row_id`` for :ref:`pagination <row-id-pagination>`. Since protocol v1. 86 :query timeout_ms: *Optional.* 87 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. 88 :query delta: *Optional.* 89 Deprecated in protocol **v1**. Use *limit* instead. 90 :query start: *Optional.* 91 Deprecated in protocol **v1**. Use *offset* instead. 92 :query long_poll_ms: *Optional.* 93 Deprecated in protocol **v1**. Use *timeout_ms* instead. 94 95 **Response:** 96 97 :http:statuscode:`200 OK`: 98 JSON object of type `RevenueIncomingHistory`. 99 :http:statuscode:`400 Bad request`: 100 Request malformed. The bank replies with an `ErrorDetail` object. 101 :http:statuscode:`401 Unauthorized`: 102 Authentication failed, likely the credentials are wrong. 103 :http:statuscode:`404 Not found`: 104 The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object. 105 106 **Details:** 107 108 .. ts:def:: RevenueIncomingHistory 109 110 interface RevenueIncomingHistory { 111 // Array of incoming transactions. 112 incoming_transactions : RevenueIncomingBankTransaction[]; 113 114 // Full payto URI to identify the receiver of funds. 115 // Credit account is shared by all incoming transactions 116 // as per the nature of the request. 117 credit_account: string; 118 } 119 120 .. ts:def:: RevenueIncomingBankTransaction 121 122 interface RevenueIncomingBankTransaction { 123 // Opaque identifier of the returned record. 124 row_id: SafeUint64; 125 126 // Date of the transaction. 127 date: Timestamp; 128 129 // Amount received before credit_fee. 130 amount: Amount; 131 132 // Fee payed by the creditor. 133 // If not null, creditor actually received amount - credit_fee 134 // @since **v1** 135 credit_fee?: Amount; 136 137 // Full payto URI to identify the sender of funds. 138 debit_account: string; 139 140 // The wire transfer subject. 141 subject: string; 142 }