get-kyc-check-H_NORMALIZED_PAYTO.h (10853B)
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 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/exchange/get-kyc-check-H_NORMALIZED_PAYTO.h 18 * @brief C interface for GET /kyc-check/$H_NORMALIZED_PAYTO 19 * @author Christian Grothoff 20 */ 21 #ifndef _TALER_EXCHANGE__GET_KYC_CHECK_H_NORMALIZED_PAYTO_H 22 #define _TALER_EXCHANGE__GET_KYC_CHECK_H_NORMALIZED_PAYTO_H 23 24 #include <taler/exchange/common.h> 25 26 /** 27 * KYC/AML status information about an account. 28 */ 29 struct TALER_EXCHANGE_AccountKycStatus 30 { 31 /** 32 * Current AML state for the target account. True if operations are not 33 * happening due to staff processing paperwork *or* due to legal 34 * requirements (so the client cannot do anything but wait). 35 */ 36 bool aml_review; 37 38 /** 39 * Length of the @e limits array. 40 */ 41 unsigned int limits_length; 42 43 /** 44 * Generation of this rule, matches a monotonically increasing 45 * table row in the exchange with KYC rules for this account. 46 */ 47 uint64_t rule_gen; 48 49 /** 50 * Array of (exposed) limits that apply to the account. 51 * Length in @e limits_length. 52 */ 53 const struct TALER_EXCHANGE_AccountLimit *limits; 54 55 /** 56 * Access token the user needs to start a KYC process. 57 */ 58 struct TALER_AccountAccessTokenP access_token; 59 60 /** 61 * Set if and only if the client must next accept the 62 * terms of service and KYC_SWAP_TOS_ACCEPTANCE is enabled. 63 * In this case, the value given is the ETag of the /terms 64 * that the customer must accept to proceed. If the customer 65 * already accepted these terms, the merchant backend will 66 * use this to signal the terms acceptance without requiring 67 * the user to again interact with it. 68 */ 69 const char *tos_required; 70 71 }; 72 73 74 /** 75 * Possible options we can set for the GET kyc-check request. 76 */ 77 enum TALER_EXCHANGE_GetKycCheckOption 78 { 79 /** 80 * End of list of options. 81 */ 82 TALER_EXCHANGE_GET_KYC_CHECK_OPTION_END = 0, 83 84 /** 85 * Latest known AML/KYC rule generation, for long polling. 86 * The server will only respond when the rule generation exceeds this value. 87 * Default is 0 (respond immediately). 88 */ 89 TALER_EXCHANGE_GET_KYC_CHECK_OPTION_KNOWN_RULE_GEN, 90 91 /** 92 * Long polling target: what KYC state to wait for. 93 * Default is to respond immediately. 94 */ 95 TALER_EXCHANGE_GET_KYC_CHECK_OPTION_LPT, 96 97 /** 98 * How long to wait for an answer including long polling. 99 * Default is zero (no long polling). 100 */ 101 TALER_EXCHANGE_GET_KYC_CHECK_OPTION_TIMEOUT 102 103 }; 104 105 106 /** 107 * Value for an option for the GET kyc-check request. 108 */ 109 struct TALER_EXCHANGE_GetKycCheckOptionValue 110 { 111 /** 112 * Type of the option being set. 113 */ 114 enum TALER_EXCHANGE_GetKycCheckOption option; 115 116 /** 117 * Specific option value. 118 */ 119 union 120 { 121 /** 122 * Value if @e option is TALER_EXCHANGE_GET_KYC_CHECK_OPTION_KNOWN_RULE_GEN. 123 */ 124 uint64_t known_rule_gen; 125 126 /** 127 * Value if @e option is TALER_EXCHANGE_GET_KYC_CHECK_OPTION_LPT. 128 */ 129 enum TALER_EXCHANGE_KycLongPollTarget lpt; 130 131 /** 132 * Value if @e option is TALER_EXCHANGE_GET_KYC_CHECK_OPTION_TIMEOUT. 133 */ 134 struct GNUNET_TIME_Relative timeout; 135 136 } details; 137 138 }; 139 140 141 /** 142 * Handle for an operation to GET /kyc-check/$H_NORMALIZED_PAYTO. 143 */ 144 struct TALER_EXCHANGE_GetKycCheckHandle; 145 146 147 /** 148 * Set up GET /kyc-check/$H_NORMALIZED_PAYTO operation. 149 * Note that you must explicitly start the operation after 150 * possibly setting options. 151 * 152 * @param ctx the context 153 * @param url base URL of the exchange 154 * @param h_payto hash of the account the KYC check is about 155 * @param pk private key to authorize the request with 156 * @return handle to operation 157 */ 158 struct TALER_EXCHANGE_GetKycCheckHandle * 159 TALER_EXCHANGE_get_kyc_check_create ( 160 struct GNUNET_CURL_Context *ctx, 161 const char *url, 162 const struct TALER_NormalizedPaytoHashP *h_payto, 163 const union TALER_AccountPrivateKeyP *pk); 164 165 166 /** 167 * Terminate the list of options. 168 * 169 * @return the terminating object of struct TALER_EXCHANGE_GetKycCheckOptionValue 170 */ 171 #define TALER_EXCHANGE_get_kyc_check_option_end_() \ 172 (const struct TALER_EXCHANGE_GetKycCheckOptionValue) \ 173 { \ 174 .option = TALER_EXCHANGE_GET_KYC_CHECK_OPTION_END \ 175 } 176 177 /** 178 * Set the latest known rule generation for long polling. 179 * 180 * @param g latest known AML decision / rule generation 181 * @return representation of the option as a struct TALER_EXCHANGE_GetKycCheckOptionValue 182 */ 183 #define TALER_EXCHANGE_get_kyc_check_option_known_rule_gen(g) \ 184 (const struct TALER_EXCHANGE_GetKycCheckOptionValue) \ 185 { \ 186 .option = TALER_EXCHANGE_GET_KYC_CHECK_OPTION_KNOWN_RULE_GEN, \ 187 .details.known_rule_gen = (g) \ 188 } 189 190 /** 191 * Set the long-polling target KYC state to wait for. 192 * 193 * @param t long poll target 194 * @return representation of the option as a struct TALER_EXCHANGE_GetKycCheckOptionValue 195 */ 196 #define TALER_EXCHANGE_get_kyc_check_option_lpt(t) \ 197 (const struct TALER_EXCHANGE_GetKycCheckOptionValue) \ 198 { \ 199 .option = TALER_EXCHANGE_GET_KYC_CHECK_OPTION_LPT, \ 200 .details.lpt = (t) \ 201 } 202 203 /** 204 * Set long-polling timeout. 205 * 206 * @param t how long to wait for an answer 207 * @return representation of the option as a struct TALER_EXCHANGE_GetKycCheckOptionValue 208 */ 209 #define TALER_EXCHANGE_get_kyc_check_option_timeout(t) \ 210 (const struct TALER_EXCHANGE_GetKycCheckOptionValue) \ 211 { \ 212 .option = TALER_EXCHANGE_GET_KYC_CHECK_OPTION_TIMEOUT, \ 213 .details.timeout = (t) \ 214 } 215 216 217 /** 218 * Set the requested options for the operation. 219 * 220 * If any option fails, other options may or may not be applied. 221 * 222 * @param gkch the request to set the options for 223 * @param num_options length of the @a options array 224 * @param options an array of options 225 * @return #GNUNET_OK on success, 226 * #GNUNET_NO on failure, 227 * #GNUNET_SYSERR on internal error 228 */ 229 enum GNUNET_GenericReturnValue 230 TALER_EXCHANGE_get_kyc_check_set_options_ ( 231 struct TALER_EXCHANGE_GetKycCheckHandle *gkch, 232 unsigned int num_options, 233 const struct TALER_EXCHANGE_GetKycCheckOptionValue *options); 234 235 236 /** 237 * Set the requested options for the operation. 238 * 239 * If any option fails, other options may or may not be applied. 240 * 241 * It should be used with helpers that create required options, for example: 242 * 243 * TALER_EXCHANGE_get_kyc_check_set_options ( 244 * gkch, 245 * TALER_EXCHANGE_get_kyc_check_option_known_rule_gen (last_gen), 246 * TALER_EXCHANGE_get_kyc_check_option_lpt (TALER_EXCHANGE_YNMS_NONE), 247 * TALER_EXCHANGE_get_kyc_check_option_timeout (timeout)); 248 * 249 * @param gkch the request to set the options for 250 * @param ... the list of options, each created by a 251 * TALER_EXCHANGE_get_kyc_check_option_NAME(VALUE) helper 252 * @return #GNUNET_OK on success, 253 * #GNUNET_NO on failure, 254 * #GNUNET_SYSERR on internal error 255 */ 256 #define TALER_EXCHANGE_get_kyc_check_set_options(gkch,...) \ 257 TALER_EXCHANGE_get_kyc_check_set_options_ ( \ 258 gkch, \ 259 TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 260 ((const struct TALER_EXCHANGE_GetKycCheckOptionValue[]) \ 261 {__VA_ARGS__, TALER_EXCHANGE_get_kyc_check_option_end_ () } \ 262 )) 263 264 265 /** 266 * KYC status response. 267 */ 268 struct TALER_EXCHANGE_GetKycCheckResponse 269 { 270 /** 271 * HTTP response data. 272 */ 273 struct TALER_EXCHANGE_HttpResponse hr; 274 275 /** 276 * Details depending on @e hr.http_status. 277 */ 278 union 279 { 280 /** 281 * KYC is satisfied; affirmation returned by the exchange. 282 * @e hr.http_status is #MHD_HTTP_OK. 283 */ 284 struct TALER_EXCHANGE_AccountKycStatus ok; 285 286 /** 287 * KYC is required before the operation can proceed. 288 * @e hr.http_status is #MHD_HTTP_ACCEPTED. 289 */ 290 struct TALER_EXCHANGE_AccountKycStatus accepted; 291 292 /** 293 * Request was forbidden (wrong authorization key). 294 * @e hr.http_status is #MHD_HTTP_FORBIDDEN. 295 */ 296 struct 297 { 298 /** 299 * Account public key that would have been authorized. 300 */ 301 union TALER_AccountPublicKeyP expected_account_pub; 302 303 } forbidden; 304 305 } details; 306 307 }; 308 309 310 #ifndef TALER_EXCHANGE_GET_KYC_CHECK_RESULT_CLOSURE 311 /** 312 * Type of the closure used by 313 * the #TALER_EXCHANGE_GetKycCheckCallback. 314 */ 315 #define TALER_EXCHANGE_GET_KYC_CHECK_RESULT_CLOSURE void 316 #endif /* TALER_EXCHANGE_GET_KYC_CHECK_RESULT_CLOSURE */ 317 318 /** 319 * Type of the function that receives the result of a 320 * GET /kyc-check/$H_NORMALIZED_PAYTO request. 321 * 322 * @param cls closure 323 * @param result result returned by the HTTP server 324 */ 325 typedef void 326 (*TALER_EXCHANGE_GetKycCheckCallback)( 327 TALER_EXCHANGE_GET_KYC_CHECK_RESULT_CLOSURE *cls, 328 const struct TALER_EXCHANGE_GetKycCheckResponse *result); 329 330 331 /** 332 * Start GET /kyc-check/$H_NORMALIZED_PAYTO operation. 333 * 334 * @param[in,out] gkch operation to start 335 * @param cb function to call with the exchange's result 336 * @param cb_cls closure for @a cb 337 * @return status code, #TALER_EC_NONE on success 338 */ 339 enum TALER_ErrorCode 340 TALER_EXCHANGE_get_kyc_check_start ( 341 struct TALER_EXCHANGE_GetKycCheckHandle *gkch, 342 TALER_EXCHANGE_GetKycCheckCallback cb, 343 TALER_EXCHANGE_GET_KYC_CHECK_RESULT_CLOSURE *cb_cls); 344 345 346 /** 347 * Cancel GET /kyc-check/$H_NORMALIZED_PAYTO operation. This function must 348 * not be called by clients after the TALER_EXCHANGE_GetKycCheckCallback has 349 * been invoked (as in those cases it'll be called internally by the 350 * implementation already). 351 * 352 * @param[in] gkch operation to cancel 353 */ 354 void 355 TALER_EXCHANGE_get_kyc_check_cancel ( 356 struct TALER_EXCHANGE_GetKycCheckHandle *gkch); 357 358 359 #endif /* _TALER_EXCHANGE__GET_KYC_CHECK_H_NORMALIZED_PAYTO_H */