get-private-kyc.h (15806B)
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 src/include/taler/merchant/get-private-kyc.h 19 * @brief C interface for the GET /private/kyc (and /management/instances/$INSTANCE/kyc) endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__GET_PRIVATE_KYC_H 23 #define _TALER_MERCHANT__GET_PRIVATE_KYC_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Possible options we can set for the GET /private/kyc request. 30 */ 31 enum TALER_MERCHANT_GetPrivateKycOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_END = 0, 37 38 /** 39 * Hash of the wire account to check, or NULL for all. 40 */ 41 TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_H_WIRE, 42 43 /** 44 * URL of the exchange to check with, or NULL for any. 45 */ 46 TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_EXCHANGE_URL, 47 48 /** 49 * Long-poll target (what status to wait for). 50 */ 51 TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_LPT, 52 53 /** 54 * Long polling timeout. 55 */ 56 TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_TIMEOUT, 57 58 /** 59 * Instance ID for management mode (GET /management/instances/$INSTANCE/kyc). 60 * If not set, uses the private endpoint (GET /private/kyc). 61 */ 62 TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_INSTANCE_ID, 63 64 /** 65 * Long-poll status filter: only return when some account reaches 66 * this status. String value (since v25). 67 */ 68 TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_LP_STATUS, 69 70 /** 71 * Long-poll negated status filter: only return when some account 72 * no longer matches this status. String value (since v25). 73 */ 74 TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_LP_NOT_STATUS, 75 76 /** 77 * Long-poll ETag to suppress responses that have not changed. 78 * ShortHashCode value (since v25). 79 */ 80 TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_LP_NOT_ETAG 81 82 }; 83 84 85 /** 86 * Value for an option for the GET /private/kyc request. 87 */ 88 struct TALER_MERCHANT_GetPrivateKycOptionValue 89 { 90 91 /** 92 * Type of the option being set. 93 */ 94 enum TALER_MERCHANT_GetPrivateKycOption option; 95 96 /** 97 * Specific option value. 98 */ 99 union 100 { 101 102 /** 103 * Value if @e option is 104 * #TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_H_WIRE. 105 */ 106 const struct TALER_MerchantWireHashP *h_wire; 107 108 /** 109 * Value if @e option is 110 * #TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_EXCHANGE_URL. 111 */ 112 const char *exchange_url; 113 114 /** 115 * Value if @e option is 116 * #TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_LPT. 117 */ 118 enum TALER_EXCHANGE_KycLongPollTarget lpt; 119 120 /** 121 * Value if @e option is 122 * #TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_TIMEOUT. 123 */ 124 struct GNUNET_TIME_Relative timeout; 125 126 /** 127 * Value if @e option is 128 * #TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_INSTANCE_ID. 129 * If set, the management endpoint 130 * /management/instances/$INSTANCE/kyc is used instead of 131 * /private/kyc. 132 */ 133 const char *instance_id; 134 135 /** 136 * Value if @e option is 137 * #TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_LP_STATUS. 138 */ 139 const char *lp_status; 140 141 /** 142 * Value if @e option is 143 * #TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_LP_NOT_STATUS. 144 */ 145 const char *lp_not_status; 146 147 /** 148 * Value if @e option is 149 * #TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_LP_NOT_ETAG. 150 */ 151 const struct GNUNET_ShortHashCode *lp_not_etag; 152 153 } details; 154 155 }; 156 157 158 /** 159 * Handle for a GET /private/kyc (or /management/instances/$INSTANCE/kyc) request. 160 */ 161 struct TALER_MERCHANT_GetPrivateKycHandle; 162 163 164 /** 165 * Set up GET /private/kyc operation. 166 * Note that you must explicitly start the operation after 167 * possibly setting options. By default, uses the /private/kyc 168 * endpoint; set the INSTANCE_ID option to use the management 169 * endpoint instead. 170 * 171 * @param ctx the context 172 * @param url base URL of the merchant backend 173 * @return handle to operation 174 */ 175 struct TALER_MERCHANT_GetPrivateKycHandle * 176 TALER_MERCHANT_get_private_kyc_create ( 177 struct GNUNET_CURL_Context *ctx, 178 const char *url); 179 180 181 /** 182 * Terminate the list of the options. 183 * 184 * @return the terminating object of struct TALER_MERCHANT_GetPrivateKycOptionValue 185 */ 186 #define TALER_MERCHANT_get_private_kyc_option_end_() \ 187 (const struct TALER_MERCHANT_GetPrivateKycOptionValue) \ 188 { \ 189 .option = TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_END \ 190 } 191 192 /** 193 * Set hash of the wire account to check. 194 * 195 * @param h pointer to the wire hash to filter by 196 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateKycOptionValue 197 */ 198 #define TALER_MERCHANT_get_private_kyc_option_h_wire(h) \ 199 (const struct TALER_MERCHANT_GetPrivateKycOptionValue) \ 200 { \ 201 .option = TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_H_WIRE, \ 202 .details.h_wire = (h) \ 203 } 204 205 /** 206 * Set exchange URL to check with. 207 * 208 * @param u exchange URL to filter by 209 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateKycOptionValue 210 */ 211 #define TALER_MERCHANT_get_private_kyc_option_exchange_url(u) \ 212 (const struct TALER_MERCHANT_GetPrivateKycOptionValue) \ 213 { \ 214 .option = TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_EXCHANGE_URL, \ 215 .details.exchange_url = (u) \ 216 } 217 218 /** 219 * Set long-poll target. 220 * 221 * @param t long-poll target to wait for 222 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateKycOptionValue 223 */ 224 #define TALER_MERCHANT_get_private_kyc_option_lpt(t) \ 225 (const struct TALER_MERCHANT_GetPrivateKycOptionValue) \ 226 { \ 227 .option = TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_LPT, \ 228 .details.lpt = (t) \ 229 } 230 231 /** 232 * Set long polling timeout. 233 * 234 * @param t timeout to use 235 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateKycOptionValue 236 */ 237 #define TALER_MERCHANT_get_private_kyc_option_timeout(t) \ 238 (const struct TALER_MERCHANT_GetPrivateKycOptionValue) \ 239 { \ 240 .option = TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_TIMEOUT, \ 241 .details.timeout = (t) \ 242 } 243 244 /** 245 * Set instance ID for management mode. When set, the request uses 246 * the /management/instances/$INSTANCE/kyc endpoint instead of 247 * /private/kyc. 248 * 249 * @param id instance identifier 250 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateKycOptionValue 251 */ 252 #define TALER_MERCHANT_get_private_kyc_option_instance_id(id) \ 253 (const struct TALER_MERCHANT_GetPrivateKycOptionValue) \ 254 { \ 255 .option = TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_INSTANCE_ID, \ 256 .details.instance_id = (id) \ 257 } 258 259 /** 260 * Set long-poll status filter. 261 * 262 * @param s status string to wait for 263 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateKycOptionValue 264 */ 265 #define TALER_MERCHANT_get_private_kyc_option_lp_status(s) \ 266 (const struct TALER_MERCHANT_GetPrivateKycOptionValue) \ 267 { \ 268 .option = TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_LP_STATUS, \ 269 .details.lp_status = (s) \ 270 } 271 272 /** 273 * Set long-poll negated status filter. 274 * 275 * @param s status string to negate 276 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateKycOptionValue 277 */ 278 #define TALER_MERCHANT_get_private_kyc_option_lp_not_status(s) \ 279 (const struct TALER_MERCHANT_GetPrivateKycOptionValue) \ 280 { \ 281 .option = TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_LP_NOT_STATUS, \ 282 .details.lp_not_status = (s) \ 283 } 284 285 /** 286 * Set long-poll ETag to suppress unchanged responses. 287 * 288 * @param e pointer to the short hash code ETag 289 * @return representation of the option as a struct TALER_MERCHANT_GetPrivateKycOptionValue 290 */ 291 #define TALER_MERCHANT_get_private_kyc_option_lp_not_etag(e) \ 292 (const struct TALER_MERCHANT_GetPrivateKycOptionValue) \ 293 { \ 294 .option = TALER_MERCHANT_GET_PRIVATE_KYC_OPTION_LP_NOT_ETAG, \ 295 .details.lp_not_etag = (e) \ 296 } 297 298 299 /** 300 * Set the requested options for the operation. 301 * 302 * If any option fail other options may be or may be not applied. 303 * 304 * @param kyc the request to set the options for 305 * @param num_options length of the @a options array 306 * @param options an array of options 307 * @return #GNUNET_OK on success, 308 * #GNUNET_NO on failure, 309 * #GNUNET_SYSERR on internal error 310 */ 311 enum GNUNET_GenericReturnValue 312 TALER_MERCHANT_get_private_kyc_set_options_ ( 313 struct TALER_MERCHANT_GetPrivateKycHandle *kyc, 314 unsigned int num_options, 315 const struct TALER_MERCHANT_GetPrivateKycOptionValue *options); 316 317 318 /** 319 * Set the requested options for the operation. 320 * 321 * If any option fail other options may be or may be not applied. 322 * 323 * It should be used with helpers that create required options, for example: 324 * 325 * TALER_MERCHANT_get_private_kyc_set_options ( 326 * kyc, 327 * TALER_MERCHANT_get_private_kyc_option_exchange_url ( 328 * "https://exchange.example.com/"), 329 * TALER_MERCHANT_get_private_kyc_option_timeout ( 330 * GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_SECONDS, 30))); 331 * 332 * @param kyc the request to set the options for 333 * @param ... the list of the options, each option must be created 334 * by helpers TALER_MERCHANT_get_private_kyc_option_NAME(VALUE) 335 * @return #GNUNET_OK on success, 336 * #GNUNET_NO on failure, 337 * #GNUNET_SYSERR on internal error 338 */ 339 #define TALER_MERCHANT_get_private_kyc_set_options(kyc,...) \ 340 TALER_MERCHANT_get_private_kyc_set_options_ ( \ 341 kyc, \ 342 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 343 ((const struct TALER_MERCHANT_GetPrivateKycOptionValue[]) \ 344 {__VA_ARGS__, TALER_MERCHANT_get_private_kyc_option_end_ () } \ 345 )) 346 347 348 /** 349 * Information about KYC actions the merchant still must perform. 350 */ 351 struct TALER_MERCHANT_GetPrivateKycRedirectDetail 352 { 353 354 /** 355 * Access token the user needs to start a KYC process, 356 * all zero if a KYC auth transfer must be made first. 357 */ 358 struct TALER_AccountAccessTokenP access_token; 359 360 /** 361 * Base URL of the exchange this is about. 362 */ 363 const char *exchange_url; 364 365 /** 366 * Our bank wire account this is about. 367 */ 368 struct TALER_FullPayto payto_uri; 369 370 /** 371 * Array of length @e limits_length with (exposed) limits that apply to the 372 * account. 373 */ 374 const struct TALER_EXCHANGE_AccountLimit *limits; 375 376 /** 377 * Array of payto://-URIs with instructions for wire 378 * transfers to perform a KYC auth wire transfer for 379 * the given account. Needed if @e access_token is zero 380 * and @e limits are to be passed. 381 */ 382 struct TALER_FullPayto *payto_kycauths; 383 384 /** 385 * Length of the @e limits array. 386 */ 387 unsigned int limits_length; 388 389 /** 390 * Length of the @e payto_kycauths array. 391 */ 392 unsigned int pkycauth_length; 393 394 /** 395 * HTTP status code returned by the exchange when we asked for 396 * information about the KYC status. 397 * 0 if there was no response at all. 398 */ 399 unsigned int exchange_http_status; 400 401 /** 402 * Error code indicating errors the exchange 403 * returned, or #TALER_EC_NONE for none. 404 */ 405 enum TALER_ErrorCode exchange_code; 406 407 /** 408 * Set to true if @e access_token was not given. 409 */ 410 bool no_access_token; 411 412 /** 413 * Hash of the wire account this entry is about. 414 */ 415 struct TALER_MerchantWireHashP h_wire; 416 417 /** 418 * KYC status string, or NULL if not provided. 419 */ 420 const char *status; 421 422 /** 423 * Currency used by the exchange, or NULL if not provided. 424 */ 425 const char *exchange_currency; 426 427 /** 428 * Set to true if the merchant backend could not 429 * get the exchanges ``/keys`` and thus could not 430 * determine default limits or determine an 431 * @e auth_conflict. 432 */ 433 bool no_keys; 434 435 /** 436 * Set to true if the given account cannot do KYC at the given exchange 437 * because no wire method exists that could be used to do the KYC auth wire 438 * transfer. 439 */ 440 bool auth_conflict; 441 442 }; 443 444 445 /** 446 * Response details for a KYC status request. 447 */ 448 struct TALER_MERCHANT_GetPrivateKycResponse 449 { 450 451 /** 452 * HTTP response details. 453 */ 454 struct TALER_MERCHANT_HttpResponse hr; 455 456 /** 457 * Details depending on the HTTP status code. 458 */ 459 union 460 { 461 462 /** 463 * Details on #MHD_HTTP_OK. 464 */ 465 struct 466 { 467 468 /** 469 * Number of KYC redirect details in @a kycs. 470 */ 471 unsigned int kycs_length; 472 473 /** 474 * Array of KYC redirect details for accounts requiring KYC. 475 */ 476 const struct TALER_MERCHANT_GetPrivateKycRedirectDetail *kycs; 477 478 } ok; 479 480 } details; 481 482 }; 483 484 485 #ifndef TALER_MERCHANT_GET_PRIVATE_KYC_RESULT_CLOSURE 486 /** 487 * Type of the closure used by 488 * the #TALER_MERCHANT_GetPrivateKycCallback. 489 */ 490 #define TALER_MERCHANT_GET_PRIVATE_KYC_RESULT_CLOSURE void 491 #endif /* TALER_MERCHANT_GET_PRIVATE_KYC_RESULT_CLOSURE */ 492 493 /** 494 * Callback for a KYC status request. 495 * 496 * @param cls closure 497 * @param kr response details 498 */ 499 typedef void 500 (*TALER_MERCHANT_GetPrivateKycCallback)( 501 TALER_MERCHANT_GET_PRIVATE_KYC_RESULT_CLOSURE *cls, 502 const struct TALER_MERCHANT_GetPrivateKycResponse *kr); 503 504 505 /** 506 * Start GET /private/kyc (or /management/instances/$INSTANCE/kyc) operation. 507 * 508 * @param[in,out] kyc operation to start 509 * @param cb function to call with the merchant's result 510 * @param cb_cls closure for @a cb 511 * @return status code, #TALER_EC_NONE on success 512 */ 513 enum TALER_ErrorCode 514 TALER_MERCHANT_get_private_kyc_start ( 515 struct TALER_MERCHANT_GetPrivateKycHandle *kyc, 516 TALER_MERCHANT_GetPrivateKycCallback cb, 517 TALER_MERCHANT_GET_PRIVATE_KYC_RESULT_CLOSURE *cb_cls); 518 519 520 /** 521 * Cancel GET /private/kyc operation. This function must not be 522 * called by clients after the TALER_MERCHANT_GetPrivateKycCallback 523 * has been invoked (as in those cases it'll be called internally by 524 * the implementation already). 525 * 526 * @param[in] kyc operation to cancel 527 */ 528 void 529 TALER_MERCHANT_get_private_kyc_cancel ( 530 struct TALER_MERCHANT_GetPrivateKycHandle *kyc); 531 532 533 #endif /* _TALER_MERCHANT__GET_PRIVATE_KYC_H */