taler_bank_service.h (29982B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2015-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 Affero General Public License as published by the Free Software 7 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 Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 */ 16 /** 17 * @file include/taler/taler_bank_service.h 18 * @brief C interface of libtalerbank, a C library to use the Taler Wire gateway HTTP API 19 * See https://docs.taler.net/core/api-wire.html 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_BANK_SERVICE_H 23 #define _TALER_BANK_SERVICE_H 24 25 #include <jansson.h> 26 #include <gnunet/gnunet_curl_lib.h> 27 #include <taler/taler_util.h> 28 #include <taler/taler_error_codes.h> 29 30 /** 31 * Version of the Bank API, in hex. 32 * Thus 1.5.0-0 = 0x01050000. 33 */ 34 #define TALER_BANK_SERVICE_API_VERSION 0x01050000 35 36 /** 37 * Authentication method types. 38 */ 39 enum TALER_BANK_AuthenticationMethod 40 { 41 42 /** 43 * No authentication. 44 */ 45 TALER_BANK_AUTH_NONE, 46 47 /** 48 * Basic authentication with cleartext username and password. 49 */ 50 TALER_BANK_AUTH_BASIC, 51 52 /** 53 * Bearer token authentication. 54 */ 55 TALER_BANK_AUTH_BEARER, 56 }; 57 58 59 /** 60 * Information used to authenticate to the bank. 61 */ 62 struct TALER_BANK_AuthenticationData 63 { 64 65 /** 66 * Base URL we use to talk to the wire gateway, 67 * which talks to the bank for us. 68 */ 69 char *wire_gateway_url; 70 71 /** 72 * Base URL including "/accounts/$USERNAME/" to use 73 * to talk to the core bank API. Useful to get a more 74 * specific access token instead of using basic authentication 75 * the whole time. Optional, can be NULL (as we do not 76 * require the core bank API to actually always be available). 77 */ 78 char *core_bank_url; 79 80 /** 81 * Which authentication method should we use? 82 */ 83 enum TALER_BANK_AuthenticationMethod method; 84 85 /** 86 * Further details as per @e method. 87 */ 88 union 89 { 90 91 /** 92 * Details for #TALER_BANK_AUTH_BASIC. 93 */ 94 struct 95 { 96 /** 97 * Username to use. 98 */ 99 char *username; 100 101 /** 102 * Password to use. 103 */ 104 char *password; 105 } basic; 106 107 /** 108 * Details for #TALER_BANK_AUTH_BEARER. 109 */ 110 struct 111 { 112 /** 113 * Token to use. 114 */ 115 char *token; 116 117 } bearer; 118 119 } details; 120 121 }; 122 123 124 /* ********************* /accounts/$ACC/token *********************** */ 125 126 127 /** 128 * @brief A /accounts/$USERNAME/token request handle 129 */ 130 struct TALER_BANK_AccountTokenHandle; 131 132 133 /** 134 * Response details for a token request. 135 */ 136 struct TALER_BANK_AccountTokenResponse 137 { 138 139 /** 140 * HTTP status. 141 */ 142 unsigned int http_status; 143 144 /** 145 * Taler error code, #TALER_EC_NONE on success. 146 */ 147 enum TALER_ErrorCode ec; 148 149 /** 150 * Full response, NULL if body was not in JSON format. 151 */ 152 const json_t *response; 153 154 /** 155 * Details returned depending on the @e http_status. 156 */ 157 union 158 { 159 160 /** 161 * Details if status was #MHD_HTTP_OK 162 */ 163 struct 164 { 165 /** 166 * Access token to use. 167 */ 168 const char *access_token; 169 170 /** 171 * time when the token will expire. 172 */ 173 struct GNUNET_TIME_Timestamp expiration; 174 175 } ok; 176 177 } details; 178 179 }; 180 181 /** 182 * Callbacks of this type are used to return the result of submitting 183 * a request for an access token to the bank. 184 * 185 * @param cls closure 186 * @param atr response details 187 */ 188 typedef void 189 (*TALER_BANK_AccountTokenCallback) ( 190 void *cls, 191 const struct TALER_BANK_AccountTokenResponse *atr); 192 193 194 /** 195 * Possible access scopes for bank bearer tokens. 196 */ 197 enum TALER_BANK_TokenScope 198 { 199 200 /** 201 * Only grant read-access to the account. Useful for 202 * human auditors. 203 */ 204 TALER_BANK_TOKEN_SCOPE_READONLY, 205 206 /** 207 * Grants full read-write access to the account. Useful 208 * for the SPA. Strongly recommended to limit validity 209 * duration. 210 */ 211 TALER_BANK_TOKEN_SCOPE_READWRITE, 212 213 /** 214 * Only grant (read-access to) the revenue API. Useful for 215 * merchant backends. 216 */ 217 TALER_BANK_TOKEN_SCOPE_REVENUE, 218 219 /** 220 * Only grant access to the wire gateway API. Useful for 221 * the exchange. 222 */ 223 TALER_BANK_TOKEN_SCOPE_WIREGATEWAY 224 225 }; 226 227 228 /** 229 * Requests an access token from the bank. Note that this 230 * request is against the CORE banking API and not done by 231 * exchange code itself (but used to get access tokens when testing). 232 * 233 * @param ctx curl context for the event loop 234 * @param auth authentication data to send to the bank 235 * @param scope requested token scope 236 * @param refreshable true if the token should be refreshable 237 * @param description human-readable token description (for token management) 238 * @param duration requested token validity, use zero for default 239 * @param res_cb the callback to call when the final result for this request is available 240 * @param res_cb_cls closure for the above callback 241 * @return NULL 242 * if the inputs are invalid (i.e. invalid amount) or internal errors. 243 * In this case, the callback is not called. 244 */ 245 struct TALER_BANK_AccountTokenHandle * 246 TALER_BANK_account_token ( 247 struct GNUNET_CURL_Context *ctx, 248 const struct TALER_BANK_AuthenticationData *auth, 249 enum TALER_BANK_TokenScope scope, 250 bool refreshable, 251 const char *description, 252 struct GNUNET_TIME_Relative duration, 253 TALER_BANK_AccountTokenCallback res_cb, 254 void *res_cb_cls); 255 256 257 /** 258 * Cancel an add incoming operation. This function cannot be used on a 259 * request handle if a response is already served for it. 260 * 261 * @param[in] ath the admin add incoming request handle 262 */ 263 void 264 TALER_BANK_account_token_cancel ( 265 struct TALER_BANK_AccountTokenHandle *ath); 266 267 268 /* ********************* /admin/add-incoming *********************** */ 269 270 271 /** 272 * @brief A /admin/add-incoming Handle 273 */ 274 struct TALER_BANK_AdminAddIncomingHandle; 275 276 277 /** 278 * Response details for a history request. 279 */ 280 struct TALER_BANK_AdminAddIncomingResponse 281 { 282 283 /** 284 * HTTP status. 285 */ 286 unsigned int http_status; 287 288 /** 289 * Taler error code, #TALER_EC_NONE on success. 290 */ 291 enum TALER_ErrorCode ec; 292 293 /** 294 * Full response, NULL if body was not in JSON format. 295 */ 296 const json_t *response; 297 298 /** 299 * Details returned depending on the @e http_status. 300 */ 301 union 302 { 303 304 /** 305 * Details if status was #MHD_HTTP_OK 306 */ 307 struct 308 { 309 /** 310 * unique ID of the wire transfer in the bank's records 311 */ 312 uint64_t serial_id; 313 314 /** 315 * time when the transaction was made. 316 */ 317 struct GNUNET_TIME_Timestamp timestamp; 318 319 } ok; 320 321 } details; 322 323 }; 324 325 /** 326 * Callbacks of this type are used to return the result of submitting 327 * a request to transfer funds to the exchange. 328 * 329 * @param cls closure 330 * @param air response details 331 */ 332 typedef void 333 (*TALER_BANK_AdminAddIncomingCallback) ( 334 void *cls, 335 const struct TALER_BANK_AdminAddIncomingResponse *air); 336 337 338 /** 339 * Perform a wire transfer from some account to the exchange to fill a 340 * reserve. Note that this API is usually only used for testing (with 341 * fakebank) and thus may not be accessible in a production setting. 342 * 343 * @param ctx curl context for the event loop 344 * @param auth authentication data to send to the bank 345 * @param reserve_pub wire transfer subject for the transfer 346 * @param amount amount that is to be deposited 347 * @param debit_account account to deposit from (payto URI, but used as 'payfrom') 348 * @param res_cb the callback to call when the final result for this request is available 349 * @param res_cb_cls closure for the above callback 350 * @return NULL 351 * if the inputs are invalid (i.e. invalid amount) or internal errors. 352 * In this case, the callback is not called. 353 */ 354 struct TALER_BANK_AdminAddIncomingHandle * 355 TALER_BANK_admin_add_incoming ( 356 struct GNUNET_CURL_Context *ctx, 357 const struct TALER_BANK_AuthenticationData *auth, 358 const struct TALER_ReservePublicKeyP *reserve_pub, 359 const struct TALER_Amount *amount, 360 const struct TALER_FullPayto debit_account, 361 TALER_BANK_AdminAddIncomingCallback res_cb, 362 void *res_cb_cls); 363 364 365 /** 366 * Cancel an add incoming operation. This function cannot be used on a 367 * request handle if a response is already served for it. 368 * 369 * @param[in] aai the admin add incoming request handle 370 */ 371 void 372 TALER_BANK_admin_add_incoming_cancel ( 373 struct TALER_BANK_AdminAddIncomingHandle *aai); 374 375 376 /** 377 * @brief A /admin/add-kycauth Handle 378 */ 379 struct TALER_BANK_AdminAddKycauthHandle; 380 381 382 /** 383 * Response details for a history request. 384 */ 385 struct TALER_BANK_AdminAddKycauthResponse 386 { 387 388 /** 389 * HTTP status. 390 */ 391 unsigned int http_status; 392 393 /** 394 * Taler error code, #TALER_EC_NONE on success. 395 */ 396 enum TALER_ErrorCode ec; 397 398 /** 399 * Full response, NULL if body was not in JSON format. 400 */ 401 const json_t *response; 402 403 /** 404 * Details returned depending on the @e http_status. 405 */ 406 union 407 { 408 409 /** 410 * Details if status was #MHD_HTTP_OK 411 */ 412 struct 413 { 414 /** 415 * unique ID of the wire transfer in the bank's records 416 */ 417 uint64_t serial_id; 418 419 /** 420 * time when the transaction was made. 421 */ 422 struct GNUNET_TIME_Timestamp timestamp; 423 424 } ok; 425 426 } details; 427 428 }; 429 430 /** 431 * Callbacks of this type are used to return the result of submitting 432 * a request to transfer funds to the exchange. 433 * 434 * @param cls closure 435 * @param air response details 436 */ 437 typedef void 438 (*TALER_BANK_AdminAddKycauthCallback) ( 439 void *cls, 440 const struct TALER_BANK_AdminAddKycauthResponse *air); 441 442 443 /** 444 * Perform a wire transfer from some account to the exchange to register a 445 * public key for KYC authentication of the origin account. Note that this 446 * API is usually only used for testing (with fakebank) and thus may not be 447 * accessible in a production setting. 448 * 449 * @param ctx curl context for the event loop 450 * @param auth authentication data to send to the bank 451 * @param account_pub wire transfer subject for the transfer 452 * @param amount amount that is to be deposited 453 * @param debit_account account to deposit from (payto URI, but used as 'payfrom') 454 * @param res_cb the callback to call when the final result for this request is available 455 * @param res_cb_cls closure for the above callback 456 * @return NULL 457 * if the inputs are invalid (i.e. invalid amount) or internal errors. 458 * In this case, the callback is not called. 459 */ 460 struct TALER_BANK_AdminAddKycauthHandle * 461 TALER_BANK_admin_add_kycauth ( 462 struct GNUNET_CURL_Context *ctx, 463 const struct TALER_BANK_AuthenticationData *auth, 464 const union TALER_AccountPublicKeyP *account_pub, 465 const struct TALER_Amount *amount, 466 const struct TALER_FullPayto debit_account, 467 TALER_BANK_AdminAddKycauthCallback res_cb, 468 void *res_cb_cls); 469 470 471 /** 472 * Cancel an add kycauth operation. This function cannot be used on a 473 * request handle if a response is already served for it. 474 * 475 * @param[in] aai the admin add kycauth request handle 476 */ 477 void 478 TALER_BANK_admin_add_kycauth_cancel ( 479 struct TALER_BANK_AdminAddKycauthHandle *aai); 480 481 482 /* ********************* /transfer *********************** */ 483 484 /** 485 * Prepare for execution of a wire transfer from the exchange to some 486 * merchant. 487 * 488 * @param destination_account_payto_uri payto:// URL identifying where to send the money 489 * @param amount amount to transfer, already rounded 490 * @param exchange_base_url base URL of this exchange (included in subject 491 * to facilitate use of tracking API by merchant backend) 492 * @param wtid wire transfer identifier to use 493 * @param extra_wire_transfer_subject additional meta data to include 494 * @param[out] buf set to transaction data to persist, NULL on error 495 * @param[out] buf_size set to number of bytes in @a buf, 0 on error 496 */ 497 void 498 TALER_BANK_prepare_transfer ( 499 const struct TALER_FullPayto destination_account_payto_uri, 500 const struct TALER_Amount *amount, 501 const char *exchange_base_url, 502 const struct TALER_WireTransferIdentifierRawP *wtid, 503 const char *extra_wire_transfer_subject, 504 void **buf, 505 size_t *buf_size); 506 507 508 /** 509 * Handle for active wire transfer. 510 */ 511 struct TALER_BANK_TransferHandle; 512 513 514 /** 515 * Response details for a history request. 516 */ 517 struct TALER_BANK_TransferResponse 518 { 519 520 /** 521 * HTTP status. 522 */ 523 unsigned int http_status; 524 525 /** 526 * Taler error code, #TALER_EC_NONE on success. 527 */ 528 enum TALER_ErrorCode ec; 529 530 /** 531 * Full response, NULL if body was not in JSON format. 532 */ 533 const json_t *response; 534 535 /** 536 * Details returned depending on the @e http_status. 537 */ 538 union 539 { 540 541 /** 542 * Details if status was #MHD_HTTP_OK 543 */ 544 struct 545 { 546 547 548 /** 549 * unique ID of the wire transfer in the bank's records 550 */ 551 uint64_t row_id; 552 553 /** 554 * when did the transaction go into effect 555 */ 556 struct GNUNET_TIME_Timestamp timestamp; 557 558 } ok; 559 } details; 560 }; 561 562 563 /** 564 * Function called with the result from the execute step. 565 * 566 * @param cls closure 567 * @param tr response details 568 */ 569 typedef void 570 (*TALER_BANK_TransferCallback)( 571 void *cls, 572 const struct TALER_BANK_TransferResponse *tr); 573 574 575 /** 576 * Execute a wire transfer from the exchange to some merchant. 577 * 578 * @param ctx context for HTTP interaction 579 * @param auth authentication data to authenticate with the bank 580 * @param buf buffer with the prepared execution details 581 * @param buf_size number of bytes in @a buf 582 * @param cc function to call upon success 583 * @param cc_cls closure for @a cc 584 * @return NULL on error 585 */ 586 struct TALER_BANK_TransferHandle * 587 TALER_BANK_transfer ( 588 struct GNUNET_CURL_Context *ctx, 589 const struct TALER_BANK_AuthenticationData *auth, 590 const void *buf, 591 size_t buf_size, 592 TALER_BANK_TransferCallback cc, 593 void *cc_cls); 594 595 596 /** 597 * Abort execution of a wire transfer. For example, because we are shutting 598 * down. Note that if an execution is aborted, it may or may not still 599 * succeed. 600 * 601 * The caller MUST run #TALER_BANK_transfer() again for the same request as 602 * soon as possible, to ensure that the request either ultimately succeeds or 603 * ultimately fails. Until this has been done, the transaction is in limbo 604 * (i.e. may or may not have been committed). 605 * 606 * This function cannot be used on a request handle if a response is already 607 * served for it. 608 * 609 * @param[in] th handle of the wire transfer request to cancel 610 */ 611 void 612 TALER_BANK_transfer_cancel ( 613 struct TALER_BANK_TransferHandle *th); 614 615 616 /* ********************* /history/incoming *********************** */ 617 618 /** 619 * Different types of wire transfers that might be 620 * credited to an exchange account. 621 */ 622 enum TALER_BANK_CreditType 623 { 624 /** 625 * Common wire transfer into a reserve account. 626 */ 627 TALER_BANK_CT_RESERVE, 628 629 /** 630 * KYC authentication wire transfer with an account 631 * public key. 632 */ 633 TALER_BANK_CT_KYCAUTH, 634 635 /** 636 * WAD transfer between exchanges. 637 */ 638 TALER_BANK_CT_WAD 639 640 }; 641 642 /** 643 * Handle for querying the bank for transactions 644 * made to the exchange. 645 */ 646 struct TALER_BANK_CreditHistoryHandle; 647 648 /** 649 * Details about a wire transfer to the exchange. 650 */ 651 struct TALER_BANK_CreditDetails 652 { 653 654 /** 655 * Type of the wire transfer. 656 */ 657 enum TALER_BANK_CreditType type; 658 659 /** 660 * Serial ID of the wire transfer. 661 */ 662 uint64_t serial_id; 663 664 /** 665 * Amount that was transferred 666 */ 667 struct TALER_Amount amount; 668 669 /** 670 * Fee paid by the creditor. 671 */ 672 struct TALER_Amount credit_fee; 673 674 /** 675 * Time of the the transfer 676 */ 677 struct GNUNET_TIME_Timestamp execution_date; 678 679 /** 680 * payto://-URL of the source account that send the funds. 681 */ 682 struct TALER_FullPayto debit_account_uri; 683 684 /** 685 * Details that depend on the @e type. 686 */ 687 union 688 { 689 690 /** 691 * Details for @e type #TALER_BANK_CT_RESERVE. 692 */ 693 struct 694 { 695 696 /** 697 * Reserve public key encoded in the wire transfer subject. 698 */ 699 struct TALER_ReservePublicKeyP reserve_pub; 700 701 } reserve; 702 703 /** 704 * Details for @e type #TALER_BANK_CT_KYCAUTH. 705 */ 706 struct 707 { 708 709 /** 710 * Public key to associate with the owner of the 711 * origin bank account. 712 */ 713 union TALER_AccountPublicKeyP account_pub; 714 715 } kycauth; 716 717 /** 718 * Details for @e type #TALER_BANK_CT_WAD. 719 */ 720 struct 721 { 722 723 /** 724 * WAD identifier for the transfer. 725 */ 726 struct TALER_WadIdentifierP wad_id; 727 728 /** 729 * Base URL of the exchange originating the transfer. 730 */ 731 const char *origin_exchange_url; 732 } wad; 733 734 } details; 735 736 }; 737 738 739 /** 740 * Response details for a history request. 741 */ 742 struct TALER_BANK_CreditHistoryResponse 743 { 744 745 /** 746 * HTTP status. Note that #MHD_HTTP_OK and #MHD_HTTP_NO_CONTENT are both 747 * successful replies, but @e details will only contain @e success information 748 * if this is set to #MHD_HTTP_OK. 749 */ 750 unsigned int http_status; 751 752 /** 753 * Taler error code, #TALER_EC_NONE on success. 754 */ 755 enum TALER_ErrorCode ec; 756 757 /** 758 * Full response, NULL if body was not in JSON format. 759 */ 760 const json_t *response; 761 762 /** 763 * Details returned depending on the @e http_status. 764 */ 765 union 766 { 767 768 /** 769 * Details if status was #MHD_HTTP_OK 770 */ 771 struct 772 { 773 774 /** 775 * payto://-URL of the target account that received the funds. 776 */ 777 struct TALER_FullPayto credit_account_uri; 778 779 /** 780 * Array of transactions received. 781 */ 782 const struct TALER_BANK_CreditDetails *details; 783 784 /** 785 * Length of the @e details array. 786 */ 787 unsigned int details_length; 788 789 } ok; 790 791 } details; 792 793 }; 794 795 796 /** 797 * Callbacks of this type are used to serve the result of asking 798 * the bank for the credit transaction history. 799 * 800 * @param cls closure 801 * @param reply details about the response 802 */ 803 typedef void 804 (*TALER_BANK_CreditHistoryCallback)( 805 void *cls, 806 const struct TALER_BANK_CreditHistoryResponse *reply); 807 808 809 /** 810 * Request the wire credit history of an exchange's bank account. 811 * 812 * @param ctx curl context for the event loop 813 * @param auth authentication data to use 814 * @param start_row from which row on do we want to get results, use UINT64_MAX for the latest; exclusive 815 * @param num_results how many results do we want; negative numbers to go into the past, 816 * positive numbers to go into the future starting at @a start_row; 817 * must not be zero. 818 * @param timeout how long the client is willing to wait for more results 819 * (only useful if @a num_results is positive) 820 * @param hres_cb the callback to call with the transaction history 821 * @param hres_cb_cls closure for the above callback 822 * @return NULL 823 * if the inputs are invalid (i.e. zero value for @e num_results). 824 * In this case, the callback is not called. 825 */ 826 struct TALER_BANK_CreditHistoryHandle * 827 TALER_BANK_credit_history ( 828 struct GNUNET_CURL_Context *ctx, 829 const struct TALER_BANK_AuthenticationData *auth, 830 uint64_t start_row, 831 int64_t num_results, 832 struct GNUNET_TIME_Relative timeout, 833 TALER_BANK_CreditHistoryCallback hres_cb, 834 void *hres_cb_cls); 835 836 837 /** 838 * Cancel an history request. This function cannot be used on a request 839 * handle if the last response (anything with a status code other than 840 * 200) is already served for it. 841 * 842 * @param[in] hh the history request handle 843 */ 844 void 845 TALER_BANK_credit_history_cancel ( 846 struct TALER_BANK_CreditHistoryHandle *hh); 847 848 849 /* ********************* /history/outgoing *********************** */ 850 851 /** 852 * Handle for querying the bank for transactions 853 * made from the exchange to merchants. 854 */ 855 struct TALER_BANK_DebitHistoryHandle; 856 857 /** 858 * Details about a wire transfer made by the exchange 859 * to a merchant. 860 */ 861 struct TALER_BANK_DebitDetails 862 { 863 /** 864 * Serial ID of the wire transfer. 865 */ 866 uint64_t serial_id; 867 868 /** 869 * Amount that was transferred 870 */ 871 struct TALER_Amount amount; 872 873 /** 874 * Time of the the transfer 875 */ 876 struct GNUNET_TIME_Timestamp execution_date; 877 878 /** 879 * Wire transfer identifier used by the exchange. 880 */ 881 struct TALER_WireTransferIdentifierRawP wtid; 882 883 /** 884 * Exchange's base URL as given in the wire transfer. 885 */ 886 const char *exchange_base_url; 887 888 /** 889 * payto://-URI of the target account that received the funds. 890 */ 891 struct TALER_FullPayto credit_account_uri; 892 893 }; 894 895 896 /** 897 * Response details for a history request. 898 */ 899 struct TALER_BANK_DebitHistoryResponse 900 { 901 902 /** 903 * HTTP status. Note that #MHD_HTTP_OK and #MHD_HTTP_NO_CONTENT are both 904 * successful replies, but @e details will only contain @e success information 905 * if this is set to #MHD_HTTP_OK. 906 */ 907 unsigned int http_status; 908 909 /** 910 * Taler error code, #TALER_EC_NONE on success. 911 */ 912 enum TALER_ErrorCode ec; 913 914 /** 915 * Full response, NULL if body was not in JSON format. 916 */ 917 const json_t *response; 918 919 /** 920 * Details returned depending on the @e http_status. 921 */ 922 union 923 { 924 925 /** 926 * Details if status was #MHD_HTTP_OK 927 */ 928 struct 929 { 930 931 /** 932 * payto://-URI of the source account that send the funds. 933 */ 934 struct TALER_FullPayto debit_account_uri; 935 936 /** 937 * Array of transactions initiated. 938 */ 939 const struct TALER_BANK_DebitDetails *details; 940 941 /** 942 * Length of the @e details array. 943 */ 944 unsigned int details_length; 945 946 } ok; 947 948 } details; 949 950 }; 951 952 953 /** 954 * Callbacks of this type are used to serve the result of asking 955 * the bank for the debit transaction history. 956 * 957 * @param cls closure 958 * @param reply details about the response 959 */ 960 typedef void 961 (*TALER_BANK_DebitHistoryCallback)( 962 void *cls, 963 const struct TALER_BANK_DebitHistoryResponse *reply); 964 965 966 /** 967 * Request the wire credit history of an exchange's bank account. 968 * 969 * @param ctx curl context for the event loop 970 * @param auth authentication data to use 971 * @param start_row from which row on do we want to get results, use UINT64_MAX for the latest; exclusive 972 * @param num_results how many results do we want; negative numbers to go into the past, 973 * positive numbers to go into the future starting at @a start_row; 974 * must not be zero. 975 * @param timeout how long the client is willing to wait for more results 976 * (only useful if @a num_results is positive) 977 * @param hres_cb the callback to call with the transaction history 978 * @param hres_cb_cls closure for the above callback 979 * @return NULL 980 * if the inputs are invalid (i.e. zero value for @e num_results). 981 * In this case, the callback is not called. 982 */ 983 struct TALER_BANK_DebitHistoryHandle * 984 TALER_BANK_debit_history ( 985 struct GNUNET_CURL_Context *ctx, 986 const struct TALER_BANK_AuthenticationData *auth, 987 uint64_t start_row, 988 int64_t num_results, 989 struct GNUNET_TIME_Relative timeout, 990 TALER_BANK_DebitHistoryCallback hres_cb, 991 void *hres_cb_cls); 992 993 994 /** 995 * Cancel an history request. This function cannot be used on a request 996 * handle if the last response (anything with a status code other than 997 * 200) is already served for it. 998 * 999 * @param[in] hh the history request handle 1000 */ 1001 void 1002 TALER_BANK_debit_history_cancel ( 1003 struct TALER_BANK_DebitHistoryHandle *hh); 1004 1005 1006 /* ******************** Convenience functions **************** */ 1007 1008 1009 /** 1010 * Convenience method for parsing configuration section with bank 1011 * authentication data. 1012 * 1013 * @param cfg configuration to parse 1014 * @param section the section with the configuration data 1015 * @param[out] auth set to the configuration data found 1016 * @return #GNUNET_OK on success 1017 */ 1018 enum GNUNET_GenericReturnValue 1019 TALER_BANK_auth_parse_cfg ( 1020 const struct GNUNET_CONFIGURATION_Handle *cfg, 1021 const char *section, 1022 struct TALER_BANK_AuthenticationData *auth); 1023 1024 1025 /** 1026 * Free memory inside of @a auth (but not @a auth itself). 1027 * Dual to #TALER_BANK_auth_parse_cfg(). 1028 * 1029 * @param[in,out] auth authentication data to free 1030 */ 1031 void 1032 TALER_BANK_auth_free ( 1033 struct TALER_BANK_AuthenticationData *auth); 1034 1035 1036 /* ********************* /registration *********************** */ 1037 1038 1039 /** 1040 * Wire transfer subject formats supported by the registration endpoint. 1041 */ 1042 enum TALER_BANK_SubjectFormat 1043 { 1044 1045 /** 1046 * Simple format: the full key is used as the wire transfer subject. 1047 * No entropy constraints apply. 1048 */ 1049 TALER_BANK_SUBJECT_FORMAT_SIMPLE, 1050 1051 /** 1052 * URI format: a prepared-payment confirmation URI is returned. 1053 */ 1054 TALER_BANK_SUBJECT_FORMAT_URI, 1055 1056 /** 1057 * Swiss QR-bill format: a 27-digit QR Reference Number is returned. 1058 */ 1059 TALER_BANK_SUBJECT_FORMAT_CH_QR_BILL 1060 1061 }; 1062 1063 1064 /** 1065 * @brief A /registration Handle 1066 */ 1067 struct TALER_BANK_RegistrationHandle; 1068 1069 1070 /** 1071 * Union holding the subject payload returned by /registration, 1072 * discriminated by @e TALER_BANK_SubjectFormat. 1073 */ 1074 struct TALER_BANK_TransferSubject 1075 { 1076 1077 /** 1078 * Which variant is set. 1079 */ 1080 enum TALER_BANK_SubjectFormat format; 1081 1082 /** 1083 * Fields that depend on @e format. 1084 */ 1085 union 1086 { 1087 1088 /** 1089 * Details for #TALER_BANK_SUBJECT_FORMAT_SIMPLE. 1090 */ 1091 struct 1092 { 1093 1094 /** 1095 * Amount to transfer. 1096 */ 1097 struct TALER_Amount credit_amount; 1098 1099 /** 1100 * Encoded string containing the key or derived short subject. 1101 */ 1102 char *subject; 1103 1104 } simple; 1105 1106 /** 1107 * Details for #TALER_BANK_SUBJECT_FORMAT_URI. 1108 */ 1109 struct 1110 { 1111 1112 /** 1113 * Amount to transfer. 1114 */ 1115 struct TALER_Amount credit_amount; 1116 1117 /** 1118 * Prepared-payment confirmation URI. Should already 1119 * be a payto:// URI. 1120 */ 1121 char *uri; 1122 1123 } uri; 1124 1125 /** 1126 * Details for #TALER_BANK_SUBJECT_FORMAT_CH_QR_BILL. 1127 */ 1128 struct 1129 { 1130 1131 /** 1132 * Amount to transfer. 1133 */ 1134 struct TALER_Amount credit_amount; 1135 1136 /** 1137 * 27-digit QR Reference Number (NUL-terminated string). 1138 * Put as "ch_qrr" into the payto URI. 1139 */ 1140 char *qr_reference_number; 1141 1142 } ch_qr_bill; 1143 1144 } details; 1145 1146 }; 1147 1148 1149 /** 1150 * Make a deep copy of @a src to @a dst. 1151 * 1152 * @param[out] dst copy to initialize 1153 * @param src source to copy from 1154 */ 1155 void 1156 TALER_BANK_transfer_subject_copy ( 1157 struct TALER_BANK_TransferSubject *dst, 1158 const struct TALER_BANK_TransferSubject *src); 1159 1160 1161 /** 1162 * Free memory allocated inside of @a subject, but not @a subject itself 1163 * 1164 * @param[in,out] subject memory to free 1165 */ 1166 void 1167 TALER_BANK_transfer_subject_free ( 1168 struct TALER_BANK_TransferSubject *subject); 1169 1170 1171 /** 1172 * Response details for a /registration POST request. 1173 */ 1174 struct TALER_BANK_RegistrationResponse 1175 { 1176 1177 /** 1178 * HTTP status. 1179 */ 1180 unsigned int http_status; 1181 1182 /** 1183 * Taler error code, #TALER_EC_NONE on success. 1184 */ 1185 enum TALER_ErrorCode ec; 1186 1187 /** 1188 * Full response, NULL if body was not in JSON format. 1189 */ 1190 const json_t *response; 1191 1192 /** 1193 * Details returned depending on the @e http_status. 1194 */ 1195 union 1196 { 1197 1198 /** 1199 * Details if status was #MHD_HTTP_OK. 1200 */ 1201 struct 1202 { 1203 1204 /** 1205 * The wire transfer subject to communicate to the user. 1206 */ 1207 const struct TALER_BANK_TransferSubject *subjects; 1208 1209 /** 1210 * Length of the @e subjects array. 1211 */ 1212 size_t num_subjects; 1213 1214 /** 1215 * Expiration time of this registration. The registration is 1216 * extended each time the corresponding wire transfer is used. 1217 * After expiration, the short subject may be re-assigned to a 1218 * different key. 1219 */ 1220 struct GNUNET_TIME_Timestamp expiration; 1221 1222 } ok; 1223 1224 } details; 1225 1226 }; 1227 1228 1229 /** 1230 * Callback called with the result of a POST /registration request. 1231 * 1232 * @param cls closure 1233 * @param rr response details 1234 */ 1235 typedef void 1236 (*TALER_BANK_RegistrationCallback) ( 1237 void *cls, 1238 const struct TALER_BANK_RegistrationResponse *rr); 1239 1240 1241 /** 1242 * Register a public key for wire transfer use, obtaining an appropriate 1243 * wire transfer subject linked to the key. 1244 * 1245 * If the same @a authorization_pub is already registered and has not yet 1246 * expired, the endpoint is idempotent and returns the same subject again. 1247 * 1248 * @param ctx curl context for the event loop 1249 * @param base_url base URL for the registration API 1250 * @param credit_account account to receive the wire transfer 1251 * @param credit_amount amount to be credited in the wire transfer 1252 * @param type transfer type, either reserve withdrawal or KYC authentication 1253 * @param account_pub account public key to associate with the registration 1254 * @param authorization_priv private key used to sign authorization requests; 1255 * the corresponding public key that will be encoded in the subject; 1256 * if @a recurrent is true this key may be reused across transfers 1257 * @param recurrent true if @a authorization_pub will be reused for 1258 * recurring transfers (disables bouncing on reuse) 1259 * @param res_cb callback invoked with the final result 1260 * @param res_cb_cls closure for @a res_cb 1261 * @return NULL if inputs are invalid or an internal error occurred; 1262 * in this case @a res_cb is never called 1263 */ 1264 struct TALER_BANK_RegistrationHandle * 1265 TALER_BANK_registration ( 1266 struct GNUNET_CURL_Context *ctx, 1267 const char *base_url, 1268 const struct TALER_FullPayto *credit_account, 1269 const struct TALER_Amount *credit_amount, 1270 enum TALER_BankRegistrationType type, 1271 const union TALER_AccountPublicKeyP *account_pub, 1272 const struct TALER_PreparedTransferAuthorizationPrivateKeyP * 1273 authorization_priv, 1274 bool recurrent, 1275 TALER_BANK_RegistrationCallback res_cb, 1276 void *res_cb_cls); 1277 1278 1279 /** 1280 * Cancel a /registration request. This function must not be called 1281 * once the response callback has already been invoked. 1282 * 1283 * @param[in] rh the registration request handle to cancel 1284 */ 1285 void 1286 TALER_BANK_registration_cancel ( 1287 struct TALER_BANK_RegistrationHandle *rh); 1288 1289 1290 #endif /* _TALER_BANK_SERVICE_H */