api-c2ec.rst (11738B)
1 .. 2 This file is part of GNU TALER. 3 4 Copyright (C) 2014-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 @author Joel Häberli 18 19 =========================== 20 The C2EC RESTful API 21 =========================== 22 23 .. note:: 24 25 **This API is experimental and not yet implemented** 26 27 This chapter describe the APIs that third party providers need to integrate to allow 28 withdrawals through indirect payment channels like credit cards or ATM. 29 30 .. contents:: Table of Contents 31 32 -------------- 33 Authentication 34 -------------- 35 36 Terminals which authenticate against the C2EC API must provide their respective 37 access token. Therefore they provide a ``Authorization: Bearer $ACCESS_TOKEN`` header, 38 where `$ACCESS_TOKEN`` is a secret authentication token configured by the exchange and 39 must begin with the RFC 8959 prefix. 40 41 ---------------------------- 42 Configuration of C2EC 43 ---------------------------- 44 45 .. http:get:: /config 46 47 Return the protocol version and configuration information about the C2EC API. 48 49 **Response:** 50 51 :http:statuscode:`200 OK`: 52 The exchange responds with a `C2ECConfig` object. This request should 53 virtually always be successful. 54 55 **Details:** 56 57 .. ts:def:: C2ECConfig 58 59 interface C2ECConfig { 60 // Name of the API. 61 name: "taler-c2ec"; 62 63 // libtool-style representation of the C2EC protocol version, see 64 // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning 65 // The format is "current:revision:age". 66 version: string; 67 } 68 69 ----------------------------- 70 Withdrawing using C2EC 71 ----------------------------- 72 73 Withdrawals with a C2EC are based on withdrawal operations which register a withdrawal identifier 74 (nonce) at the C2EC component. The provider must first create a unique identifier for the withdrawal 75 operation (the ``WOPID``) to interact with the withdrawal operation and eventually withdraw using the wallet. 76 77 .. http:post:: /withdrawal-operation 78 79 Register a `WOPID` belonging to a reserve public key. 80 81 **Request:** 82 83 .. ts:def:: C2ECWithdrawRegistration 84 85 interface C2ECWithdrawRegistration { 86 // Maps a nonce generated by the provider to a reserve public key generated by the wallet. 87 wopid: ShortHashCode; 88 89 // Reserve public key generated by the wallet. 90 // According to TALER_ReservePublicKeyP (https://docs.taler.net/core/api-common.html#cryptographic-primitives) 91 reserve_pub_key: EddsaPublicKey; 92 93 // Optional amount for the withdrawal. 94 amount?: Amount; 95 96 // Id of the terminal of the provider requesting a withdrawal by nonce. 97 // Assigned by the exchange. 98 terminal_id: SafeUint64; 99 } 100 101 **Response:** 102 103 :http:statuscode:`204 No content`: 104 The withdrawal was successfully registered. 105 :http:statuscode:`400 Bad request`: 106 The ``WithdrawRegistration`` request was malformed or contained invalid parameters. 107 :http:statuscode:`500 Internal Server error`: 108 The registration of the withdrawal failed due to server side issues. 109 110 .. http:get:: /withdrawal-operation/$WOPID 111 112 Query information about a withdrawal operation, identified by the ``WOPID``. 113 114 **Request:** 115 116 :query long_poll_ms: 117 *Optional.* If specified, the bank will wait up to ``long_poll_ms`` 118 milliseconds for operationt state to be different from ``old_state`` before sending the HTTP 119 response. A client must never rely on this behavior, as the bank may 120 return a response immediately. 121 :query old_state: 122 *Optional.* Default to "pending". 123 124 **Response:** 125 126 :http:statuscode:`200 Ok`: 127 The withdrawal was found and is returned in the response body as ``C2ECWithdrawalStatus``. 128 :http:statuscode:`404 Not found`: 129 C2EC does not have a withdrawal registered with the specified ``WOPID``. 130 131 **Details** 132 133 .. ts:def:: C2ECWithdrawalStatus 134 135 interface C2ECWithdrawalStatus { 136 // Current status of the operation 137 // pending: the operation is pending parameters selection (exchange and reserve public key) 138 // selected: the operations has been selected and is pending confirmation 139 // aborted: the operation has been aborted 140 // confirmed: the transfer has been confirmed and registered by the bank 141 // Since protocol v1. 142 status: "pending" | "selected" | "aborted" | "confirmed"; 143 144 // Amount that will be withdrawn with this operation 145 // (raw amount without fee considerations). 146 amount: Amount; 147 148 // A refund address as ``payto`` URI. This address shall be used 149 // in case a refund must be done. Only not-null if the status 150 // is "confirmed" or "aborted" 151 sender_wire?: string; 152 153 // Reserve public key selected by the exchange, 154 // only non-null if ``status`` is ``selected`` or ``confirmed``. 155 // Since protocol v1. 156 selected_reserve_pub?: string; 157 } 158 159 160 .. http:post:: /withdrawal-operation/$WOPID 161 162 Notifies C2EC about an executed payment for a specific withdrawal. 163 164 **Request:** 165 166 .. ts:def:: C2ECPaymentNotification 167 168 interface C2ECPaymentNotification { 169 170 // Unique identifier of the provider transaction. 171 provider_transaction_id: string; 172 173 // Specifies the amount which was payed to the provider (without fees). 174 // This amount shall be put into the reserve linked to by the withdrawal id. 175 amount: Amount; 176 177 // Fees associated with the payment. 178 fees: Amount; 179 } 180 181 **Response:** 182 183 :http:statuscode:`204 No content`: 184 C2EC received the ``C2ECPaymentNotification`` successfully and will further process 185 the withdrawal. 186 :http:statuscode:`400 Bad request`: 187 The ``C2ECPaymentNotification`` request was malformed or contained invalid parameters. 188 :http:statuscode:`404 Not found`: 189 C2EC does not have a withdrawal registered with the specified ``WOPID``. 190 :http:statuscode:`500 Internal Server error`: 191 The ``C2ECPaymentNotification`` could not be processed due to server side issues. 192 193 194 -------------- 195 Taler Wire Gateway 196 -------------- 197 198 C2EC implements the wire gateway API in order to check for incoming transactions and 199 let the exchange get proofs of payments. This will allow the C2EC componente to add reserves 200 and therefore allow the withdrawal of the money. C2EC does not entirely implement all endpoints, 201 because the it is not needed for the case of C2EC. The endpoints not implemented are not described 202 further. They will be available but respond with 400 http error code. 203 204 .. http:get:: /config 205 206 Return the protocol version and configuration information about the bank. 207 This specification corresponds to ``current`` protocol being version **0**. 208 209 **Response:** 210 211 :http:statuscode:`200 OK`: 212 The exchange responds with a `WireConfig` object. This request should 213 virtually always be successful. 214 215 **Details:** 216 217 .. ts:def:: WireConfig 218 219 interface WireConfig { 220 // Name of the API. 221 name: "taler-wire-gateway"; 222 223 // libtool-style representation of the Bank protocol version, see 224 // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning 225 // The format is "current:revision:age". 226 version: string; 227 228 // Currency used by this gateway. 229 currency: string; 230 231 // URN of the implementation (needed to interpret 'revision' in version). 232 // @since v0, may become mandatory in the future. 233 implementation?: string; 234 } 235 236 .. http:post:: /transfer 237 238 This API allows the exchange to make a transaction, typically to a merchant. The bank account 239 of the exchange is not included in the request, but instead derived from the user name in the 240 authentication header and/or the request base URL. 241 242 To make the API idempotent, the client must include a nonce. Requests with the same nonce 243 are rejected unless the request is the same. 244 245 **Request:** 246 247 .. ts:def:: TransferRequest 248 249 interface TransferRequest { 250 // Nonce to make the request idempotent. Requests with the same 251 // ``request_uid`` that differ in any of the other fields 252 // are rejected. 253 request_uid: HashCode; 254 255 // Amount to transfer. 256 amount: Amount; 257 258 // Base URL of the exchange. Shall be included by the bank gateway 259 // in the appropriate section of the wire transfer details. 260 exchange_base_url: string; 261 262 // Wire transfer identifier chosen by the exchange, 263 // used by the merchant to identify the Taler order(s) 264 // associated with this wire transfer. 265 wtid: ShortHashCode; 266 267 // The recipient's account identifier as a payto URI. 268 credit_account: string; 269 } 270 271 **Response:** 272 273 :http:statuscode:`200 OK`: 274 The request has been correctly handled, so the funds have been transferred to 275 the recipient's account. The body is a `TransferResponse`. 276 :http:statuscode:`400 Bad request`: 277 Request malformed. The bank replies with an `ErrorDetail` object. 278 :http:statuscode:`401 Unauthorized`: 279 Authentication failed, likely the credentials are wrong. 280 :http:statuscode:`404 Not found`: 281 The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object. 282 :http:statuscode:`409 Conflict`: 283 A transaction with the same ``request_uid`` but different transaction details 284 has been submitted before. 285 286 **Details:** 287 288 .. ts:def:: TransferResponse 289 290 interface TransferResponse { 291 // Timestamp that indicates when the wire transfer will be executed. 292 // In cases where the wire transfer gateway is unable to know when 293 // the wire transfer will be executed, the time at which the request 294 // has been received and stored will be returned. 295 // The purpose of this field is for debugging (humans trying to find 296 // the transaction) as well as for taxation (determining which 297 // time period a transaction belongs to). 298 timestamp: Timestamp; 299 300 // Opaque ID of the transaction that the bank has made. 301 row_id: SafeUint64; 302 } 303 304 .. http:get:: /history/incoming 305 306 **Request:** 307 308 :query start: *Optional.* 309 Row identifier to explicitly set the *starting point* of the query. 310 :query delta: 311 The *delta* value that determines the range of the query. 312 :query long_poll_ms: *Optional.* If this parameter is specified and the 313 result of the query would be empty, the bank will wait up to ``long_poll_ms`` 314 milliseconds for new transactions that match the query to arrive and only 315 then send the HTTP response. A client must never rely on this behavior, as 316 the bank may return a response immediately or after waiting only a fraction 317 of ``long_poll_ms``. 318 319 **Response:** 320 321 .. ts:def:: IncomingReserveTransaction 322 323 interface IncomingReserveTransaction { 324 type: "RESERVE"; 325 326 // Opaque identifier of the returned record. 327 row_id: SafeUint64; 328 329 // Date of the transaction. 330 date: Timestamp; 331 332 // Amount transferred. 333 amount: Amount; 334 335 // Payto URI to identify the sender of funds. 336 debit_account: string; 337 338 // The reserve public key extracted from the transaction details. 339 reserve_pub: EddsaPublicKey; 340 341 } 342