api-bank-integration.rst (10945B)
1 .. 2 This file is part of GNU TALER. 3 4 Copyright (C) 2014-2025 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 @author Marcello Stanisci 18 @author Christian Grothoff 19 20 ========================== 21 Taler Bank Integration API 22 ========================== 23 24 This chapter describe the APIs that banks need to offer towards Taler wallets 25 to tightly integrate with GNU Taler. 26 27 .. contents:: Table of Contents 28 29 .. http:get:: /config 30 31 Return the protocol version and configuration information about the bank. 32 This specification corresponds to ``current`` protocol being **v5**. 33 34 **Response:** 35 36 :http:statuscode:`200 OK`: 37 The exchange responds with a `IntegrationConfig` object. This request should 38 virtually always be successful. 39 40 **Details:** 41 42 .. ts:def:: IntegrationConfig 43 44 interface IntegrationConfig { 45 // Name of the API. 46 name: "taler-bank-integration"; 47 48 // libtool-style representation of the Bank protocol version, see 49 // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning 50 // 51 // The format is "current:revision:age". 52 version: string; 53 54 // URN of the implementation (needed to interpret 'revision' in version). 55 // @since **v2**, may become mandatory in the future. 56 implementation?: string; 57 58 // Currency used by this bank. 59 currency: string; 60 61 // How the bank SPA should render this currency. 62 currency_specification: CurrencySpecification; 63 } 64 65 66 .. _wallet-wopid-withdrawing: 67 68 ----------- 69 Withdrawing 70 ----------- 71 72 Withdrawals with a Taler-integrated bank are based on withdrawal operations. 73 Some user interaction (on the bank's websitei) creates a 74 withdrawal operation record in the bank's database. The wallet can use a unique identifier 75 for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdrawal operation. 76 77 .. http:get:: /withdrawal-operation/$WITHDRAWAL_ID 78 79 Query information about a withdrawal operation, identified by the ``WITHDRAWAL_ID``. 80 81 **Request:** 82 83 :query timeout_ms: *Optional.* 84 Timeout in milliseconds, for :ref:`long-polling <long-polling>`, to wait for operation state to be different from ``old_state``. Since protocol **v3**. 85 :query old_state: 86 *Optional.* Defaults to "pending". 87 :query long_poll_ms: *Optional.* 88 Deprecated in protocol **v3**. Use *timeout_ms* instead. 89 90 **Response:** 91 92 :http:statuscode:`200 OK`: 93 The withdrawal operation is known to the bank, and details are given 94 in the `BankWithdrawalOperationStatus` response body. 95 :http:statuscode:`404 Not found`: 96 The operation was not found. 97 98 **Details:** 99 100 .. ts:def:: BankWithdrawalOperationStatus 101 102 interface BankWithdrawalOperationStatus { 103 // Current status of the operation 104 // pending: the operation is pending parameters selection (exchange and reserve public key) 105 // selected: the operations has been selected and is pending confirmation 106 // aborted: the operation has been aborted 107 // confirmed: the transfer has been confirmed and registered by the bank 108 // @since **v1** 109 status: "pending" | "selected" | "aborted" | "confirmed"; 110 111 // Currency used for the withdrawal. 112 // MUST be present when amount is absent. 113 // @since **v2**, may become mandatory in the future. 114 currency?: string; 115 116 // Amount that will be withdrawn with this operation 117 // (raw amount without fee considerations). Only 118 // given once the amount is fixed and cannot be changed. 119 // Optional since **v4**. 120 amount?: Amount; 121 122 // Suggestion for the amount to be withdrawn with this 123 // operation. Given if a suggestion was made but the 124 // user may still change the amount. 125 // Optional since **v4**. 126 suggested_amount?: Amount; 127 128 // Minimum amount that the wallet can choose to withdraw. 129 // Only applicable when the amount is not fixed. 130 // @since **v4**. 131 min_amount?: Amount; 132 133 // Maximum amount that the wallet can choose to withdraw. 134 // Only applicable when the amount is not fixed. 135 // @since **v4**. 136 max_amount?: Amount; 137 138 // The non-Taler card fees the customer will have 139 // to pay to the bank / payment service provider 140 // they are using to make the withdrawal in addition 141 // to the amount. 142 // @since **v4** 143 card_fees?: Amount; 144 145 // Bank account of the customer that is debiting, as a 146 // full RFC 8905 ``payto`` URI. 147 sender_wire?: string; 148 149 // Base URL of the suggested exchange. The bank may have 150 // neither a suggestion nor a requirement for the exchange. 151 // This value is typically set in the bank's configuration. 152 suggested_exchange?: string; 153 154 // Base URL of an exchange that must be used. Optional, 155 // not given *unless* a particular exchange is mandatory. 156 // This value is typically set in the bank's configuration. 157 // @since **v4** 158 required_exchange?: string; 159 160 // URL that the user needs to navigate to in order to 161 // complete some final confirmation (e.g. 2FA). 162 // Only applicable when ``status`` is ``selected`` or ``pending``. 163 // It may contain the withdrawal operation id. 164 confirm_transfer_url?: string; 165 166 // Wire transfer types supported by the bank. 167 wire_types: string[]; 168 169 // Reserve public key selected by the exchange, 170 // only non-null if ``status`` is ``selected`` or ``confirmed``. 171 // @since **v1** 172 selected_reserve_pub?: EddsaPublicKey; 173 174 // Exchange account selected by the wallet; 175 // only non-null if ``status`` is ``selected`` or ``confirmed``. 176 // @since **v1** 177 selected_exchange_account?: string; 178 179 // If true, tells the wallet not to allow the user to 180 // specify an amount to withdraw and to not provide 181 // any amount when registering with the withdrawal 182 // operation. The amount to withdraw will be set 183 // by the final ``/withdrawals/$WITHDRAWAL_ID/confirm`` step. 184 // @since **v5** 185 no_amount_to_wallet?: boolean; 186 187 // @deprecated since **v1**, use ``status`` instead 188 // Indicates whether the withdrawal was aborted. 189 aborted: boolean; 190 191 // @deprecated since **v1**, use ``status`` instead 192 // Has the wallet selected parameters for the withdrawal operation 193 // (exchange and reserve public key) and successfully sent it 194 // to the bank? 195 selection_done: boolean; 196 197 // @deprecated since **v1**, use ``status`` instead 198 // The transfer has been confirmed and registered by the bank. 199 // Does not guarantee that the funds have arrived at the exchange already. 200 transfer_done: boolean; 201 } 202 203 204 .. http:post:: /withdrawal-operation/$WITHDRAWAL_ID 205 206 This endpoint is used by the GNU Taler wallet to supply additional 207 details needed to complete a withdraw operation. 208 209 **Request:** 210 211 .. ts:def:: BankWithdrawalOperationPostRequest 212 213 interface BankWithdrawalOperationPostRequest { 214 215 // Reserve public key that should become the wire transfer 216 // subject to fund the withdrawal. 217 reserve_pub: EddsaPublicKey; 218 219 // Full RFC 8905 (payto) address of the exchange account to be 220 // credited for the withdrawal. 221 selected_exchange: string; 222 223 // Selected amount to be transferred. Optional if the 224 // backend already knows the amount. 225 // @since **v4** 226 amount?: Amount; 227 } 228 229 **Response:** 230 231 :http:statuscode:`200 OK`: 232 The bank has accepted the withdrawal operation parameters chosen by the wallet. 233 The response is a `BankWithdrawalOperationPostResponse`. 234 :http:statuscode:`404 Not found`: 235 The bank does not know about a withdrawal operation with the specified ``WITHDRAWAL_ID``. 236 :http:statuscode:`409 Conflict`: 237 * ``TALER_EC_BANK_UPDATE_ABORT_CONFLICT`` : the withdrawal has been aborted previously and can't be modified. 238 * ``TALER_EC_BANK_WITHDRAWAL_OPERATION_RESERVE_SELECTION_CONFLICT``: 239 The wallet selected a different exchange or reserve public key under the same withdrawal ID. 240 * ``TALER_EC_BANK_DUPLICATE_RESERVE_PUB_SUBJECT``: the reserve public key is already used. 241 * ``TALER_EC_BANK_UNKNOWN_ACCOUNT``: the selected exchange account was not found. 242 * ``TALER_EC_BANK_ACCOUNT_IS_NOT_EXCHANGE``: the selected account is not an exchange. 243 * ``TALER_EC_BANK_AMOUNT_DIFFERS`` : the specified amount will not work for this 244 withdrawal (since **v4**). 245 * ``TALER_EC_BANK_UNALLOWED_DEBIT`` : the account does not have sufficient funds or the amount is too low or too high (since **v4**). 246 247 **Details:** 248 249 .. ts:def:: BankWithdrawalOperationPostResponse 250 251 interface BankWithdrawalOperationPostResponse { 252 // Current status of the operation 253 // pending: the operation is pending parameters selection (exchange and reserve public key) 254 // selected: the operations has been selected and is pending confirmation 255 // aborted: the operation has been aborted 256 // confirmed: the transfer has been confirmed and registered by the bank 257 status: "selected" | "aborted" | "confirmed"; 258 259 // URL that the user needs to navigate to in order to 260 // complete some final confirmation (e.g. 2FA). 261 // 262 // Only applicable when ``status`` is ``selected`` or ``pending``. 263 // It may contain withdrawal operation id 264 confirm_transfer_url?: string; 265 266 // @deprecated since **v1**, use ``status`` instead 267 // The transfer has been confirmed and registered by the bank. 268 // Does not guarantee that the funds have arrived at the exchange already. 269 transfer_done: boolean; 270 } 271 272 273 .. http:post:: /withdrawal-operation/$WITHDRAWAL_ID/abort 274 275 Aborts ``WITHDRAWAL_ID`` operation. Has no effect on an already aborted 276 operation. This endpoint can be used by the wallet if the user aborts 277 the transaction, ensuring that the operation is also aborted at the 278 bank. 279 280 Since protocol **v2**. 281 282 **Request:** 283 284 The request body is empty. 285 286 **Response:** 287 288 :http:statuscode:`204 No content`: 289 The withdrawal operation has been aborted. 290 :http:statuscode:`404 Not found`: 291 The withdrawal operation was not found. 292 :http:statuscode:`409 Conflict`: 293 The withdrawal operation has been confirmed previously and 294 can't be aborted.