post-orders-ORDER_ID-pay.h (20705B)
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/post-orders-ORDER_ID-pay.h 19 * @brief C interface for the POST /orders/$ORDER_ID/pay endpoint 20 * @author Christian Grothoff 21 * @author Marcello Stanisci 22 */ 23 #ifndef _TALER_MERCHANT__POST_ORDERS_ORDER_ID_PAY_H 24 #define _TALER_MERCHANT__POST_ORDERS_ORDER_ID_PAY_H 25 26 #include <taler/taler-merchant/common.h> 27 28 /** 29 * Forward-declaration here to keep the API stable even if 30 * the Donau header is not available. 31 */ 32 struct DONAU_BlindedUniqueDonorIdentifierKeyPair; 33 34 /** 35 * One coin used to pay (frontend / external wallet mode). 36 */ 37 struct TALER_MERCHANT_PostOrdersPayPaidCoin 38 { 39 40 /** 41 * Denomination public key. 42 */ 43 struct TALER_DenominationPublicKey denom_pub; 44 45 /** 46 * Hash of the denomination public key. 47 */ 48 struct TALER_DenominationHashP denom_pub_hash; 49 50 /** 51 * Denomination signature over the coin. 52 */ 53 struct TALER_DenominationSignature denom_sig; 54 55 /** 56 * Face value of the denomination. 57 */ 58 struct TALER_Amount denom_value; 59 60 /** 61 * Public key of the coin. 62 */ 63 struct TALER_CoinSpendPublicKeyP coin_pub; 64 65 /** 66 * Signature by the coin authorizing the deposit. 67 */ 68 struct TALER_CoinSpendSignatureP coin_sig; 69 70 /** 71 * Hash of the age commitment for this coin. 72 */ 73 struct TALER_AgeCommitmentHashP h_age_commitment; 74 75 /** 76 * Set to true if this coin has an age commitment. 77 */ 78 bool has_age_commitment; 79 80 /** 81 * Total amount contributed including deposit fee. 82 */ 83 struct TALER_Amount amount_with_fee; 84 85 /** 86 * Amount contributed without the deposit fee. 87 */ 88 struct TALER_Amount amount_without_fee; 89 90 /** 91 * Deposit fee for this coin. 92 */ 93 struct TALER_Amount deposit_fee; 94 95 /** 96 * Base URL of the exchange this coin was issued by. 97 */ 98 char *exchange_url; 99 100 }; 101 102 103 /** 104 * One coin used to pay (wallet-internal mode, private key available). 105 */ 106 struct TALER_MERCHANT_PostOrdersPayCoin 107 { 108 109 /** 110 * Denomination public key. 111 */ 112 struct TALER_DenominationPublicKey denom_pub; 113 114 /** 115 * Denomination signature over the coin. 116 */ 117 struct TALER_DenominationSignature denom_sig; 118 119 /** 120 * Face value of the denomination. 121 */ 122 struct TALER_Amount denom_value; 123 124 /** 125 * Private key of the coin (to sign the deposit). 126 */ 127 struct TALER_CoinSpendPrivateKeyP coin_priv; 128 129 /** 130 * Hash of the age commitment for this coin, or 131 * all zeros if none. 132 */ 133 struct TALER_AgeCommitmentHashP h_age_commitment; 134 135 /** 136 * Total amount contributed including deposit fee. 137 */ 138 struct TALER_Amount amount_with_fee; 139 140 /** 141 * Amount contributed without the deposit fee. 142 */ 143 struct TALER_Amount amount_without_fee; 144 145 /** 146 * URL of the exchange that issued @e coin_priv. 147 */ 148 char *exchange_url; 149 150 }; 151 152 153 /** 154 * Token to use for payment (public form, already obtained). 155 */ 156 struct TALER_MERCHANT_PostOrdersPayUsedToken 157 { 158 159 /** 160 * Signature on TALER_TokenUseRequestPS made with the token use private key. 161 */ 162 struct TALER_TokenUseSignatureP token_sig; 163 164 /** 165 * Public key of the token. 166 */ 167 struct TALER_TokenUsePublicKeyP token_pub; 168 169 /** 170 * Unblinded signature made by the token issue public key of the merchant. 171 */ 172 struct TALER_TokenIssueSignature ub_sig; 173 174 /** 175 * Token issue public key associated with this token. 176 */ 177 struct TALER_TokenIssuePublicKey issue_pub; 178 179 }; 180 181 182 /** 183 * Information we need from the wallet to use a token for an order. 184 */ 185 struct TALER_MERCHANT_PostOrdersPayUseToken 186 { 187 188 /** 189 * Private key of the token (to sign the use authorization). 190 */ 191 struct TALER_TokenUsePrivateKeyP token_priv; 192 193 /** 194 * Unblinded signature made by the token issue public key of the merchant. 195 */ 196 struct TALER_TokenIssueSignature ub_sig; 197 198 /** 199 * Token issue public key associated with this token. 200 */ 201 struct TALER_TokenIssuePublicKey issue_pub; 202 203 }; 204 205 206 /** 207 * Output token: used both as input to pay (envelope to be signed) 208 * and as output in the pay response (blind signature received). 209 */ 210 struct TALER_MERCHANT_PostOrdersPayOutputToken 211 { 212 213 /** 214 * Blinded token envelope to be signed by the issuer (input to pay). 215 */ 216 struct TALER_TokenEnvelope envelope; 217 218 /** 219 * Blinded token issue signature received from the issuer (output of pay). 220 */ 221 struct TALER_BlindedTokenIssueSignature blinded_sig; 222 223 }; 224 225 226 /** 227 * Possible options for the POST /orders/$ORDER_ID/pay request. 228 */ 229 enum TALER_MERCHANT_PostOrdersPayOption 230 { 231 /** 232 * End of list of options. 233 */ 234 TALER_MERCHANT_POST_ORDERS_PAY_OPTION_END = 0, 235 236 /** 237 * Session identifier for session-bound payments. 238 */ 239 TALER_MERCHANT_POST_ORDERS_PAY_OPTION_SESSION_ID, 240 241 /** 242 * Wallet-specific data (JSON). 243 */ 244 TALER_MERCHANT_POST_ORDERS_PAY_OPTION_WALLET_DATA, 245 246 /** 247 * Used tokens (public form, for frontend mode). 248 */ 249 TALER_MERCHANT_POST_ORDERS_PAY_OPTION_USED_TOKENS, 250 251 /** 252 * Use tokens (private form, for wallet mode). 253 */ 254 TALER_MERCHANT_POST_ORDERS_PAY_OPTION_USE_TOKENS, 255 256 /** 257 * Output tokens (for wallet mode). 258 */ 259 TALER_MERCHANT_POST_ORDERS_PAY_OPTION_OUTPUT_TOKENS, 260 261 /** 262 * Output tokens as JSON array (for frontend mode). 263 */ 264 TALER_MERCHANT_POST_ORDERS_PAY_OPTION_OUTPUT_TOKENS_JSON, 265 266 /** 267 * Output donation receipts. 268 */ 269 TALER_MERCHANT_POST_ORDERS_PAY_OPTION_OUTPUT_DONAU, 270 271 /** 272 * Payment choice index (wallet mode). 273 */ 274 TALER_MERCHANT_POST_ORDERS_PAY_OPTION_CHOICE_INDEX 275 276 }; 277 278 279 /** 280 * Value for an option for the POST /orders/$ORDER_ID/pay request. 281 */ 282 struct TALER_MERCHANT_PostOrdersPayOptionValue 283 { 284 285 /** 286 * Type of the option being set. 287 */ 288 enum TALER_MERCHANT_PostOrdersPayOption option; 289 290 /** 291 * Specific option value. 292 */ 293 union 294 { 295 296 /** 297 * Value if @e option is 298 * #TALER_MERCHANT_POST_ORDERS_PAY_OPTION_SESSION_ID. 299 */ 300 const char *session_id; 301 302 /** 303 * Value if @e option is 304 * #TALER_MERCHANT_POST_ORDERS_PAY_OPTION_WALLET_DATA. 305 */ 306 const json_t *wallet_data; 307 308 /** 309 * Value if @e option is 310 * #TALER_MERCHANT_POST_ORDERS_PAY_OPTION_USED_TOKENS. 311 */ 312 struct 313 { 314 /** 315 * Length of @e tokens array 316 */ 317 unsigned int num; 318 const struct TALER_MERCHANT_PostOrdersPayUsedToken *tokens; 319 } used_tokens; 320 321 /** 322 * Value if @e option is 323 * #TALER_MERCHANT_POST_ORDERS_PAY_OPTION_USE_TOKENS. 324 */ 325 struct 326 { 327 /** 328 * Length of @e tokens array 329 */ 330 unsigned int num; 331 const struct TALER_MERCHANT_PostOrdersPayUseToken *tokens; 332 } use_tokens; 333 334 /** 335 * Value if @e option is 336 * #TALER_MERCHANT_POST_ORDERS_PAY_OPTION_OUTPUT_TOKENS. 337 */ 338 struct 339 { 340 /** 341 * Length of @e tokens array 342 */ 343 unsigned int num; 344 const struct TALER_MERCHANT_PostOrdersPayOutputToken *tokens; 345 } output_tokens; 346 347 /** 348 * Value if @e option is 349 * #TALER_MERCHANT_POST_ORDERS_PAY_OPTION_OUTPUT_TOKENS_JSON. 350 */ 351 json_t *output_tokens_json; 352 353 /** 354 * Value if @e option is 355 * #TALER_MERCHANT_POST_ORDERS_PAY_OPTION_OUTPUT_DONAU. 356 */ 357 struct 358 { 359 /** 360 * Base URL of the donau. 361 */ 362 const char *donau_base_url; 363 364 /** 365 * Array of blinded dontation receipts. 366 */ 367 const struct DONAU_BlindedUniqueDonorIdentifierKeyPair *bkps; 368 369 /** 370 * Length of @e bkps array 371 */ 372 size_t num_bkps; 373 374 /** 375 * Year for which the donation receipts are issued. 376 */ 377 uint64_t year; 378 } output_donau; 379 380 /** 381 * Value if @e option is 382 * #TALER_MERCHANT_POST_ORDERS_PAY_OPTION_CHOICE_INDEX. 383 */ 384 int choice_index; 385 386 } details; 387 388 }; 389 390 391 /** 392 * Handle for a POST /orders/$ORDER_ID/pay request. 393 */ 394 struct TALER_MERCHANT_PostOrdersPayHandle; 395 396 397 /** 398 * Response details for a POST /orders/$ORDER_ID/pay request. 399 */ 400 struct TALER_MERCHANT_PostOrdersPayResponse 401 { 402 403 /** 404 * HTTP response details. 405 */ 406 struct TALER_MERCHANT_HttpResponse hr; 407 408 /** 409 * Details depending on the HTTP status code. 410 */ 411 union 412 { 413 414 /** 415 * Details on #MHD_HTTP_OK. 416 */ 417 struct 418 { 419 420 /** 421 * Merchant signature confirming the payment. 422 */ 423 struct TALER_MerchantSignatureP merchant_sig; 424 425 /** 426 * POS confirmation string, or NULL if not applicable. 427 */ 428 const char *pos_confirmation; 429 430 /** 431 * Number of output tokens in @a tokens. 432 */ 433 unsigned int num_tokens; 434 435 /** 436 * Array of output tokens issued upon payment. 437 */ 438 struct TALER_MERCHANT_PostOrdersPayOutputToken *tokens; 439 440 } ok; 441 442 /** 443 * Details on #MHD_HTTP_CONFLICT. 444 * Set when a coin was already spent (insufficient funds) or 445 * the order was already fully paid. 446 */ 447 struct 448 { 449 450 /** 451 * Base URL of the exchange that reported the conflict, 452 * or NULL if not applicable. 453 */ 454 const char *exchange_url; 455 456 /** 457 * Taler error code from the exchange, if available. 458 */ 459 enum TALER_ErrorCode exchange_ec; 460 461 /** 462 * HTTP status code returned by the exchange, if available. 463 */ 464 unsigned int exchange_http_status; 465 466 } conflict; 467 468 /** 469 * Details on #MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS. 470 */ 471 struct 472 { 473 474 /** 475 * Number of exchange URLs in @a exchanges. 476 */ 477 unsigned int num_exchanges; 478 479 /** 480 * Array of exchange URLs that refused the payment for legal reasons. 481 */ 482 const char **exchanges; 483 484 } unavailable_for_legal_reasons; 485 486 /** 487 * Details on #MHD_HTTP_BAD_GATEWAY. 488 * The merchant's interaction with the exchange failed. 489 */ 490 struct 491 { 492 493 /** 494 * Base URL of the exchange that returned an error, 495 * or NULL if not available. 496 */ 497 const char *exchange_url; 498 499 /** 500 * Taler error code from the exchange, if available. 501 */ 502 enum TALER_ErrorCode exchange_ec; 503 504 /** 505 * HTTP status code returned by the exchange, if available. 506 */ 507 unsigned int exchange_http_status; 508 509 } bad_gateway; 510 511 } details; 512 513 }; 514 515 516 /** 517 * Terminate the list of the options. 518 * 519 * @return the terminating object 520 */ 521 #define TALER_MERCHANT_post_orders_pay_option_end_() \ 522 (const struct TALER_MERCHANT_PostOrdersPayOptionValue) \ 523 { \ 524 .option = TALER_MERCHANT_POST_ORDERS_PAY_OPTION_END \ 525 } 526 527 /** 528 * Set session identifier. 529 * 530 * @param s session ID 531 * @return representation of the option 532 */ 533 #define TALER_MERCHANT_post_orders_pay_option_session_id(s) \ 534 (const struct TALER_MERCHANT_PostOrdersPayOptionValue) \ 535 { \ 536 .option = TALER_MERCHANT_POST_ORDERS_PAY_OPTION_SESSION_ID, \ 537 .details.session_id = (s) \ 538 } 539 540 /** 541 * Set wallet-specific data. 542 * 543 * @param w wallet data JSON object 544 * @return representation of the option 545 */ 546 #define TALER_MERCHANT_post_orders_pay_option_wallet_data(w) \ 547 (const struct TALER_MERCHANT_PostOrdersPayOptionValue) \ 548 { \ 549 .option = TALER_MERCHANT_POST_ORDERS_PAY_OPTION_WALLET_DATA, \ 550 .details.wallet_data = (w) \ 551 } 552 553 /** 554 * Set used tokens (public form, for frontend mode). 555 * 556 * @param n number of tokens 557 * @param t array of used tokens 558 * @return representation of the option 559 */ 560 #define TALER_MERCHANT_post_orders_pay_option_used_tokens(n,t) \ 561 (const struct TALER_MERCHANT_PostOrdersPayOptionValue) \ 562 { \ 563 .option = TALER_MERCHANT_POST_ORDERS_PAY_OPTION_USED_TOKENS, \ 564 .details.used_tokens = { .num = (n), .tokens = (t) } \ 565 } 566 567 /** 568 * Set use tokens (private form, for wallet mode). 569 * 570 * @param n number of tokens 571 * @param t array of use tokens 572 * @return representation of the option 573 */ 574 #define TALER_MERCHANT_post_orders_pay_option_use_tokens(n,t) \ 575 (const struct TALER_MERCHANT_PostOrdersPayOptionValue) \ 576 { \ 577 .option = TALER_MERCHANT_POST_ORDERS_PAY_OPTION_USE_TOKENS, \ 578 .details.use_tokens = { .num = (n), .tokens = (t) } \ 579 } 580 581 /** 582 * Set output tokens (for wallet mode). 583 * 584 * @param n number of output tokens 585 * @param t array of output tokens 586 * @return representation of the option 587 */ 588 #define TALER_MERCHANT_post_orders_pay_option_output_tokens(n,t) \ 589 (const struct TALER_MERCHANT_PostOrdersPayOptionValue) \ 590 { \ 591 .option = TALER_MERCHANT_POST_ORDERS_PAY_OPTION_OUTPUT_TOKENS, \ 592 .details.output_tokens = { .num = (n), .tokens = (t) } \ 593 } 594 595 /** 596 * Set output tokens as JSON array (for frontend mode). 597 * 598 * @param j JSON array describing desired output tokens 599 * @return representation of the option 600 */ 601 #define TALER_MERCHANT_post_orders_pay_option_output_tokens_json(j) \ 602 (const struct TALER_MERCHANT_PostOrdersPayOptionValue) \ 603 { \ 604 .option = TALER_MERCHANT_POST_ORDERS_PAY_OPTION_OUTPUT_TOKENS_JSON, \ 605 .details.output_tokens_json = (j) \ 606 } 607 608 609 /** 610 * Set blinded donation receipts as output. 611 * 612 * @param u base URL of the selected Donau 613 * @param y year for which receipts are requested 614 * @param l length of the @a bkps array 615 * @param a array of blinded donation receipts 616 * @return representation of the option 617 */ 618 #define TALER_MERCHANT_post_orders_pay_option_output_donau(u,y,l,a) \ 619 (const struct TALER_MERCHANT_PostOrdersPayOptionValue) \ 620 { \ 621 .option = TALER_MERCHANT_POST_ORDERS_PAY_OPTION_OUTPUT_DONAU, \ 622 .details.output_donau.donau_base_url = (u), \ 623 .details.output_donau.bkps = (a), \ 624 .details.output_donau.num_bkps = (l), \ 625 .details.output_donau.year = (y) \ 626 } 627 628 /** 629 * Set payment choice index (wallet mode). 630 * Use -1 to indicate no choice (the default). 631 * 632 * @param i choice index 633 * @return representation of the option 634 */ 635 #define TALER_MERCHANT_post_orders_pay_option_choice_index(i) \ 636 (const struct TALER_MERCHANT_PostOrdersPayOptionValue) \ 637 { \ 638 .option = TALER_MERCHANT_POST_ORDERS_PAY_OPTION_CHOICE_INDEX, \ 639 .details.choice_index = (i) \ 640 } 641 642 643 /** 644 * Set the requested options for the operation. 645 * 646 * @param poph the request to set the options for 647 * @param num_options length of the @a options array 648 * @param options an array of options 649 * @return #GNUNET_OK on success, 650 * #GNUNET_NO on failure, 651 * #GNUNET_SYSERR on internal error 652 */ 653 enum GNUNET_GenericReturnValue 654 TALER_MERCHANT_post_orders_pay_set_options_ ( 655 struct TALER_MERCHANT_PostOrdersPayHandle *poph, 656 unsigned int num_options, 657 const struct TALER_MERCHANT_PostOrdersPayOptionValue *options); 658 659 660 /** 661 * Set the requested options for the operation. 662 * 663 * @param poph the request to set the options for 664 * @param ... the list of the options 665 * @return #GNUNET_OK on success, 666 * #GNUNET_NO on failure, 667 * #GNUNET_SYSERR on internal error 668 */ 669 #define TALER_MERCHANT_post_orders_pay_set_options(poph,...) \ 670 TALER_MERCHANT_post_orders_pay_set_options_ ( \ 671 poph, \ 672 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 673 ((const struct TALER_MERCHANT_PostOrdersPayOptionValue[]) \ 674 {__VA_ARGS__, TALER_MERCHANT_post_orders_pay_option_end_ () } \ 675 )) 676 677 678 /** 679 * Set up POST /orders/$ORDER_ID/pay operation in frontend mode 680 * (coins already signed by the wallet). 681 * Note that you must explicitly start the operation after 682 * possibly setting options. 683 * 684 * @param ctx the context 685 * @param url base URL of the merchant backend 686 * @param order_id identifier of the order to pay 687 * @param num_coins number of coins in @a coins 688 * @param coins array of coins to pay with (already signed) 689 * @return handle to operation 690 */ 691 struct TALER_MERCHANT_PostOrdersPayHandle * 692 TALER_MERCHANT_post_orders_pay_frontend_create ( 693 struct GNUNET_CURL_Context *ctx, 694 const char *url, 695 const char *order_id, 696 unsigned int num_coins, 697 const struct TALER_MERCHANT_PostOrdersPayPaidCoin coins[static num_coins]); 698 699 700 /** 701 * Set up POST /orders/$ORDER_ID/pay operation in wallet-internal mode 702 * (signing done internally). 703 * Note that you must explicitly start the operation after 704 * possibly setting options. 705 * 706 * @param ctx the context 707 * @param url base URL of the merchant backend 708 * @param order_id identifier of the order to pay 709 * @param h_contract_terms hash of the contract terms 710 * @param amount total payment amount 711 * @param max_fee maximum acceptable fee 712 * @param merchant_pub merchant public key 713 * @param merchant_sig merchant signature 714 * @param timestamp contract timestamp 715 * @param refund_deadline refund deadline 716 * @param pay_deadline payment deadline 717 * @param h_wire hash of the merchant wire details 718 * @param num_coins number of coins in @a coins 719 * @param coins array of coins with private keys 720 * @return handle to operation 721 */ 722 struct TALER_MERCHANT_PostOrdersPayHandle * 723 TALER_MERCHANT_post_orders_pay_create ( 724 struct GNUNET_CURL_Context *ctx, 725 const char *url, 726 const char *order_id, 727 const struct TALER_PrivateContractHashP *h_contract_terms, 728 const struct TALER_Amount *amount, 729 const struct TALER_Amount *max_fee, 730 const struct TALER_MerchantPublicKeyP *merchant_pub, 731 const struct TALER_MerchantSignatureP *merchant_sig, 732 struct GNUNET_TIME_Timestamp timestamp, 733 struct GNUNET_TIME_Timestamp refund_deadline, 734 struct GNUNET_TIME_Timestamp pay_deadline, 735 const struct TALER_MerchantWireHashP *h_wire, 736 unsigned int num_coins, 737 const struct TALER_MERCHANT_PostOrdersPayCoin coins[static num_coins]); 738 739 740 #ifndef TALER_MERCHANT_POST_ORDERS_PAY_RESULT_CLOSURE 741 /** 742 * Type of the closure used by 743 * the #TALER_MERCHANT_PostOrdersPayCallback. 744 */ 745 #define TALER_MERCHANT_POST_ORDERS_PAY_RESULT_CLOSURE void 746 #endif /* TALER_MERCHANT_POST_ORDERS_PAY_RESULT_CLOSURE */ 747 748 /** 749 * Callback for a POST /orders/$ORDER_ID/pay request. 750 * 751 * @param cls closure 752 * @param opr response details 753 */ 754 typedef void 755 (*TALER_MERCHANT_PostOrdersPayCallback)( 756 TALER_MERCHANT_POST_ORDERS_PAY_RESULT_CLOSURE *cls, 757 const struct TALER_MERCHANT_PostOrdersPayResponse *opr); 758 759 760 /** 761 * Start POST /orders/$ORDER_ID/pay operation. 762 * 763 * @param[in,out] poph operation to start 764 * @param cb function to call with the merchant's result 765 * @param cb_cls closure for @a cb 766 * @return status code, #TALER_EC_NONE on success 767 */ 768 enum TALER_ErrorCode 769 TALER_MERCHANT_post_orders_pay_start ( 770 struct TALER_MERCHANT_PostOrdersPayHandle *poph, 771 TALER_MERCHANT_PostOrdersPayCallback cb, 772 TALER_MERCHANT_POST_ORDERS_PAY_RESULT_CLOSURE *cb_cls); 773 774 775 /** 776 * Cancel POST /orders/$ORDER_ID/pay operation. This function must not be 777 * called by clients after the TALER_MERCHANT_PostOrdersPayCallback has 778 * been invoked (as in those cases it'll be called internally by the 779 * implementation already). 780 * 781 * @param[in] poph operation to cancel 782 */ 783 void 784 TALER_MERCHANT_post_orders_pay_cancel ( 785 struct TALER_MERCHANT_PostOrdersPayHandle *poph); 786 787 788 #endif /* _TALER_MERCHANT__POST_ORDERS_ORDER_ID_PAY_H */