api-corebank.rst (7499B)
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 3.0, 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. The v12 contract also clarifies account 43 contact removal, token refresh rotation, TAN challenge terminal states, 44 cashout idempotency and anonymous histories for public accounts. These are 45 corrections to v12 behavior and do not introduce a new protocol version. 46 47 **Upcoming versions:** 48 49 * None anticipated. 50 51 **Ideas for future version:** 52 53 * ``vXXX``: marker for features not yet targeted for release 54 55 56 57 58 Config 59 ------ 60 61 .. include:: corebank/get-config.rst 62 63 64 65 Authentication 66 -------------- 67 68 Some endpoints require the client to authenticate using a bearer token. Tokens can be obtained or refreshed using the :http:post:`/accounts/$USERNAME/token </accounts/$USERNAME/token>` endpoint. 69 This endpoint supports 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. 70 71 Refreshing a token rotates credentials instead of extending the presented 72 credential indefinitely. See the token endpoint for the fixed overlap period 73 and retry behavior. Clients must store the replacement before discarding the 74 source token. 75 76 The user ``admin`` is a special, hard-coded username. Some requests require the client to authenticate as administrator. 77 78 .. warning:: 79 80 Since **v7** Basic authentication for endpoints other than :http:post:`/accounts/$USERNAME/token </accounts/$USERNAME/token>` has been deprecated and will no longer be supported in the next release. 81 82 .. include:: corebank/post-accounts-USERNAME-token.rst 83 84 .. include:: corebank/delete-accounts-USERNAME-token.rst 85 86 .. include:: corebank/get-accounts-USERNAME-tokens.rst 87 88 .. include:: corebank/delete-accounts-USERNAME-tokens-TOKEN_ID.rst 89 90 Bank Web UI 91 ----------- 92 93 The web UI for the bank is typically served under ``/``. 94 95 96 Account Management 97 ------------------ 98 99 .. _bank-account-register: 100 101 .. include:: corebank/post-accounts.rst 102 103 .. _account-reconfig: 104 105 .. include:: corebank/patch-accounts-USERNAME.rst 106 107 108 .. _account-password-reconfig: 109 110 .. include:: corebank/patch-accounts-USERNAME-auth.rst 111 112 113 .. _delete-account: 114 115 .. include:: corebank/delete-accounts-USERNAME.rst 116 117 .. _account-list: 118 119 .. include:: corebank/get-public-accounts.rst 120 121 .. include:: corebank/get-accounts.rst 122 123 .. _bank-account-info: 124 125 .. include:: corebank/get-accounts-USERNAME.rst 126 127 Transactions 128 ------------ 129 130 .. include:: corebank/get-accounts-USERNAME-transactions.rst 131 132 .. include:: corebank/get-accounts-USERNAME-transactions-TRANSACTION_ID.rst 133 134 .. include:: corebank/post-accounts-USERNAME-transactions.rst 135 136 Account withdrawals 137 ------------------- 138 139 .. include:: corebank/post-accounts-USERNAME-withdrawals.rst 140 141 .. include:: corebank/post-accounts-USERNAME-withdrawals-WITHDRAWAL_ID-confirm.rst 142 143 .. include:: corebank/post-accounts-USERNAME-withdrawals-WITHDRAWAL_ID-abort.rst 144 145 .. include:: corebank/get-withdrawals-WITHDRAWAL_ID.rst 146 147 Cashouts 148 -------- 149 150 .. _account-cashout: 151 152 .. include:: corebank/post-accounts-USERNAME-cashouts.rst 153 154 .. _circuit-cashout-details: 155 156 .. include:: corebank/get-accounts-USERNAME-cashouts-CASHOUT_ID.rst 157 158 .. _circuit-cashouts: 159 160 .. include:: corebank/get-accounts-USERNAME-cashouts.rst 161 162 .. include:: corebank/get-cashouts.rst 163 164 Conversion rate class 165 --------------------- 166 167 .. include:: corebank/post-conversion-rate-classes.rst 168 169 .. include:: corebank/patch-conversion-rate-classes-CLASS_ID.rst 170 171 .. include:: corebank/delete-conversion-rate-classes-CLASS_ID.rst 172 173 .. include:: corebank/get-conversion-rate-classes-CLASS_ID.rst 174 175 .. include:: corebank/get-conversion-rate-classes.rst 176 177 178 Two Factor Auth 179 --------------- 180 181 202 Challenge Responses 182 ^^^^^^^^^^^^^^^^^^^^^^^ 183 184 Various APIs generate ``202 Accepted`` HTTP status codes when multi-factor 185 authentication (MFA) is required. In this case, the response will be a 186 `ChallengeResponse`. In these cases, the client must first request and solve 187 one or more challenges before repeating the request. When repeating the 188 request, they must include a list of comma-separated challenge IDs of the 189 solved challenges in a ``Taler-Challenge-Ids`` HTTP header. The body must 190 remain absolutely unchanged. 191 192 .. note:: 193 194 If all allowed attempts to solve the MFA challenge(s) fail, the endpoint 195 may start to return ``403 Forbidden`` until the issued challenges expire, 196 preventing the request from being completed for a while. In this case, 197 repeating the request with a different body may still be allowed! 198 199 .. ts:def:: ChallengeResponse 200 201 // @since v10 202 interface ChallengeResponse { 203 // List of challenge IDs that must be solved before the 204 // client may proceed. 205 challenges: Challenge[]; 206 207 // True if **all** challenges must be solved (AND), false if 208 // it is sufficient to solve one of them (OR). 209 combi_and: boolean; 210 } 211 212 .. ts:def:: Challenge 213 214 // @since v10 215 interface Challenge { 216 // Unique identifier of the challenge to solve to run this protected 217 // operation. 218 challenge_id: Slug; 219 220 // Channel that will be used to transmit the challenge. 221 tan_channel: TanChannel; 222 223 // Hint to show to the user as to where the challenge will be 224 // sent or what to use to solve the challenge. May not 225 // contain the full address for privacy. 226 tan_info: string; 227 } 228 229 .. ts:def:: TanChannel 230 231 enum TanChannel { 232 SMS = "sms", 233 EMAIL = "email" 234 } 235 236 Requesting challenges 237 ^^^^^^^^^^^^^^^^^^^^^ 238 239 .. include:: corebank/post-accounts-USERNAME-challenge-CHALLENGE_ID.rst 240 241 Solving challenges 242 ^^^^^^^^^^^^^^^^^^ 243 244 .. include:: corebank/post-accounts-USERNAME-challenge-CHALLENGE_ID-confirm.rst 245 246 247 Monitor 248 ------- 249 250 .. include:: corebank/get-monitor.rst 251 252 253 Endpoints for Integrated Sub-APIs 254 --------------------------------- 255 256 .. include:: corebank/any-taler-integration-star.rst 257 258 259 .. include:: corebank/any-accounts-USERNAME-taler-wire-gateway-star.rst 260 261 .. include:: corebank/any-taler-prepared-transfer-star.rst 262 263 .. include:: corebank/any-accounts-USERNAME-taler-revenue-star.rst 264 265 .. include:: corebank/any-accounts-USERNAME-conversion-info-star.rst 266 267 .. include:: corebank/any-conversion-rate-classes-CLASS_ID-conversion-info-star.rst 268 269 .. include:: corebank/any-conversion-info-star.rst 270 271 .. include:: corebank/any-taler-observability-star.rst