api-bank-wire.rst (3178B)
1 .. 2 This file is part of GNU TALER. 3 Copyright (C) 2019-2025, 2026 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-wire-gateway-http-api: 17 18 =========================== 19 Taler Wire Gateway HTTP API 20 =========================== 21 22 --------------- 23 Version History 24 --------------- 25 26 * ``v4``: adds account API. 27 * ``v5``: adds metadata and prepared transfer fields 28 29 ----------------- 30 Configuration API 31 ----------------- 32 33 This section describes the API offered by the Taler wire adapters. The API is 34 used by the exchange to trigger transactions and query incoming transactions, as 35 well as by the auditor to query incoming and outgoing transactions. 36 37 This API is currently implemented by the Taler Demo Bank, as well as by 38 LibEuFin. 39 40 .. include:: bank-wire/get-config.rst 41 42 -------------- 43 Authentication 44 -------------- 45 46 The bank library authenticates requests to the wire gateway via 47 `HTTP basic auth <https://tools.ietf.org/html/rfc7617>`_. 48 49 ------------------- 50 Making Transactions 51 ------------------- 52 53 .. include:: bank-wire/post-transfer.rst 54 55 .. include:: bank-wire/get-transfers.rst 56 57 58 .. include:: bank-wire/get-transfers-ROW_ID.rst 59 60 -------------------------------- 61 Querying the transaction history 62 -------------------------------- 63 64 The exchange's bank account is derived from the username in the 65 ``Authorization`` header and/or the request's base URL. In fact, the 66 transaction history may come from a "virtual" account, where several real bank 67 accounts are merged into a single history. 68 69 .. include:: bank-wire/get-history-incoming.rst 70 71 72 .. include:: bank-wire/get-history-outgoing.rst 73 74 75 ----------------- 76 Wire Account APIs 77 ----------------- 78 79 .. include:: bank-wire/get-account-check.rst 80 81 ----------------------- 82 Wire Transfer Test APIs 83 ----------------------- 84 85 Endpoints in this section are only used for integration tests and never 86 exposed by bank gateways in production. 87 88 .. _twg-admin-add-incoming: 89 90 .. include:: bank-wire/post-admin-add-incoming.rst 91 92 93 94 .. _twg-admin-add-kycauth: 95 96 .. include:: bank-wire/post-admin-add-kycauth.rst 97 98 .. include:: bank-wire/post-admin-add-mapped.rst 99 100 101 Security Considerations 102 ======================= 103 104 For implementors: 105 106 * The withdrawal operation ID must contain enough entropy to be unguessable. 107 108 Design: 109 110 * The user must complete the 2FA step of the withdrawal in the context of their banking 111 app or online banking Website. 112 We explicitly reject any design where the user would have to enter a confirmation code 113 they get from their bank in the context of the wallet, as this would teach and normalize 114 bad security habits.