taler_merchant_pay_service.h (19460B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2014-2024 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free 7 Software Foundation; either version 3, 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.LIB. If not, see <http://www.gnu.org/licenses/> 15 */ 16 /** 17 * @file taler_merchant_pay_service.h 18 * @brief Payment‑specific interface extracted from taler_merchant_service.h 19 * **Only** declarations and helper‑macros live here – the actual 20 * implementation must be provided in the accompanying *.c file. 21 * This header can be included by both merchant front‑ends and wallets 22 * that want to create or proxy /orders/$ID/pay requests. 23 */ 24 #ifndef TALER_MERCHANT_PAY_SERVICE_H 25 #define TALER_MERCHANT_PAY_SERVICE_H 26 27 #include <taler/taler_util.h> 28 #include <taler/taler_signatures.h> 29 #include <taler/taler_error_codes.h> 30 #include <taler/taler_exchange_service.h> 31 #include "taler_merchant_service.h" 32 #include <gnunet/gnunet_time_lib.h> 33 34 35 #ifndef TALER_MERCHANT_ORDER_PAY_CALLBACK_CLOSURE_TYPE 36 #define TALER_MERCHANT_ORDER_PAY_CALLBACK_CLOSURE_TYPE void 37 #endif 38 39 /** 40 * Opaque handle returned by the payment helper APIs declared below. 41 */ 42 struct TALER_MERCHANT_OrderPayHandle; 43 44 /** 45 * Which option is being supplied to #TALER_MERCHANT_order_pay_set_options(). 46 */ 47 enum TALER_MERCHANT_OrderPayOptionType 48 { 49 TALER_MERCHANT_OrderPayOptionType_END = 0, 50 TALER_MERCHANT_OrderPayOptionType_MERCHANT_URL, 51 TALER_MERCHANT_OrderPayOptionType_SESSION_ID, 52 TALER_MERCHANT_OrderPayOptionType_H_CONTRACT, 53 TALER_MERCHANT_OrderPayOptionType_CHOICE_INDEX, 54 TALER_MERCHANT_OrderPayOptionType_AMOUNT, 55 TALER_MERCHANT_OrderPayOptionType_MAX_FEE, 56 TALER_MERCHANT_OrderPayOptionType_MERCHANT_PUB, 57 TALER_MERCHANT_OrderPayOptionType_TIMESTAMP, 58 TALER_MERCHANT_OrderPayOptionType_REFUND_DEADLINE, 59 TALER_MERCHANT_OrderPayOptionType_PAY_DEADLINE, 60 TALER_MERCHANT_OrderPayOptionType_H_WIRE, 61 TALER_MERCHANT_OrderPayOptionType_ORDER_ID, 62 TALER_MERCHANT_OrderPayOptionType_COINS, 63 TALER_MERCHANT_OrderPayOptionType_INPUT_TOKENS, 64 TALER_MERCHANT_OrderPayOptionType_OUTPUT_TOKENS, 65 TALER_MERCHANT_OrderPayOptionType_WALLET_DATA, // Used privately so no #define is present for it 66 TALER_MERCHANT_OrderPayOptionType_DONAU_URL, 67 TALER_MERCHANT_OrderPayOptionType_DONAU_YEAR, 68 TALER_MERCHANT_OrderPayOptionType_DONAU_BUDIS, 69 /*New objects go in here*/ 70 TALER_MERCHANT_OrderPayOptionType_LENGTH 71 }; 72 73 /** 74 * Container describing *one* option for a payment request. 75 * 76 * Applications should typically not use this struct directly, 77 * only through respective TALER_MERCHANT_ORDER_PAY_OPTION_-macros 78 */ 79 struct TALER_MERCHANT_OrderPayOption 80 { 81 /** 82 * Type of the option being supplied. 83 */ 84 enum TALER_MERCHANT_OrderPayOptionType ot; 85 86 union 87 { 88 const char *merchant_url; 89 const char *session_id; 90 const struct TALER_PrivateContractHashP *h_contract; 91 int choice_index; 92 struct TALER_Amount amount; 93 struct TALER_Amount max_fee; 94 struct TALER_MerchantPublicKeyP merchant_pub; 95 struct GNUNET_TIME_Timestamp timestamp; 96 struct GNUNET_TIME_Timestamp refund_deadline; 97 struct GNUNET_TIME_Timestamp pay_deadline; 98 struct TALER_MerchantWireHashP h_wire; 99 const char *order_id; 100 struct 101 { 102 unsigned int num_coins; 103 const struct TALER_MERCHANT_PayCoin *coins; 104 } coins; 105 struct 106 { 107 unsigned int num_tokens; 108 const struct TALER_MERCHANT_UseToken *tokens; 109 } input_tokens; 110 struct 111 { 112 unsigned int num_output_tokens; 113 const struct TALER_MERCHANT_OutputToken *output_tokens; 114 } output_tokens; 115 const char *donau_url; 116 uint64_t donau_year; 117 json_t *donau_budis_json; 118 } details; 119 }; 120 121 122 /** 123 * Status codes returned from #TALER_MERCHANT_order_pay_set_options() and 124 * #TALER_MERCHANT_order_pay_start(). 125 */ 126 enum TALER_MERCHANT_OrderPayErrorCode 127 { 128 TALER_MERCHANT_OPOEC_OK = 0, /**< everything fine */ 129 TALER_MERCHANT_OPOEC_UNKNOWN_OPTION, /**< unrecognised option kind */ 130 TALER_MERCHANT_OPOEC_DUPLICATE_OPTION, /**< option given more than once */ 131 TALER_MERCHANT_OPOEC_INVALID_VALUE, /**< semantic/format error in value */ 132 TALER_MERCHANT_OPOEC_MISSING_MANDATORY, /**< required field missing at start */ 133 TALER_MERCHANT_OPOEC_URL_FAILURE, /**< failed to build request URL */ 134 TALER_MERCHANT_OPOEC_CURL_FAILURE /**< failed to init/schedule CURL */ 135 }; 136 137 138 /** 139 * Terminate the list of payment options. 140 * 141 * @par Example 142 * \code 143 * struct TALER_MERCHANT_OrderPayOption opts[] = { 144 * TALER_MERCHANT_ORDER_PAY_OPTION_TERMINATE() 145 * }; 146 * \endcode 147 */ 148 #define TALER_MERCHANT_ORDER_PAY_OPTION_TERMINATE() \ 149 (struct TALER_MERCHANT_OrderPayOption){ \ 150 .ot = TALER_MERCHANT_OrderPayOptionType_END \ 151 } 152 153 154 /** 155 * Specify the merchant’s URL for the payment request. 156 * 157 * @param _url NULL-terminated string holding the merchant endpoint. 158 * 159 * @par Example 160 * \code 161 * struct TALER_MERCHANT_OrderPayOption opts[] = { 162 * TALER_MERCHANT_ORDER_PAY_OPTION_MERCHANT_URL("https://shop.example/pay"), 163 * TALER_MERCHANT_ORDER_PAY_OPTION_TERMINATE() 164 * }; 165 * \endcode 166 */ 167 #define TALER_MERCHANT_ORDER_PAY_OPTION_MERCHANT_URL(_url) \ 168 (struct TALER_MERCHANT_OrderPayOption){ \ 169 .ot = TALER_MERCHANT_OrderPayOptionType_MERCHANT_URL, \ 170 .details.merchant_url = (_url) \ 171 } 172 173 174 /** 175 * Supply the session identifier for this payment. 176 * 177 * @param _sid session ID string. 178 * 179 * @par Example 180 * \code 181 * struct TALER_MERCHANT_OrderPayOption opts[] = { 182 * TALER_MERCHANT_ORDER_PAY_OPTION_SESSION_ID("ABC123"), 183 * TALER_MERCHANT_ORDER_PAY_OPTION_TERMINATE() 184 * }; 185 * \endcode 186 */ 187 #define TALER_MERCHANT_ORDER_PAY_OPTION_SESSION_ID(_sid) \ 188 (struct TALER_MERCHANT_OrderPayOption){ \ 189 .ot = TALER_MERCHANT_OrderPayOptionType_SESSION_ID, \ 190 .details.session_id = (_sid) \ 191 } 192 193 194 /** 195 * Supply a private contract hash for the order. 196 * 197 * @param _h pointer to a TALER_PrivateContractHashP. 198 * 199 * @par Example 200 * \code 201 * struct TALER_PrivateContractHashP *h = …; 202 * struct TALER_MERCHANT_OrderPayOption opts[] = { 203 * TALER_MERCHANT_ORDER_PAY_OPTION_H_CONTRACT(h), 204 * TALER_MERCHANT_ORDER_PAY_OPTION_TERMINATE() 205 * }; 206 * \endcode 207 */ 208 #define TALER_MERCHANT_ORDER_PAY_OPTION_H_CONTRACT(_h) \ 209 (struct TALER_MERCHANT_OrderPayOption){ \ 210 .ot = TALER_MERCHANT_OrderPayOptionType_H_CONTRACT, \ 211 .details.h_contract = (_h) \ 212 } 213 214 215 /** 216 * Supply which choice index the customer(wallet) selected. 217 * from contract terms. 218 * 219 * @param _idx choice index. 220 * 221 * @par Example 222 * \code 223 * struct TALER_MERCHANT_OrderPayOption opts[] = { 224 * TALER_MERCHANT_ORDER_PAY_OPTION_CHOICE_INDEX(2), 225 * TALER_MERCHANT_ORDER_PAY_OPTION_TERMINATE() 226 * }; 227 * \endcode 228 */ 229 #define TALER_MERCHANT_ORDER_PAY_OPTION_CHOICE_INDEX(_idx) \ 230 (struct TALER_MERCHANT_OrderPayOption){ \ 231 .ot = TALER_MERCHANT_OrderPayOptionType_CHOICE_INDEX, \ 232 .details.choice_index = (_idx) \ 233 } 234 235 236 /** 237 * Specify the amount to be paid. 238 * 239 * @param _amt pointer to a TALER_Amount struct. 240 * 241 * @par Example 242 * \code 243 * struct TALER_Amount amt = ...; 244 * struct TALER_MERCHANT_OrderPayOption opts[] = { 245 * TALER_MERCHANT_ORDER_PAY_OPTION_AMOUNT(&amt), 246 * TALER_MERCHANT_ORDER_PAY_OPTION_TERMINATE() 247 * }; 248 * \endcode 249 */ 250 #define TALER_MERCHANT_ORDER_PAY_OPTION_AMOUNT(_amt) \ 251 (struct TALER_MERCHANT_OrderPayOption){ \ 252 .ot = TALER_MERCHANT_OrderPayOptionType_AMOUNT, \ 253 .details.amount = *(_amt) \ 254 } 255 256 257 /** 258 * Set the maximum acceptable fee. 259 * 260 * @param _fee pointer to a TALER_Amount struct for the fee cap. 261 * 262 * @par Example 263 * \code 264 * struct TALER_Amount fee = ...; 265 * struct TALER_MERCHANT_OrderPayOption opts[] = { 266 * TALER_MERCHANT_ORDER_PAY_OPTION_MAX_FEE(&fee), 267 * TALER_MERCHANT_ORDER_PAY_OPTION_TERMINATE() 268 * }; 269 * \endcode 270 */ 271 #define TALER_MERCHANT_ORDER_PAY_OPTION_MAX_FEE(_fee) \ 272 (struct TALER_MERCHANT_OrderPayOption){ \ 273 .ot = TALER_MERCHANT_OrderPayOptionType_MAX_FEE, \ 274 .details.max_fee = *(_fee) \ 275 } 276 277 278 /** 279 * Provide the merchant’s public key. 280 * 281 * @param _mpub pointer to a TALER_MerchantPublicKeyP. 282 * 283 * @par Example 284 * \code 285 * struct TALER_MerchantPublicKeyP *mp = …; 286 * struct TALER_MERCHANT_OrderPayOption opts[] = { 287 * TALER_MERCHANT_ORDER_PAY_OPTION_MERCHANT_PUB(mp), 288 * TALER_MERCHANT_ORDER_PAY_OPTION_TERMINATE() 289 * }; 290 * \endcode 291 */ 292 #define TALER_MERCHANT_ORDER_PAY_OPTION_MERCHANT_PUB(_mpub) \ 293 (struct TALER_MERCHANT_OrderPayOption){ \ 294 .ot = TALER_MERCHANT_OrderPayOptionType_MERCHANT_PUB, \ 295 .details.merchant_pub = *(_mpub) \ 296 } 297 298 299 /** 300 * Stamp the request with a specific time. 301 * 302 * @param _ts GNUNET_TIME_Timestamp value. 303 * 304 * @par Example 305 * \code 306 * struct GNUNET_TIME_Timestamp now = …; 307 * struct TALER_MERCHANT_OrderPayOption opts[] = { 308 * TALER_MERCHANT_ORDER_PAY_OPTION_TIMESTAMP(now), 309 * TALER_MERCHANT_ORDER_PAY_OPTION_TERMINATE() 310 * }; 311 * \endcode 312 */ 313 #define TALER_MERCHANT_ORDER_PAY_OPTION_TIMESTAMP(_ts) \ 314 (struct TALER_MERCHANT_OrderPayOption){ \ 315 .ot = TALER_MERCHANT_OrderPayOptionType_TIMESTAMP, \ 316 .details.timestamp = (_ts) \ 317 } 318 319 320 /** 321 * Set a deadline by which refunds may be issued. 322 * 323 * @param _ts GNUNET_TIME_Timestamp for the refund deadline. 324 * 325 * @par Example 326 * \code 327 * struct GNUNET_TIME_Timestamp rd = …; 328 * struct TALER_MERCHANT_OrderPayOption opts[] = { 329 * TALER_MERCHANT_ORDER_PAY_OPTION_REFUND_DEADLINE(rd), 330 * TALER_MERCHANT_ORDER_PAY_OPTION_TERMINATE() 331 * }; 332 * \endcode 333 */ 334 #define TALER_MERCHANT_ORDER_PAY_OPTION_REFUND_DEADLINE(_ts) \ 335 (struct TALER_MERCHANT_OrderPayOption){ \ 336 .ot = TALER_MERCHANT_OrderPayOptionType_REFUND_DEADLINE, \ 337 .details.refund_deadline = (_ts) \ 338 } 339 340 341 /** 342 * Set a deadline by which payment must be completed. 343 * 344 * @param _ts GNUNET_TIME_Timestamp for the payment deadline. 345 * 346 * @par Example 347 * \code 348 * struct GNUNET_TIME_Timestamp pd = …; 349 * struct TALER_MERCHANT_OrderPayOption opts[] = { 350 * TALER_MERCHANT_ORDER_PAY_OPTION_PAY_DEADLINE(pd), 351 * TALER_MERCHANT_ORDER_PAY_OPTION_TERMINATE() 352 * }; 353 * \endcode 354 */ 355 #define TALER_MERCHANT_ORDER_PAY_OPTION_PAY_DEADLINE(_ts) \ 356 (struct TALER_MERCHANT_OrderPayOption){ \ 357 .ot = TALER_MERCHANT_OrderPayOptionType_PAY_DEADLINE, \ 358 .details.pay_deadline = (_ts) \ 359 } 360 361 362 /** 363 * Supply the merchant wire transaction hash. 364 * 365 * @param _hwire pointer to a TALER_MerchantWireHashP. 366 * 367 * @par Example 368 * \code 369 * struct TALER_MerchantWireHashP *wh = …; 370 * struct TALER_MERCHANT_OrderPayOption opts[] = { 371 * TALER_MERCHANT_ORDER_PAY_OPTION_H_WIRE(wh), 372 * TALER_MERCHANT_ORDER_PAY_OPTION_TERMINATE() 373 * }; 374 * \endcode 375 */ 376 #define TALER_MERCHANT_ORDER_PAY_OPTION_H_WIRE(_hwire) \ 377 (struct TALER_MERCHANT_OrderPayOption){ \ 378 .ot = TALER_MERCHANT_OrderPayOptionType_H_WIRE, \ 379 .details.h_wire = *(_hwire) \ 380 } 381 382 383 /** 384 * Provide the unique order identifier. 385 * 386 * @param _oid NULL-terminated string of the order ID. 387 * 388 * @par Example 389 * \code 390 * struct TALER_MERCHANT_OrderPayOption opts[] = { 391 * TALER_MERCHANT_ORDER_PAY_OPTION_ORDER_ID("order-42"), 392 * TALER_MERCHANT_ORDER_PAY_OPTION_TERMINATE() 393 * }; 394 * \endcode 395 */ 396 #define TALER_MERCHANT_ORDER_PAY_OPTION_ORDER_ID(_oid) \ 397 (struct TALER_MERCHANT_OrderPayOption){ \ 398 .ot = TALER_MERCHANT_OrderPayOptionType_ORDER_ID, \ 399 .details.order_id = (_oid) \ 400 } 401 402 403 /** 404 * Include a list of pay coins. 405 * 406 * @param _num number of coins in the array 407 * @param _coins pointer to array of TALER_MERCHANT_PayCoin. 408 * 409 * @par Example 410 * \code 411 * const struct TALER_MERCHANT_PayCoin coins[2] = { … }; 412 * struct TALER_MERCHANT_OrderPayOption opts[] = { 413 * TALER_MERCHANT_ORDER_PAY_OPTION_COINS(2, coins), 414 * TALER_MERCHANT_ORDER_PAY_OPTION_TERMINATE() 415 * }; 416 * \endcode 417 */ 418 #define TALER_MERCHANT_ORDER_PAY_OPTION_COINS(_num,_coins) \ 419 (struct TALER_MERCHANT_OrderPayOption){ \ 420 .ot = TALER_MERCHANT_OrderPayOptionType_COINS, \ 421 .details.coins = { .num_coins = (_num), \ 422 .coins = (_coins) } \ 423 } 424 425 426 /** 427 * Include a list of input tokens. 428 * 429 * @param _num number of tokens 430 * @param _tokens pointer to array of TALER_MERCHANT_UseToken. 431 * 432 * @par Example 433 * \code 434 * const struct TALER_MERCHANT_UseToken toks[1] = { … }; 435 * struct TALER_MERCHANT_OrderPayOption opts[] = { 436 * TALER_MERCHANT_ORDER_PAY_OPTION_INPUT_TOKENS(1, toks), 437 * TALER_MERCHANT_ORDER_PAY_OPTION_TERMINATE() 438 * }; 439 * \endcode 440 */ 441 442 #define TALER_MERCHANT_ORDER_PAY_OPTION_INPUT_TOKENS(_num,_tokens) \ 443 (struct TALER_MERCHANT_OrderPayOption){ \ 444 .ot = TALER_MERCHANT_OrderPayOptionType_INPUT_TOKENS, \ 445 .details.input_tokens = { .num_tokens = (_num), \ 446 .tokens = (_tokens) } \ 447 } 448 449 450 /** 451 * Include a list of output tokens. 452 * 453 * @param _num number of output tokens 454 * @param _otokens pointer to array of TALER_MERCHANT_OutputToken. 455 * 456 * @par Example 457 * \code 458 * const struct TALER_MERCHANT_OutputToken ots[3] = { … }; 459 * struct TALER_MERCHANT_OrderPayOption opts[] = { 460 * TALER_MERCHANT_ORDER_PAY_OPTION_OUTPUT_TOKENS(3, ots), 461 * TALER_MERCHANT_ORDER_PAY_OPTION_TERMINATE() 462 * }; 463 * \endcode 464 */ 465 #define TALER_MERCHANT_ORDER_PAY_OPTION_OUTPUT_TOKENS(_num,_otokens) \ 466 (struct TALER_MERCHANT_OrderPayOption){ \ 467 .ot = TALER_MERCHANT_OrderPayOptionType_OUTPUT_TOKENS, \ 468 .details.output_tokens = { .num_output_tokens = (_num), \ 469 .output_tokens = (_otokens) } \ 470 } 471 472 473 /** 474 * Supply the Donau service URL. 475 * 476 * @param _u NULL-terminated string of the Donau endpoint. 477 * 478 * @par Example 479 * \code 480 * struct TALER_MERCHANT_OrderPayOption opts[] = { 481 * TALER_MERCHANT_ORDER_PAY_OPTION_DONAU_URL("https://donau.example"), 482 * TALER_MERCHANT_ORDER_PAY_OPTION_TERMINATE() 483 * }; 484 * \endcode 485 */ 486 #define TALER_MERCHANT_ORDER_PAY_OPTION_DONAU_URL(_u) \ 487 (struct TALER_MERCHANT_OrderPayOption){ \ 488 .ot = TALER_MERCHANT_OrderPayOptionType_DONAU_URL, \ 489 .details.donau_url = (_u) \ 490 } 491 492 493 /** 494 * Specify the Donau “year” parameter. 495 * 496 * @param _y 64-bit unsigned integer for the Donau year. 497 * 498 * @par Example 499 * \code 500 * struct TALER_MERCHANT_OrderPayOption opts[] = { 501 * TALER_MERCHANT_ORDER_PAY_OPTION_DONAU_YEAR(2025), 502 * TALER_MERCHANT_ORDER_PAY_OPTION_TERMINATE() 503 * }; 504 * \endcode 505 */ 506 #define TALER_MERCHANT_ORDER_PAY_OPTION_DONAU_YEAR(_y) \ 507 (struct TALER_MERCHANT_OrderPayOption){ \ 508 .ot = TALER_MERCHANT_OrderPayOptionType_DONAU_YEAR, \ 509 .details.donau_year = (_y) \ 510 } 511 512 513 /** 514 * Supply the Donau “budis” JSON structure. 515 * 516 * @param _js pointer to a json_t* holding the budis data. 517 * 518 * @par Example 519 * \code 520 * json_t *budis = json_pack("{s:i}", "quota", 100); 521 * struct TALER_MERCHANT_OrderPayOption opts[] = { 522 * TALER_MERCHANT_ORDER_PAY_OPTION_DONAU_BUDIS(budis), 523 * TALER_MERCHANT_ORDER_PAY_OPTION_TERMINATE() 524 * }; 525 * \endcode 526 */ 527 #define TALER_MERCHANT_ORDER_PAY_OPTION_DONAU_BUDIS(_js) \ 528 (struct TALER_MERCHANT_OrderPayOption){ \ 529 .ot = TALER_MERCHANT_OrderPayOptionType_DONAU_BUDIS, \ 530 .details.donau_budis_json = (_js) \ 531 } 532 533 534 /** 535 * Helper to call TALER_MERCHANT_order_pay_set_options() 536 * with a compound‐literal array terminated by TERMINATE(). 537 * 538 * @param ph the payment handle 539 * @param ... a comma-separated list of `_OPTION_*()` macros 540 * 541 * @par Example 542 * \code 543 * TALER_MERCHANT_ORDER_PAY_SET_OPTIONS(handle, 544 * TALER_MERCHANT_ORDER_PAY_OPTION_MERCHANT_URL("https://…"), 545 * TALER_MERCHANT_ORDER_PAY_OPTION_AMOUNT(&amt), 546 * TALER_MERCHANT_ORDER_PAY_OPTION_MAX_FEE(&fee) 547 * ); 548 * \endcode 549 */ 550 #define TALER_MERCHANT_ORDER_PAY_SET_OPTIONS(ph,...) \ 551 MHD_NOWARN_COMPOUND_LITERALS_ \ 552 TALER_MERCHANT_order_pay_set_options ( \ 553 daemon, \ 554 ((const struct TALER_MERCHANT_OrderPayHandle[]) \ 555 {__VA_ARGS__, TALER_MERCHANT_ORDER_PAY_OPTION_TERMINATE ()}), \ 556 MHD_OPTIONS_ARRAY_MAX_SIZE) \ 557 558 559 /** 560 * @brief Create and initialize a new payment handle. 561 * 562 * @param ctx GNUNET CURL context used for HTTP operations 563 * @param pay_cb callback to invoke when the payment completes or fails 564 * @param pay_cb_cls closure data passed back to @a pay_cb 565 * @return pointer to a newly allocated handle, or NULL on error 566 */ 567 struct TALER_MERCHANT_OrderPayHandle * 568 TALER_MERCHANT_order_pay_create (struct GNUNET_CURL_Context *ctx, 569 TALER_MERCHANT_OrderPayCallback pay_cb, 570 TALER_MERCHANT_ORDER_PAY_CALLBACK_CLOSURE_TYPE 571 *pay_cb_cls); 572 573 574 /** 575 * @brief Configure payment options on a handle. 576 * 577 * @param ph payment handle to configure 578 * @param options NULL-terminated array of options (use 579 * TALER_MERCHANT_ORDER_PAY_OPTION_* macros) 580 * @param max_options maximum number of options in the @a options array 581 * @return #TALER_MERCHANT_OPOEC_OK on success; 582 * error code otherwise 583 */ 584 enum TALER_MERCHANT_OrderPayErrorCode 585 TALER_MERCHANT_order_pay_set_options (struct TALER_MERCHANT_OrderPayHandle *ph, 586 const struct TALER_MERCHANT_OrderPayOption 587 options[], 588 size_t max_options); 589 590 591 /** 592 * @brief Start processing the payment request. 593 * 594 * @param ph fully configured payment handle 595 * @return #TALER_MERCHANT_OPOEC_OK on successful dispatch; 596 * error code on validation or dispatch failure 597 */ 598 enum TALER_MERCHANT_OrderPayErrorCode 599 TALER_MERCHANT_order_pay_start (struct TALER_MERCHANT_OrderPayHandle *ph); 600 601 602 /** 603 * @brief Cancel an in-flight or pending payment. 604 * 605 * @param ph payment handle to cancel and free 606 */ 607 void 608 TALER_MERCHANT_order_pay_cancel1 (struct TALER_MERCHANT_OrderPayHandle *ph); 609 610 #endif /* TALER_MERCHANT_PAY_SERVICE_H */