get-private-orders-ORDER_ID.h (15533B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2014-2026 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Lesser General Public License as published by the Free Software 7 Foundation; either version 2.1, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. 12 13 You should have received a copy of the GNU Lesser General Public License along with 14 TALER; see the file COPYING.LGPL. If not, see 15 <http://www.gnu.org/licenses/> 16 */ 17 /** 18 * @file include/taler/taler-merchant/get-private-orders-ORDER_ID.h 19 * @brief C interface for the GET /private/orders/$ORDER_ID endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__GET_PRIVATE_ORDERS_ORDER_ID_H 23 #define _TALER_MERCHANT__GET_PRIVATE_ORDERS_ORDER_ID_H 24 25 #include <taler/taler-merchant/common.h> 26 27 28 /** 29 * Possible options we can set for the GET /private/orders/$ORDER_ID request. 30 */ 31 enum TALER_MERCHANT_GetPrivateOrderOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_GET_PRIVATE_ORDER_OPTION_END = 0, 37 38 /** 39 * Session ID for repurchase detection. 40 */ 41 TALER_MERCHANT_GET_PRIVATE_ORDER_OPTION_SESSION_ID, 42 43 /** 44 * Long polling timeout. 45 */ 46 TALER_MERCHANT_GET_PRIVATE_ORDER_OPTION_TIMEOUT, 47 48 /** 49 * If set to true, try to obtain the wire transfer status 50 * for this order from the exchange. 51 * @deprecated since protocol v6. 52 */ 53 TALER_MERCHANT_GET_PRIVATE_ORDER_OPTION_TRANSFER, 54 55 /** 56 * Long-poll ETag to suppress responses that have not changed. 57 * ShortHashCode value. 58 * @since protocol v25. 59 */ 60 TALER_MERCHANT_GET_PRIVATE_ORDER_OPTION_LP_NOT_ETAG, 61 62 /** 63 * If true, refunded orders may be returned under 64 * "already_paid_order_id". 65 * @since protocol v9. 66 */ 67 TALER_MERCHANT_GET_PRIVATE_ORDER_OPTION_ALLOW_REFUNDED_FOR_REPURCHASE 68 69 }; 70 71 72 /** 73 * Value for an option for the GET /private/orders/$ORDER_ID request. 74 */ 75 struct TALER_MERCHANT_GetPrivateOrderOptionValue 76 { 77 78 /** 79 * Type of the option being set. 80 */ 81 enum TALER_MERCHANT_GetPrivateOrderOption option; 82 83 /** 84 * Specific option value. 85 */ 86 union 87 { 88 89 /** 90 * Value if @e option is 91 * #TALER_MERCHANT_GET_PRIVATE_ORDER_OPTION_SESSION_ID. 92 */ 93 const char *session_id; 94 95 /** 96 * Value if @e option is 97 * #TALER_MERCHANT_GET_PRIVATE_ORDER_OPTION_TIMEOUT. 98 */ 99 struct GNUNET_TIME_Relative timeout; 100 101 /** 102 * Value if @e option is 103 * #TALER_MERCHANT_GET_PRIVATE_ORDER_OPTION_TRANSFER. 104 */ 105 bool transfer; 106 107 /** 108 * Value if @e option is 109 * #TALER_MERCHANT_GET_PRIVATE_ORDER_OPTION_LP_NOT_ETAG. 110 */ 111 const struct GNUNET_ShortHashCode *lp_not_etag; 112 113 /** 114 * Value if @e option is 115 * #TALER_MERCHANT_GET_PRIVATE_ORDER_OPTION_ALLOW_REFUNDED_FOR_REPURCHASE. 116 */ 117 bool allow_refunded_for_repurchase; 118 119 } details; 120 121 }; 122 123 124 /** 125 * Handle for a GET /private/orders/$ORDER_ID request. 126 */ 127 struct TALER_MERCHANT_GetPrivateOrderHandle; 128 129 130 /** 131 * Set up GET /private/orders/$ORDER_ID operation. 132 * Note that you must explicitly start the operation after 133 * possibly setting options. 134 * 135 * @param ctx the context 136 * @param url base URL of the merchant backend 137 * @param order_id identifier of the order to retrieve 138 * @return handle to operation 139 */ 140 struct TALER_MERCHANT_GetPrivateOrderHandle * 141 TALER_MERCHANT_get_private_order_create ( 142 struct GNUNET_CURL_Context *ctx, 143 const char *url, 144 const char *order_id); 145 146 147 /** 148 * Terminate the list of the options. 149 * 150 * @return the terminating object of struct TALER_MERCHANT_GetPrivateOrderOptionValue 151 */ 152 #define TALER_MERCHANT_get_private_order_option_end_() \ 153 (const struct TALER_MERCHANT_GetPrivateOrderOptionValue) \ 154 { \ 155 .option = TALER_MERCHANT_GET_PRIVATE_ORDER_OPTION_END \ 156 } 157 158 /** 159 * Set session ID for repurchase detection. 160 * 161 * @param s session ID to use 162 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateOrderOptionValue 163 */ 164 #define TALER_MERCHANT_get_private_order_option_session_id(s) \ 165 (const struct TALER_MERCHANT_GetPrivateOrderOptionValue) \ 166 { \ 167 .option = TALER_MERCHANT_GET_PRIVATE_ORDER_OPTION_SESSION_ID, \ 168 .details.session_id = (s) \ 169 } 170 171 /** 172 * Set long polling timeout. 173 * 174 * @param t timeout to use 175 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateOrderOptionValue 176 */ 177 #define TALER_MERCHANT_get_private_order_option_timeout(t) \ 178 (const struct TALER_MERCHANT_GetPrivateOrderOptionValue) \ 179 { \ 180 .option = TALER_MERCHANT_GET_PRIVATE_ORDER_OPTION_TIMEOUT, \ 181 .details.timeout = (t) \ 182 } 183 184 /** 185 * Set transfer flag (try to obtain wire transfer status from exchange). 186 * @deprecated since protocol v6. 187 * 188 * @param b true to request wire transfer status 189 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateOrderOptionValue 190 */ 191 #define TALER_MERCHANT_get_private_order_option_transfer(b) \ 192 (const struct TALER_MERCHANT_GetPrivateOrderOptionValue) \ 193 { \ 194 .option = TALER_MERCHANT_GET_PRIVATE_ORDER_OPTION_TRANSFER, \ 195 .details.transfer = (b) \ 196 } 197 198 /** 199 * Set long-poll ETag to suppress unchanged responses. 200 * 201 * @param e pointer to the short hash code ETag 202 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateOrderOptionValue 203 */ 204 #define TALER_MERCHANT_get_private_order_option_lp_not_etag(e) \ 205 (const struct TALER_MERCHANT_GetPrivateOrderOptionValue) \ 206 { \ 207 .option = TALER_MERCHANT_GET_PRIVATE_ORDER_OPTION_LP_NOT_ETAG, \ 208 .details.lp_not_etag = (e) \ 209 } 210 211 /** 212 * Set allow-refunded-for-repurchase flag. 213 * 214 * @param b true to allow refunded orders under already_paid_order_id 215 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateOrderOptionValue 216 */ 217 #define TALER_MERCHANT_get_private_order_option_allow_refunded_for_repurchase(b) \ 218 (const struct TALER_MERCHANT_GetPrivateOrderOptionValue) \ 219 { \ 220 .option = TALER_MERCHANT_GET_PRIVATE_ORDER_OPTION_ALLOW_REFUNDED_FOR_REPURCHASE, \ 221 .details.allow_refunded_for_repurchase = (b) \ 222 } 223 224 225 /** 226 * Set the requested options for the operation. 227 * 228 * If any option fail other options may be or may be not applied. 229 * 230 * @param oph the request to set the options for 231 * @param num_options length of the @a options array 232 * @param options an array of options 233 * @return #GNUNET_OK on success, 234 * #GNUNET_NO on failure, 235 * #GNUNET_SYSERR on internal error 236 */ 237 enum GNUNET_GenericReturnValue 238 TALER_MERCHANT_get_private_order_set_options_ ( 239 struct TALER_MERCHANT_GetPrivateOrderHandle *oph, 240 unsigned int num_options, 241 const struct TALER_MERCHANT_GetPrivateOrderOptionValue *options); 242 243 244 /** 245 * Set the requested options for the operation. 246 * 247 * If any option fail other options may be or may be not applied. 248 * 249 * It should be used with helpers that create required options, for example: 250 * 251 * TALER_MERCHANT_get_private_order_set_options ( 252 * oph, 253 * TALER_MERCHANT_get_private_order_option_session_id ("mysession")); 254 * 255 * @param oph the request to set the options for 256 * @param ... the list of the options, each option must be created 257 * by helpers TALER_MERCHANT_get_private_order_option_NAME(VALUE) 258 * @return #GNUNET_OK on success, 259 * #GNUNET_NO on failure, 260 * #GNUNET_SYSERR on internal error 261 */ 262 #define TALER_MERCHANT_get_private_order_set_options(oph,...) \ 263 TALER_MERCHANT_get_private_order_set_options_ ( \ 264 oph, \ 265 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 266 ((const struct TALER_MERCHANT_GetPrivateOrderOptionValue[]) \ 267 {__VA_ARGS__, TALER_MERCHANT_get_private_order_option_end_ () } \ 268 )) 269 270 271 /** 272 * Order status code. 273 */ 274 enum TALER_MERCHANT_OrderStatusCode 275 { 276 /** 277 * The order is unpaid. 278 */ 279 TALER_MERCHANT_OSC_UNPAID = 0, 280 281 /** 282 * The order has been claimed by a wallet. 283 */ 284 TALER_MERCHANT_OSC_CLAIMED = 1, 285 286 /** 287 * The order has been paid. 288 */ 289 TALER_MERCHANT_OSC_PAID = 2 290 }; 291 292 293 /** 294 * Refund detail in a paid order (merchant view). 295 */ 296 struct TALER_MERCHANT_GetPrivateOrderRefundDetail 297 { 298 299 /** 300 * Human-readable reason given for the refund. 301 */ 302 const char *reason; 303 304 /** 305 * Time when the refund was granted. 306 */ 307 struct GNUNET_TIME_Timestamp refund_time; 308 309 /** 310 * Total amount that was refunded. 311 */ 312 struct TALER_Amount refund_amount; 313 314 /** 315 * True if a refund is still available for the wallet 316 * for this payment. 317 */ 318 bool pending; 319 320 }; 321 322 323 /** 324 * Response details for a GET /private/orders/$ORDER_ID request. 325 */ 326 struct TALER_MERCHANT_GetPrivateOrderResponse 327 { 328 329 /** 330 * HTTP response details. 331 */ 332 struct TALER_MERCHANT_HttpResponse hr; 333 334 /** 335 * Details depending on the HTTP status code. 336 */ 337 union 338 { 339 340 /** 341 * Details on #MHD_HTTP_OK. 342 */ 343 struct 344 { 345 346 /** 347 * Current status of the order. 348 */ 349 enum TALER_MERCHANT_OrderStatusCode status; 350 351 /** 352 * Details depending on @a status. 353 */ 354 union 355 { 356 357 /** 358 * Details when @a status is #TALER_MERCHANT_OSC_UNPAID. 359 */ 360 struct 361 { 362 363 /** 364 * Order ID of a previously paid order that covers this one, 365 * or NULL if none. 366 */ 367 const char *already_paid_order_id; 368 369 /** 370 * Fulfillment URL of an already paid order, or NULL. 371 */ 372 const char *already_paid_fulfillment_url; 373 374 /** 375 * Taler pay URI for this order. 376 */ 377 const char *taler_pay_uri; 378 379 /** 380 * Short summary of the order. 381 */ 382 const char *summary; 383 384 /** 385 * Proto contract terms (contract terms without nonce). 386 * @since protocol v25. 387 */ 388 const json_t *proto_contract_terms; 389 390 /** 391 * Status URL for the order. 392 */ 393 const char *order_status_url; 394 395 /** 396 * Timestamp when the order was created. 397 */ 398 struct GNUNET_TIME_Timestamp creation_time; 399 400 /** 401 * Deadline when the offer expires. 402 * @since protocol v21. 403 */ 404 struct GNUNET_TIME_Timestamp pay_deadline; 405 406 } unpaid; 407 408 /** 409 * Details when @a status is #TALER_MERCHANT_OSC_CLAIMED. 410 */ 411 struct 412 { 413 414 /** 415 * Contract terms (JSON). 416 */ 417 const json_t *contract_terms; 418 419 /** 420 * Status URL for the order. 421 * @since protocol v19. 422 */ 423 const char *order_status_url; 424 425 } claimed; 426 427 /** 428 * Details when @a status is #TALER_MERCHANT_OSC_PAID. 429 */ 430 struct 431 { 432 433 /** 434 * True if a refund has been granted. 435 */ 436 bool refunded; 437 438 /** 439 * True if a refund is still pending at the exchange. 440 */ 441 bool refund_pending; 442 443 /** 444 * True if the payment has been wired to the merchant. 445 */ 446 bool wired; 447 448 /** 449 * Total amount deposited. 450 */ 451 struct TALER_Amount deposit_total; 452 453 /** 454 * Error code from the exchange, or TALER_EC_NONE. 455 */ 456 enum TALER_ErrorCode exchange_ec; 457 458 /** 459 * HTTP status returned by the exchange. 460 */ 461 unsigned int exchange_hc; 462 463 /** 464 * Total amount refunded. 465 */ 466 struct TALER_Amount refund_amount; 467 468 /** 469 * Contract terms (JSON). 470 */ 471 const json_t *contract_terms; 472 473 /** 474 * Number of wire transfers in @a wts. 475 */ 476 unsigned int wts_len; 477 478 /** 479 * Array of wire transfer details. 480 */ 481 struct TALER_MERCHANT_WireTransfer *wts; 482 483 /** 484 * Number of refund details in @a refunds. 485 */ 486 unsigned int refunds_len; 487 488 /** 489 * Array of per-coin refund details. 490 */ 491 struct TALER_MERCHANT_GetPrivateOrderRefundDetail *refunds; 492 493 /** 494 * Timestamp of the last payment. 495 */ 496 struct GNUNET_TIME_Timestamp last_payment; 497 498 /** 499 * Status URL for the order. 500 */ 501 const char *order_status_url; 502 503 /** 504 * Index of the selected choice within the choices array 505 * of contract terms, or -1 if not set. 506 * @since protocol v21. 507 */ 508 int choice_index; 509 510 } paid; 511 512 } details; 513 514 } ok; 515 516 } details; 517 518 }; 519 520 521 #ifndef TALER_MERCHANT_GET_PRIVATE_ORDER_RESULT_CLOSURE 522 /** 523 * Type of the closure used by 524 * the #TALER_MERCHANT_GetPrivateOrderCallback. 525 */ 526 #define TALER_MERCHANT_GET_PRIVATE_ORDER_RESULT_CLOSURE void 527 #endif /* TALER_MERCHANT_GET_PRIVATE_ORDER_RESULT_CLOSURE */ 528 529 /** 530 * Callback for a GET /private/orders/$ORDER_ID request. 531 * 532 * @param cls closure 533 * @param osr response details 534 */ 535 typedef void 536 (*TALER_MERCHANT_GetPrivateOrderCallback)( 537 TALER_MERCHANT_GET_PRIVATE_ORDER_RESULT_CLOSURE *cls, 538 const struct TALER_MERCHANT_GetPrivateOrderResponse *osr); 539 540 541 /** 542 * Start GET /private/orders/$ORDER_ID operation. 543 * 544 * @param[in,out] oph operation to start 545 * @param cb function to call with the merchant's result 546 * @param cb_cls closure for @a cb 547 * @return status code, #TALER_EC_NONE on success 548 */ 549 enum TALER_ErrorCode 550 TALER_MERCHANT_get_private_order_start ( 551 struct TALER_MERCHANT_GetPrivateOrderHandle *oph, 552 TALER_MERCHANT_GetPrivateOrderCallback cb, 553 TALER_MERCHANT_GET_PRIVATE_ORDER_RESULT_CLOSURE *cb_cls); 554 555 556 /** 557 * Cancel GET /private/orders/$ORDER_ID operation. This function must not be 558 * called by clients after the TALER_MERCHANT_GetPrivateOrderCallback 559 * has been invoked (as in those cases it'll be called internally by 560 * the implementation already). 561 * 562 * @param[in] oph operation to cancel 563 */ 564 void 565 TALER_MERCHANT_get_private_order_cancel ( 566 struct TALER_MERCHANT_GetPrivateOrderHandle *oph); 567 568 569 #endif /* _TALER_MERCHANT__GET_PRIVATE_ORDERS_ORDER_ID_H */