api-terminal.rst (10911B)
1 .. 2 This file is part of GNU TALER. 3 4 Copyright (C) 2024 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 .. _terminal-api: 20 21 ============ 22 Terminal API 23 ============ 24 25 26 Introduction 27 ------------ 28 29 Terminals are devices where users can withdraw digital cash. 30 31 This API is offered by a payment service backend and is used by such 32 terminals. It enables imposing limits on withdrawals per unique user ID (and 33 communicating such limits to the terminals) as well as setting up and 34 triggering withdrawal operations. 35 36 Implementations of this API typically interact with a terminal-specific 37 payment service (or a bank) to realize the service. 38 39 40 Authentication 41 -------------- 42 43 Terminals must authenticate against all terminal API using basic auth according to `HTTP basic auth <https://tools.ietf.org/html/rfc7617>`_. 44 45 46 Config 47 ------ 48 49 .. http:get:: /config 50 51 Return the protocol version and configuration information about the bank. 52 This specification corresponds to ``current`` protocol being version **0**. 53 54 **Response:** 55 56 :http:statuscode:`200 OK`: 57 Response is a `TerminalConfig`. 58 59 **Details:** 60 61 .. ts:def:: TerminalConfig 62 63 interface TerminalConfig { 64 // Name of the API. 65 name: "taler-terminal"; 66 67 // libtool-style representation of the Bank protocol version, see 68 // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning 69 // The format is "current:revision:age". 70 version: string; 71 72 // Terminal provider display name to be used in user interfaces. 73 provider_name: string; 74 75 // The currency supported by this Terminal-API 76 // must be the same as the currency specified 77 // in the currency field of the wire gateway config 78 currency: string; 79 80 // The withdrawal fees which of this Terminals API endpoint. 81 // If the Exchange chooses to charge no fees, then just configure 82 // the zero amount. 83 withdrawal_fees: Amount; 84 85 // Wire transfer type supported by the terminal. 86 // FIXME: needed? 87 wire_type: string; 88 } 89 90 91 .. http:get:: /quotas/$UUID 92 93 Obtain the current transaction limit for the given $UUID. 94 The UUID should be an encoding of a unique identifier of 95 the user. 96 97 **Response:** 98 99 :http:statuscode:`200 OK`: 100 Response is a `WithdrawLimit`. 101 102 **Details:** 103 104 .. ts:def:: WithdrawLimit 105 106 interface WithdrawLimit { 107 // Maximum amount that can be withdrawn now. 108 limit: Amount; 109 110 // Time when the limit may increase. 111 expiration: Timestamp; 112 } 113 114 115 .. http:post:: /quotas/$UUID/lock 116 117 This endpoint allows a terminal to reserve a given amount 118 from the user's quota, ensuring that a subsequent operation 119 will not fail due to a quota violation. 120 121 **Request:** 122 123 The request should be a `WithdrawLimitLock`. 124 125 **Response:** 126 127 :http:statuscode:`204 No content`: 128 The change was accepted. 129 :http:statuscode:`409 Conflict`: 130 The proposed lock would push the user above the limit. 131 132 **Details:** 133 134 .. ts:def:: WithdrawLimitLock 135 136 interface WithdrawLimitLock { 137 138 // Amount that should be reserved from the quota. 139 limit: Amount; 140 141 // ID for the lock. FIXME: could also be 32-byte nonce? 142 lock: string; 143 144 // How long should the lock be held? 145 expiration: Timestamp; 146 } 147 148 .. http:delete:: /quotas/$UUID/lock/$LOCK 149 150 This endpoint allows the terminal to clear a lock it may have 151 previously created. 152 153 **Response:** 154 155 :http:statuscode:`204 No content`: 156 The lock was cleared. 157 :http:statuscode:`404 Not found`: 158 The lock is unknown. 159 :http:statuscode:`409 Conflict`: 160 The lock was already used in a withdrawal operation. 161 162 163 .. http:post:: /withdrawals 164 165 This endpoint allows the terminal to set up a new withdrawal 166 operation. 167 168 **Request:** 169 170 The request should be a `TerminalWithdrawalSetup`. 171 172 **Response:** 173 174 :http:statuscode:`200 Ok`: 175 The operation was created. The response will be 176 a `TerminalWithdrawalSetupResponse`. 177 :http:statuscode:`404 Not found`: 178 A lock was specified but the lock is not known for 179 the given user. 180 :http:statuscode:`409 Conflict`: 181 A conflicting withdrawal operation already exists or 182 the amount would violate the quota for the specified user. 183 184 **Details:** 185 186 .. ts:def:: TerminalWithdrawalSetup 187 188 interface TerminalWithdrawalSetup { 189 190 // Amount to withdraw. If given, the wallet 191 // cannot change the amount! 192 amount?: Amount; 193 194 // Suggested amount to withdraw. If given, the wallet can 195 // still change the suggestion. 196 suggested_amount?: Amount; 197 198 // A provider-specific transaction identifier. 199 // This identifier may be used to attest the 200 // payment at the provider's backend. Optional, 201 // as we may not know it at this time. 202 provider_transaction_id?: string; 203 204 // The non-Taler fees the customer will have 205 // to pay to the service provider 206 // they are using to make this withdrawal. 207 // If the fees cannot be precalculated, 208 // they can be specified in the /withdrawals/$WITHDRAWAL_ID/check 209 // request after the transaction was executed. 210 terminal_fees?: Amount; 211 212 // Unique request ID to make retried requests idempotent. 213 request_uid: string; 214 215 // Unique user ID of the user. Optional 216 // in case a user Id is not (yet) known. 217 user_uuid?: string; 218 219 // ID identifying a lock on the quota that the client 220 // may wish to use in this operation. May only be 221 // present if ``user_uuid`` is also given. 222 lock?: string; 223 } 224 225 .. ts:def:: TerminalWithdrawalSetupResponse 226 227 interface TerminalWithdrawalSetupResponse { 228 229 // ID identifying the withdrawal operation being created. 230 withdrawal_id: string; 231 } 232 233 234 .. http:post:: /withdrawals/$WITHDRAWAL_ID/check 235 236 Endpoint for providers to notify the terminal backend about a payment having 237 happened. This will cause the bank to validate the transaction and allow 238 the withdrawal to proceed. The API is idempotent, meaning sending a payment 239 notification for the same ``WITHDRAWAL_ID`` return successfuly but not 240 change anything. This endpoint is always *optional*: the bank, exchange and 241 wallet should all eventually notice the wire transfer with or without this 242 endpoint being called. However, by calling this endpoint checks that might 243 otherwise only happen periodically can be triggered immediately. 244 245 The endpoint may also be used to associate a user ID at a very late stage 246 with the withdrawal --- and still get an immediate failure if we are above 247 the quota. 248 249 .. note:: 250 251 The backend shall **never** just accept this claim that the payment was 252 confirmed, but instead needs to internally attest that the payment was 253 successful using provider-specific transaction validation logic! The point 254 of this endpoint is merely to trigger this validation **now**. 255 256 **Request:** 257 258 The body of the request must be a `TerminalWithdrawalConfirmationRequest`. 259 260 **Response:** 261 262 :http:statuscode:`204 No content`: 263 The payment notification was processed successfully. 264 :http:statuscode:`404 Not found`: 265 The withdrawal operation was not found. 266 :http:statuscode:`409 Conflict`: 267 The withdrawal operation has been previously aborted 268 and cannot be confirmed anymore. 269 :http:statuscode:`451 Unavailable for Legal Reasons`: 270 The withdrawal operation cannot be confirmed because 271 it would put the user above the legal limit. The 272 payment service will eventually bounce the transfer 273 (if it were to become effective), but the user should 274 already be shown an error. 275 276 **Details:** 277 278 .. ts:def:: TerminalWithdrawalConfirmationRequest 279 280 interface TerminalWithdrawalConfirmationRequest { 281 282 // A provider-specific transaction identifier. 283 // This identifier may be used to facilitate the 284 // backend to check that the credit was confirmed. 285 provider_transaction_id?: string; 286 287 // The fees which the customer had to pay to the 288 // provider 289 terminal_fees?: Amount; 290 291 // A user-specific identifier for quota checks. 292 user_uuid?: string; 293 294 // ID identifying a lock on the quota that the client 295 // may wish to use in this operation. May only be 296 // present if ``user_uuid`` is also given. 297 lock?: string; 298 } 299 300 .. http:get:: /withdrawals/$WITHDRAWAL_ID 301 302 Query information about a withdrawal, identified by the ``WITHDRAWAL_ID``. 303 304 **Request:** 305 306 :query long_poll_ms: 307 *Optional.* If specified, the bank will wait up to ``long_poll_ms`` 308 milliseconds for operationt state to be different from ``old_state`` before sending the HTTP 309 response. A client must never rely on this behavior, as the bank may 310 return a response immediately. 311 :query old_state: 312 *Optional.* Defaults to "pending". 313 314 **Response:** 315 316 :http:statuscode:`200 OK`: 317 The withdrawal operation is known to the bank, and details are given 318 in the `BankWithdrawalOperationStatus` response body. 319 :http:statuscode:`404 Not found`: 320 The operation was not found. 321 322 .. http:delete:: /withdrawals/$WITHDRAWAL_ID/abort 323 324 Aborts ``WITHDRAWAL_ID`` operation. Has no effect on an already aborted 325 operation. This endpoint can be used by the terminal if the terminal aborts 326 the transaction, ensuring that the operation is also aborted at the 327 bank. 328 329 **Request:** 330 331 The request body is empty. 332 333 **Response:** 334 335 :http:statuscode:`204 No content`: 336 The withdrawal operation has been aborted. 337 :http:statuscode:`404 Not found`: 338 The withdrawal operation was not found. 339 :http:statuscode:`409 Conflict`: 340 The withdrawal operation has been confirmed previously and 341 can't be aborted. 342 343 344 Endpoints for Integrated Sub-APIs 345 --------------------------------- 346 347 .. http:any:: /taler-integration/* 348 349 All endpoints under this prefix are specified by the. 350 :doc:`GNU Taler bank integration API </core/api-bank-integration>`. 351 This API handles the communication with Taler wallets. 352 353 354 .. http:any:: /taler-wire-gateway/* 355 356 All endpoints under this prefix are specified 357 by the :doc:`GNU Taler wire gateway API </core/api-bank-wire>`. 358 359 The endpoints are only available for accounts configured with ``is_taler_exchange=true``.