api-corebank.rst (6932B)
1 .. 2 This file is part of GNU TALER. 3 4 Copyright (C) 2014-2025, 2026 Taler Systems SA 5 6 TALER is free software; you can redistribute it and/or modify it under the 7 terms of the GNU Affero General Public License as published by the Free Software 8 Foundation; either version 2.1, or (at your option) any later version. 9 10 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 11 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 12 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 13 14 You should have received a copy of the GNU Affero General Public License along with 15 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 16 17 .. target audience: developer, core developer 18 19 .. _corebank-api: 20 21 ==================== 22 Taler Core Bank API 23 ==================== 24 25 Introduction 26 ------------ 27 28 The Libeufin bank provides a minimal core banking system. In addition to that, 29 it provides features for local/regional currencies. 30 31 Version History 32 --------------- 33 34 The current protocol version is **v12**. 35 36 * Android cashier app is currently targeting **v9**. 37 38 **Version history:** 39 40 * ``v10``: Update two factor authentication API to match Merchant Backend API 41 * ``v11``: Add observability API 42 * ``v12``: Add wire transfer API 43 44 **Upcoming versions:** 45 46 * None anticipated. 47 48 **Ideas for future version:** 49 50 * ``vXXX``: marker for features not yet targeted for release 51 52 53 54 55 Config 56 ------ 57 58 .. include:: corebank/get-config.rst 59 60 61 62 Authentication 63 -------------- 64 65 Some endpoints requires the client to authenticate using a bearer token. Tokens can be obtained or refreshed using the ``/accounts/$USERNAME/token`` endpoint. 66 This endpoint support authentication via HTTP Basic auth (RFC 7617). When using Basic authentication, the user-id must be the bank's username, and the password the password of the corresponding user. 67 68 The user ``admin`` is a special, hard-coded username. Some requests require the client to authenticate as administrator. 69 70 .. warning:: 71 72 Since **v7** Basic authentication for endpoints other than ``/accounts/$USERNAME/token`` has been deprecated and will no longer be supported in the next release. 73 74 .. include:: corebank/post-accounts-USERNAME-token.rst 75 76 .. include:: corebank/delete-accounts-USERNAME-token.rst 77 78 .. include:: corebank/get-accounts-USERNAME-tokens.rst 79 80 .. include:: corebank/delete-accounts-USERNAME-tokens-TOKEN_ID.rst 81 82 Bank Web UI 83 ----------- 84 85 The web UI for the bank is typically served under ``/``. 86 87 88 Account Management 89 ------------------ 90 91 .. _bank-account-register: 92 93 .. include:: corebank/post-accounts.rst 94 95 .. _account-reconfig: 96 97 .. include:: corebank/patch-accounts-USERNAME.rst 98 99 100 .. _account-password-reconfig: 101 102 .. include:: corebank/patch-accounts-USERNAME-auth.rst 103 104 105 .. _delete-account: 106 107 .. include:: corebank/delete-accounts-USERNAME.rst 108 109 .. _account-list: 110 111 .. include:: corebank/get-public-accounts.rst 112 113 .. include:: corebank/get-accounts.rst 114 115 .. _bank-account-info: 116 117 .. include:: corebank/get-accounts-USERNAME.rst 118 119 Transactions 120 ------------ 121 122 .. include:: corebank/get-accounts-USERNAME-transactions.rst 123 124 .. include:: corebank/get-accounts-USERNAME-transactions-TRANSACTION_ID.rst 125 126 .. include:: corebank/post-accounts-USERNAME-transactions.rst 127 128 Account withdrawals 129 ------------------- 130 131 .. include:: corebank/post-accounts-USERNAME-withdrawals.rst 132 133 .. include:: corebank/post-accounts-USERNAME-withdrawals-WITHDRAWAL_ID-confirm.rst 134 135 .. include:: corebank/post-accounts-USERNAME-withdrawals-WITHDRAWAL_ID-abort.rst 136 137 .. include:: corebank/get-withdrawals-WITHDRAWAL_ID.rst 138 139 Cashouts 140 -------- 141 142 .. _account-cashout: 143 144 .. include:: corebank/post-accounts-USERNAME-cashouts.rst 145 146 .. _circuit-cashout-details: 147 148 .. include:: corebank/get-accounts-USERNAME-cashouts-CASHOUT_ID.rst 149 150 .. _circuit-cashouts: 151 152 .. include:: corebank/get-accounts-USERNAME-cashouts.rst 153 154 .. include:: corebank/get-cashouts.rst 155 156 Conversion rate class 157 --------------------- 158 159 .. include:: corebank/post-conversion-rate-classes.rst 160 161 .. include:: corebank/patch-conversion-rate-classes-CLASS_ID.rst 162 163 .. include:: corebank/delete-conversion-rate-classes-CLASS_ID.rst 164 165 .. include:: corebank/get-conversion-rate-classes-CLASS_ID.rst 166 167 .. include:: corebank/get-conversion-rate-classes.rst 168 169 170 Two Factor Auth 171 --------------- 172 173 202 Challenge Responses 174 ^^^^^^^^^^^^^^^^^^^^^^^ 175 176 Various APIs generate ``202 Accepted`` HTTP status codes when multi-factor 177 authentication (MFA) is required. In this case, the response will be a 178 `ChallengeResponse`. In these cases, the client must first request and solve 179 one or more challenges before repeating the request. When repeating the 180 request, they must include a list of comma-separated challenge IDs of the 181 solved challenges in an ``Taler-Challenge-Ids`` HTTP header. The body must 182 remain absolutely unchanged. 183 184 .. note:: 185 186 If all allowed attempts to solve the MFA challenge(s) fail, the endpoint 187 may start to return ``403 Forbidden`` until the issued challenges expire, 188 preventing the request from being completed for a while. In this case, 189 repeating the request with a different body may still be allowed! 190 191 .. ts:def:: ChallengeResponse 192 193 // @since v10 194 interface ChallengeResponse { 195 // List of challenge IDs that must be solved before the 196 // client may proceed. 197 challenges: Challenge[]; 198 199 // True if **all** challenges must be solved (AND), false if 200 // it is sufficient to solve one of them (OR). 201 combi_and: boolean; 202 } 203 204 .. ts:def:: Challenge 205 206 // @since v10 207 interface Challenge { 208 // Unique identifier of the challenge to solve to run this protected 209 // operation. 210 challenge_id: string; 211 212 // Channel that will be used to transmit the challenge. 213 tan_channel: TanChannel; 214 215 // Hint to show to the user as to where the challenge will be 216 // sent or what to use to solve the challenge. May not 217 // contain the full address for privacy. 218 tan_info: string; 219 } 220 221 .. ts:def:: TanChannel 222 223 enum TanChannel { 224 SMS = "sms", 225 EMAIL = "email" 226 } 227 228 Requesting challenges 229 ^^^^^^^^^^^^^^^^^^^^^ 230 231 .. include:: corebank/post-accounts-USERNAME-challenge-CHALLENGE_ID.rst 232 233 Solving challenges 234 ^^^^^^^^^^^^^^^^^^ 235 236 .. include:: corebank/post-accounts-USERNAME-challenge-CHALLENGE_ID-confirm.rst 237 238 239 Monitor 240 ------- 241 242 .. include:: corebank/get-monitor.rst 243 244 245 Endpoints for Integrated Sub-APIs 246 --------------------------------- 247 248 .. include:: corebank/any-taler-integration-star.rst 249 250 251 .. include:: corebank/any-accounts-USERNAME-taler-wire-gateway-star.rst 252 253 .. include:: corebank/any-accounts-USERNAME-taler-prepared-transfer-star.rst 254 255 .. include:: corebank/any-accounts-USERNAME-taler-revenue-star.rst 256 257 .. include:: corebank/any-accounts-USERNAME-conversion-info-star.rst 258 259 .. include:: corebank/any-conversion-rate-classes-CLASS_ID-conversion-info-star.rst 260 261 .. include:: corebank/any-conversion-info-star.rst 262 263 .. include:: corebank/any-taler-observability-star.rst