diff options
Diffstat (limited to 'src/include/taler_merchant_service.h')
| -rw-r--r-- | src/include/taler_merchant_service.h | 3019 |
1 files changed, 1930 insertions, 1089 deletions
diff --git a/src/include/taler_merchant_service.h b/src/include/taler_merchant_service.h index e413a7c6..057c9eff 100644 --- a/src/include/taler_merchant_service.h +++ b/src/include/taler_merchant_service.h @@ -1,6 +1,6 @@ /* This file is part of TALER - Copyright (C) 2014-2022 Taler Systems SA + Copyright (C) 2014-2024 Taler Systems SA TALER is free software; you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software @@ -16,6 +16,8 @@ /** * @file taler_merchant_service.h * @brief C interface of libtalermerchant, a C library to use merchant's HTTP API + * This library is not thread-safe, all APIs must only be used from a single thread. + * This library calls abort() if it runs out of memory. Be aware of these limitations. * @author Christian Grothoff * @author Marcello Stanisci * @author Priscilla HUANG @@ -29,6 +31,11 @@ #include <gnunet/gnunet_curl_lib.h> #include <jansson.h> +/** + * Library version (in hex) for compatibility tests. + */ +#define TALER_MERCHANT_SERVICE_VERSION 0x00100000 + /** * General information about the HTTP response we obtained @@ -211,7 +218,7 @@ struct TALER_MERCHANT_RefundUriData * @param[out] parse_data data extracted from the URI. Must be free'd. * @return #GNUNET_SYSERR if @e refund_uri is malformed, #GNUNET_OK otherwise. */ -int +enum GNUNET_GenericReturnValue TALER_MERCHANT_parse_refund_uri ( const char *refund_uri, struct TALER_MERCHANT_RefundUriData *parse_data); @@ -288,7 +295,8 @@ enum TALER_MERCHANT_VersionCompatibility struct TALER_MERCHANT_ConfigInformation { /** - * Currency used/supported by the merchant. + * Default currency of the merchant. See cspecs + * for all currencies supported by the merchant. */ const char *currency; @@ -304,19 +312,96 @@ struct TALER_MERCHANT_ConfigInformation /** + * Information about an exchange the merchant backend trusts. + */ +struct TALER_MERCHANT_ExchangeConfigInfo +{ + /** + * Base URL of the exchange REST API. + */ + const char *base_url; + + /** + * Currency for which the merchant is configured to + * trust the exchange. + */ + const char *currency; + + /** + * Master public key of the exchange. + */ + struct TALER_MasterPublicKeyP master_pub; + +}; + +/** + * Response to /config request. + */ +struct TALER_MERCHANT_ConfigResponse +{ + /** + * HTTP response. + */ + struct TALER_MERCHANT_HttpResponse hr; + + /** + * Status-dependent details. + */ + union + { + /** + * Information returned on #MHD_HTTP_OK. + */ + struct + { + + /** + * basic information about the merchant + */ + struct TALER_MERCHANT_ConfigInformation ci; + + /** + * protocol compatibility information + */ + enum TALER_MERCHANT_VersionCompatibility compat; + + /** + * Length of the @e cspecs array. + */ + unsigned int num_cspecs; + + /** + * Array with rendering specifications for the currencies + * supported by this merchant backend. + */ + const struct TALER_CurrencySpecification *cspecs; + + /** + * Length of the @e exchanges array. + */ + unsigned int num_exchanges; + + /** + * Array details about exchanges trusted + * by this merchant backend. + */ + const struct TALER_MERCHANT_ExchangeConfigInfo *exchanges; + + } ok; + } details; +}; + + +/** * Function called with information about the merchant. * * @param cls closure - * @param hr HTTP response data - * @param ci basic information about the merchant - * @param compat protocol compatibility information + * @param cr response data */ typedef void (*TALER_MERCHANT_ConfigCallback) ( void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - const struct TALER_MERCHANT_ConfigInformation *ci, - enum TALER_MERCHANT_VersionCompatibility compat); + const struct TALER_MERCHANT_ConfigResponse *cr); /** @@ -338,17 +423,18 @@ struct TALER_MERCHANT_ConfigGetHandle; * @return the config check handle; NULL upon error */ struct TALER_MERCHANT_ConfigGetHandle * -TALER_MERCHANT_config_get (struct GNUNET_CURL_Context *ctx, - const char *backend_url, - TALER_MERCHANT_ConfigCallback config_cb, - void *config_cb_cls); +TALER_MERCHANT_config_get ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + TALER_MERCHANT_ConfigCallback config_cb, + void *config_cb_cls); /** * Cancel /config request. Must not be called by clients after * the callback was invoked. * - * @param vgh request to cancel. + * @param[in] vgh request to cancel. */ void TALER_MERCHANT_config_get_cancel (struct TALER_MERCHANT_ConfigGetHandle *vgh); @@ -382,7 +468,12 @@ struct TALER_MERCHANT_InstanceInformation * JSON array of payment targets (strings) supported by this backend * instance. */ - json_t *payment_targets; + const json_t *payment_targets; + + /** + * User type for the instance. + */ + enum TALER_KYCLOGIC_KycUserType ut; }; @@ -394,19 +485,47 @@ struct TALER_MERCHANT_InstancesGetHandle; /** + * Response to a GET /instances request. + */ +struct TALER_MERCHANT_InstancesGetResponse +{ + /** + * HTTP response data + */ + struct TALER_MERCHANT_HttpResponse hr; + + union + { + /** + * Data returned on #MHD_HTTP_OK status. + */ + struct + { + /** + * length of the @e iis array + */ + unsigned int iis_length; + + /** + * array with instance information of length @e iis_length + */ + const struct TALER_MERCHANT_InstanceInformation *iis; + } ok; + } details; + +}; + + +/** * Function called with the result of the GET /instances operation. * * @param cls closure - * @param hr HTTP response data - * @param iis_length length of the @a iis array - * @param iis array with instance information of length @a iis_length + * @param igr response data */ typedef void (*TALER_MERCHANT_InstancesGetCallback)( void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - unsigned int iis_length, - const struct TALER_MERCHANT_InstanceInformation iis[]); + const struct TALER_MERCHANT_InstancesGetResponse *igr); /** @@ -422,10 +541,11 @@ typedef void * @return the instances handle; NULL upon error */ struct TALER_MERCHANT_InstancesGetHandle * -TALER_MERCHANT_instances_get (struct GNUNET_CURL_Context *ctx, - const char *backend_url, - TALER_MERCHANT_InstancesGetCallback instances_cb, - void *instances_cb_cls); +TALER_MERCHANT_instances_get ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + TALER_MERCHANT_InstancesGetCallback instances_cb, + void *instances_cb_cls); /** @@ -446,7 +566,7 @@ struct TALER_MERCHANT_InstancesPostHandle; /** - * Function called with the result of the GET /instances/$ID operation. + * Function called with the result of the POST /instances/$ID operation. * * @param cls closure * @param hr HTTP response data @@ -463,14 +583,11 @@ typedef void * @param ctx the context * @param backend_url HTTP base URL for the backend * @param instance_id identity of the instance to get information about - * @param accounts_length how many bank accounts this instance has - * @param payto_uris URIs of the bank accounts of the merchant instance * @param name name of the merchant instance + * @param ut user type of the merchant instance * @param address physical address of the merchant instance * @param jurisdiction jurisdiction of the merchant instance - * @param default_max_wire_fee default maximum wire fee merchant is willing to fully pay - * @param default_wire_fee_amortization default amortization factor for excess wire fees - * @param default_max_deposit_fee default maximum deposit fee merchant is willing to pay + * @param use_stefan use STEFAN curve for acceptable fees * @param default_wire_transfer_delay default wire transfer delay merchant will ask for * @param default_pay_delay default validity period for offers merchant makes * @param auth_token authentication token to use for access control, NULL for external auth; MUST follow RFC 8959 @@ -484,14 +601,11 @@ TALER_MERCHANT_instances_post ( struct GNUNET_CURL_Context *ctx, const char *backend_url, const char *instance_id, - unsigned int accounts_length, - const char *payto_uris[], const char *name, + enum TALER_KYCLOGIC_KycUserType ut, const json_t *address, const json_t *jurisdiction, - const struct TALER_Amount *default_max_wire_fee, - uint32_t default_wire_fee_amortization, - const struct TALER_Amount *default_max_deposit_fee, + bool use_stefan, struct GNUNET_TIME_Relative default_wire_transfer_delay, struct GNUNET_TIME_Relative default_pay_delay, const char *auth_token, @@ -536,14 +650,11 @@ typedef void * or base URL of an instance if @a instance_id is NULL) * @param instance_id identity of the instance to modify information about; NULL * if the instance is identified as part of the @a backend_url - * @param accounts_length length of the @a accounts array - * @param payto_uris URIs of the bank accounts of the merchant instance * @param name name of the merchant instance + * @param ut user type of the merchant instance * @param address physical address of the merchant instance * @param jurisdiction jurisdiction of the merchant instance - * @param default_max_wire_fee default maximum wire fee merchant is willing to fully pay - * @param default_wire_fee_amortization default amortization factor for excess wire fees - * @param default_max_deposit_fee default maximum deposit fee merchant is willing to pay + * @param use_stefan use STEFAN curve for acceptable fees * @param default_wire_transfer_delay default wire transfer delay merchant will ask for * @param default_pay_delay default validity period for offers merchant makes * @param cb function to call with the @@ -556,14 +667,11 @@ TALER_MERCHANT_instance_patch ( struct GNUNET_CURL_Context *ctx, const char *backend_url, const char *instance_id, - unsigned int accounts_length, - const char *payto_uris[], const char *name, + enum TALER_KYCLOGIC_KycUserType ut, const json_t *address, const json_t *jurisdiction, - const struct TALER_Amount *default_max_wire_fee, - uint32_t default_wire_fee_amortization, - const struct TALER_Amount *default_max_deposit_fee, + bool use_stefan, struct GNUNET_TIME_Relative default_wire_transfer_delay, struct GNUNET_TIME_Relative default_pay_delay, TALER_MERCHANT_InstancePatchCallback cb, @@ -642,34 +750,6 @@ struct TALER_MERCHANT_InstanceGetHandle; /** - * Details about a merchant's bank account. - */ -struct TALER_MERCHANT_Account -{ - /** - * salt used to compute h_wire - */ - struct TALER_WireSaltP salt; - - /** - * payto:// URI of the account. - */ - const char *payto_uri; - - /** - * Hash of @e payto_uri and @e salt. - */ - struct TALER_MerchantWireHashP h_wire; - - /** - * true if the account is active, - * false if it is historic. - */ - bool active; -}; - - -/** * Details about an instance. */ struct TALER_MERCHANT_InstanceDetails @@ -682,7 +762,7 @@ struct TALER_MERCHANT_InstanceDetails /** * public key of the merchant instance */ - const struct TALER_MerchantPublicKeyP *merchant_pub; + struct TALER_MerchantPublicKeyP merchant_pub; /** * physical address of the merchant instance @@ -695,29 +775,51 @@ struct TALER_MERCHANT_InstanceDetails const json_t *jurisdiction; /** - * default maximum wire fee merchant is willing to fully pay + * Are we using STEFAN curves to determine acceptable + * fees? */ - const struct TALER_Amount *default_max_wire_fee; + bool use_stefan; /** - * default amortization factor for excess wire fees + * default wire transfer delay merchant will ask for */ - uint32_t default_wire_fee_amortization; + struct GNUNET_TIME_Relative default_wire_transfer_delay; /** - * default maximum deposit fee merchant is willing to pay + * default validity period for offers merchant makes */ - const struct TALER_Amount *default_max_deposit_fee; + struct GNUNET_TIME_Relative default_pay_delay; /** - * default wire transfer delay merchant will ask for + * User type for the instance. */ - struct GNUNET_TIME_Relative default_wire_transfer_delay; + enum TALER_KYCLOGIC_KycUserType ut; +}; + +struct TALER_MERCHANT_InstanceGetResponse +{ /** - * default validity period for offers merchant makes + * HTTP response data */ - struct GNUNET_TIME_Relative default_pay_delay; + struct TALER_MERCHANT_HttpResponse hr; + + union + { + + /** + * Data returned on #MHD_HTTP_OK. + */ + struct + { + /** + * Details about the instance. + */ + struct TALER_MERCHANT_InstanceDetails details; + + } ok; + } + details; }; @@ -725,18 +827,12 @@ struct TALER_MERCHANT_InstanceDetails * Function called with the result of the GET /instances/$ID operation. * * @param cls closure - * @param hr HTTP response data - * @param accounts_length length of the @a accounts array - * @param accounts bank accounts of the merchant instance - * @param details details about the instance configuration + * @param igr response details */ typedef void (*TALER_MERCHANT_InstanceGetCallback)( void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - unsigned int accounts_length, - const struct TALER_MERCHANT_Account accounts[], - const struct TALER_MERCHANT_InstanceDetails *details); + const struct TALER_MERCHANT_InstanceGetResponse *igr); /** @@ -753,11 +849,12 @@ typedef void * @return the instances handle; NULL upon error */ struct TALER_MERCHANT_InstanceGetHandle * -TALER_MERCHANT_instance_get (struct GNUNET_CURL_Context *ctx, - const char *backend_url, - const char *instance_id, - TALER_MERCHANT_InstanceGetCallback cb, - void *cb_cls); +TALER_MERCHANT_instance_get ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + const char *instance_id, + TALER_MERCHANT_InstanceGetCallback cb, + void *cb_cls); /** @@ -852,7 +949,422 @@ TALER_MERCHANT_instance_delete_cancel ( * @param arg request to cancel. */ #define TALER_MERCHANT_instance_purge_cancel(arg) \ - TALER_MERCHANT_instance_delete_cancel (arg) + TALER_MERCHANT_instance_delete_cancel (arg) + + +/* *************** Accounts **************** */ + +/** + * Handle for a POST /instances/$ID/accounts operation. + */ +struct TALER_MERCHANT_AccountsPostHandle; + + +/** + * Response for a POST /instances/$ID/account operation. + */ +struct TALER_MERCHANT_AccountsPostResponse +{ + /** + * HTTP response data + */ + struct TALER_MERCHANT_HttpResponse hr; + + /** + * Details depending on HTTP status. + */ + union + { + + /** + * Details returned on #MHD_HTTP_OK. + */ + struct + { + + /** + * Hash of @e payto_uri and @e salt. + */ + struct TALER_MerchantWireHashP h_wire; + + /** + * salt used to compute h_wire + */ + struct TALER_WireSaltP salt; + } ok; + + } details; +}; + + +/** + * Function called with the result of the POST /instances/$ID/accounts operation. + * + * @param cls closure + * @param par response data + */ +typedef void +(*TALER_MERCHANT_AccountsPostCallback)( + void *cls, + const struct TALER_MERCHANT_AccountsPostResponse *par); + + +/** + * Setup an new account for an instance in the backend. + * + * @param ctx the context + * @param backend_url HTTP base URL for the backend + * @param payto_uri URI of the bank account as per RFC 8905 + * @param credit_facade_url credit facade for the account, can be NULL + * @param credit_facade_credentials credentials for credit facade, can be NULL + * @param cb function to call with the response + * @param cb_cls closure for @a config_cb + * @return the instances handle; NULL upon error + */ +struct TALER_MERCHANT_AccountsPostHandle * +TALER_MERCHANT_accounts_post ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + const char *payto_uri, + const char *credit_facade_url, + const json_t *credit_facade_credentials, + TALER_MERCHANT_AccountsPostCallback cb, + void *cb_cls); + + +/** + * Cancel POST /accounts request. Must not be called by clients after + * the callback was invoked. + * + * @param pah request to cancel. + */ +void +TALER_MERCHANT_accounts_post_cancel ( + struct TALER_MERCHANT_AccountsPostHandle *pah); + + +/** + * Handle for a GET /accounts/$ID operation. + */ +struct TALER_MERCHANT_AccountGetHandle; + + +/** + * Details about a merchant's bank account. + */ +struct TALER_MERCHANT_AccountDetails +{ + /** + * salt used to compute h_wire + */ + struct TALER_WireSaltP salt; + + /** + * payto:// URI of the account. + */ + const char *payto_uri; + + /** + * Credit facade URL of the account. + */ + const char *credit_facade_url; + + /** + * Hash of @e payto_uri and @e salt. + */ + struct TALER_MerchantWireHashP h_wire; + + /** + * true if the account is active, + * false if it is historic. + */ + bool active; +}; + + +/** + * Response returned with details about an account. + */ +struct TALER_MERCHANT_AccountGetResponse +{ + /** + * HTTP response data + */ + struct TALER_MERCHANT_HttpResponse hr; + + union + { + + /** + * Data returned on #MHD_HTTP_OK. + */ + struct + { + + /** + * bank accounts of the merchant instance + */ + struct TALER_MERCHANT_AccountDetails ad; + + } ok; + } + details; +}; + + +/** + * Function called with the result of the GET /instances/$ID/accounts/$H_WIRE operation. + * + * @param cls closure + * @param igr response details + */ +typedef void +(*TALER_MERCHANT_AccountGetCallback)( + void *cls, + const struct TALER_MERCHANT_AccountGetResponse *igr); + + +/** + * Get the details on one of the accounts of an instance. Will connect to the + * merchant backend and obtain information about the account. The respective + * information will be passed to the @a cb once available. + * + * @param ctx the context + * @param backend_url HTTP base URL for the backend + * @param instance_id identity of the instance to get information about + * @param h_wire hash of the wire details + * @param cb function to call with the + * backend's instances information + * @param cb_cls closure for @a config_cb + * @return the instances handle; NULL upon error + */ +struct TALER_MERCHANT_AccountGetHandle * +TALER_MERCHANT_account_get ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + const char *instance_id, + const struct TALER_MerchantWireHashP *h_wire, + TALER_MERCHANT_AccountGetCallback cb, + void *cb_cls); + + +/** + * Cancel GET /accounts/$H_WIRE request. Must not be called by clients after + * the callback was invoked. + * + * @param igh request to cancel. + */ +void +TALER_MERCHANT_account_get_cancel ( + struct TALER_MERCHANT_AccountGetHandle *igh); + + +/** + * Handle for a GET /accounts operation. + */ +struct TALER_MERCHANT_AccountsGetHandle; + +/** + * Individual account (minimal information + * returned via GET /accounts). + */ +struct TALER_MERCHANT_AccountEntry +{ + /** + * account payto URI. + */ + const char *payto_uri; + + /** + * Hash of @e payto_uri and salt. + */ + struct TALER_MerchantWireHashP h_wire; + +}; + + +/** + * Response to a GET /accounts operation. + */ +struct TALER_MERCHANT_AccountsGetResponse +{ + /** + * HTTP response details + */ + struct TALER_MERCHANT_HttpResponse hr; + + /** + * Details depending on status. + */ + union + { + /** + * Details if status is #MHD_HTTP_OK. + */ + struct + { + /** + * length of the @e accounts array + */ + unsigned int accounts_length; + + /** + * array of accounts the requested instance offers + */ + const struct TALER_MERCHANT_AccountEntry *accounts; + } ok; + } details; +}; + + +/** + * Function called with the result of the GET /accounts operation. + * + * @param cls closure + * @param tgr response details + */ +typedef void +(*TALER_MERCHANT_AccountsGetCallback)( + void *cls, + const struct TALER_MERCHANT_AccountsGetResponse *tgr); + + +/** + * Make a GET /accounts request. + * + * @param ctx the context + * @param backend_url HTTP base URL for the backend + * @param cb function to call with the backend information + * @param cb_cls closure for @a cb + * @return the request handle; NULL upon error + */ +struct TALER_MERCHANT_AccountsGetHandle * +TALER_MERCHANT_accounts_get ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + TALER_MERCHANT_AccountsGetCallback cb, + void *cb_cls); + + +/** + * Cancel GET /accounts operation. + * + * @param tgh operation to cancel + */ +void +TALER_MERCHANT_accounts_get_cancel ( + struct TALER_MERCHANT_AccountsGetHandle *tgh); + + +/** + * Handle for a PATCH /account operation. + */ +struct TALER_MERCHANT_AccountPatchHandle; + + +/** + * Function called with the result of the PATCH /account operation. + * + * @param cls closure + * @param hr HTTP response details + */ +typedef void +(*TALER_MERCHANT_AccountPatchCallback)( + void *cls, + const struct TALER_MERCHANT_HttpResponse *hr); + + +/** + * Make a PATCH /accounts/$H_WIRE request to update account details. Cannot be used to change the payto URI or the salt. + * + * @param ctx the context + * @param backend_url HTTP base URL for the backend + * @param h_wire identifies the account to patch + * @param credit_facade_url credit facade for the account, can be NULL + * @param credit_facade_credentials credentials for credit facade, can be NULL + * @param cb function to call with the backend's result + * @param cb_cls closure for @a cb + * @return the request handle; NULL upon error + */ +struct TALER_MERCHANT_AccountPatchHandle * +TALER_MERCHANT_account_patch ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + const struct TALER_MerchantWireHashP *h_wire, + const char *credit_facade_url, + const json_t *credit_facade_credentials, + TALER_MERCHANT_AccountPatchCallback cb, + void *cb_cls); + + +/** + * Cancel PATCH /accounts/$H_WIRE operation. + * + * @param[in] tph operation to cancel + */ +void +TALER_MERCHANT_account_patch_cancel ( + struct TALER_MERCHANT_AccountPatchHandle *tph); + + +/** + * Handle for a DELETE /instances/$ID/account/$H_WIRE operation. + */ +struct TALER_MERCHANT_AccountDeleteHandle; + + +/** + * Response for a DELETE /instances/$ID/account operation. + */ +struct TALER_MERCHANT_AccountDeleteResponse +{ + /** + * HTTP response data + */ + struct TALER_MERCHANT_HttpResponse hr; +}; + + +/** + * Function called with the result of the DELETE /instances/$ID/account/$H_WIRE operation. + * + * @param cls closure + * @param par response data + */ +typedef void +(*TALER_MERCHANT_AccountDeleteCallback)( + void *cls, + const struct TALER_MERCHANT_AccountDeleteResponse *par); + + +/** + * Remove bank account from an instance in the backend. + * + * @param ctx the context + * @param backend_url HTTP base URL for the backend + * @param h_wire wire hash of the bank accounts to delete + * @param cb function to call with the response + * @param cb_cls closure for @a config_cb + * @return the instances handle; NULL upon error + */ +struct TALER_MERCHANT_AccountDeleteHandle * +TALER_MERCHANT_account_delete ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + const struct TALER_MerchantWireHashP *h_wire, + TALER_MERCHANT_AccountDeleteCallback cb, + void *cb_cls); + + +/** + * Cancel /account request. Must not be called by clients after + * the callback was invoked. + * + * @param pah request to cancel. + */ +void +TALER_MERCHANT_account_delete_cancel ( + struct TALER_MERCHANT_AccountDeleteHandle *pah); /* ********************* /products *********************** */ @@ -874,6 +1386,40 @@ struct TALER_MERCHANT_InventoryEntry */ const char *product_id; + /** + * Serial ID of the product. + */ + uint64_t product_serial; +}; + + +/** + * Response to a GET /products request. + */ +struct TALER_MERCHANT_GetProductsResponse +{ + /** + * HTTP response details + */ + struct TALER_MERCHANT_HttpResponse hr; + + union + { + struct + { + + /** + * length of the @a products array + */ + unsigned int products_length; + + /** + * array of products the requested instance offers + */ + const struct TALER_MERCHANT_InventoryEntry *products; + } ok; + + } details; }; @@ -881,16 +1427,12 @@ struct TALER_MERCHANT_InventoryEntry * Function called with the result of the GET /products operation. * * @param cls closure - * @param hr HTTP response details - * @param products_length length of the @a products array - * @param products array of products the requested instance offers + * @param gpr response details */ typedef void (*TALER_MERCHANT_ProductsGetCallback)( void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - unsigned int products_length, - const struct TALER_MERCHANT_InventoryEntry products[]); + const struct TALER_MERCHANT_GetProductsResponse *gpr); /** @@ -930,44 +1472,104 @@ struct TALER_MERCHANT_ProductGetHandle; /** + * Response to GET /product/$ID operation. + */ +struct TALER_MERCHANT_ProductGetResponse +{ + /** + * HTTP response details + */ + struct TALER_MERCHANT_HttpResponse hr; + + /** + * Details depending on HTTP status. + */ + union + { + /** + * Details for #MHD_HTTP_OK. + */ + struct + { + + /** + * description of the product + */ + const char *description; + + /** + * Map from IETF BCP 47 language tags to localized descriptions + */ + const json_t *description_i18n; + + /** + * unit in which the product is measured (liters, kilograms, packages, etc.) + */ + const char *unit; + + /** + * the price for one @a unit of the product, zero is used to imply that + * this product is not sold separately or that the price is + * not fixed and must be supplied by the front-end. If + * non-zero, price must include applicable taxes. + */ + struct TALER_Amount price; + + /** + * base64-encoded product image + */ + const char *image; + + /** + * list of taxes paid by the merchant + */ + const json_t *taxes; + + /** + * total_stock in @e units, -1 to indicate "infinite" (i.e. electronic + * books), does NOT indicate remaining stocks, to get remaining stocks, + * subtract @e total_sold and @e total_lost. Note that this still does + * not then say how many of the remaining inventory are locked. + */ + int64_t total_stock; + + /** + * in @e units, total number of @e unit of product sold + */ + uint64_t total_sold; + + /** + * in @e units, total number of @e unit of product lost from inventory + */ + uint64_t total_lost; + + /** + * where the product is in stock + */ + const json_t *location; + + /** + * when the next restocking is expected to happen, 0 for unknown, + * #GNUNET_TIME_UNIT_FOREVER_ABS for 'never'. + */ + struct GNUNET_TIME_Timestamp next_restock; + } ok; + + } details; + +}; + + +/** * Function called with the result of the GET /products operation. * * @param cls closure - * @param hr HTTP response details - * @param description description of the product - * @param description_i18n Map from IETF BCP 47 language tags to localized descriptions - * @param unit unit in which the product is measured (liters, kilograms, packages, etc.) - * @param price the price for one @a unit of the product, zero is used to imply that - * this product is not sold separately or that the price is not fixed and - * must be supplied by the front-end. If non-zero, price must include - * applicable taxes. - * @param image base64-encoded product image - * @param taxes list of taxes paid by the merchant - * @param total_stock in @a units, -1 to indicate "infinite" (i.e. electronic books), - * does NOT indicate remaining stocks, to get remaining stocks, - * subtract @a total_sold and @a total_lost. Note that this still - * does not then say how many of the remaining inventory are locked. - * @param total_sold in @a units, total number of @a unit of product sold - * @param total_lost in @a units, total number of @a unit of product lost from inventory - * @param location where the product is in stock - * @param next_restock when the next restocking is expected to happen, 0 for unknown, - * #GNUNET_TIME_UNIT_FOREVER_ABS for 'never'. + * @param pgr response details */ typedef void (*TALER_MERCHANT_ProductGetCallback)( void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - const char *description, - const json_t *description_i18n, - const char *unit, - const struct TALER_Amount *price, - const char *image, - const json_t *taxes, - int64_t total_stock, - uint64_t total_sold, - uint64_t total_lost, - const json_t *location, - struct GNUNET_TIME_Timestamp next_restock); + const struct TALER_MERCHANT_ProductGetResponse *pgr); /** @@ -1061,6 +1663,50 @@ TALER_MERCHANT_products_post ( /** + * Make a POST /products request to add a product to the + * inventory. + * + * @param ctx the context + * @param backend_url HTTP base URL for the backend + * @param product_id identifier to use for the product + * @param description description of the product + * @param description_i18n Map from IETF BCP 47 language tags to localized descriptions + * @param unit unit in which the product is measured (liters, kilograms, packages, etc.) + * @param price the price for one @a unit of the product, zero is used to imply that + * this product is not sold separately or that the price is not fixed and + * must be supplied by the front-end. If non-zero, price must include + * applicable taxes. + * @param image base64-encoded product image + * @param taxes list of taxes paid by the merchant + * @param total_stock in @a units, -1 to indicate "infinite" (i.e. electronic books) + * @param address where the product is in stock + * @param next_restock when the next restocking is expected to happen, 0 for unknown, + * #GNUNET_TIME_UNIT_FOREVER_ABS for 'never'. + * @param minimum_age minimum age the buyer must have + * @param cb function to call with the backend's result + * @param cb_cls closure for @a cb + * @return the request handle; NULL upon error + */ +struct TALER_MERCHANT_ProductsPostHandle * +TALER_MERCHANT_products_post2 ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + const char *product_id, + const char *description, + const json_t *description_i18n, + const char *unit, + const struct TALER_Amount *price, + const char *image, + const json_t *taxes, + int64_t total_stock, + const json_t *address, + struct GNUNET_TIME_Timestamp next_restock, + uint32_t minimum_age, + TALER_MERCHANT_ProductsPostCallback cb, + void *cb_cls); + + +/** * Cancel POST /products operation. * * @param pph operation to cancel @@ -1249,6 +1895,172 @@ TALER_MERCHANT_product_delete_cancel ( struct TALER_MERCHANT_ProductDeleteHandle *pdh); +/* ********************* /tokenfamilies ************************** */ + +/** + * Handle for a GET /tokenfamilies/$SLUG operation. + */ +struct TALER_MERCHANT_TokenFamilyGetHandle; + + +/** + * Response to GET /tokenfamilies/$SLUG operation. + */ +struct TALER_MERCHANT_TokenFamilyGetResponse +{ + /** + * HTTP response details + */ + struct TALER_MERCHANT_HttpResponse hr; + + /** + * Details depending on HTTP status. + */ + union + { + /** + * Details for #MHD_HTTP_OK. + */ + struct + { + + /** + * Identifier for the token family consisting of unreserved characters + * according to RFC 3986. + */ + const char *slug; + + /** + * Human-readable name for the token family. + */ + const char *name; + + /** + * description of the token family + */ + const char *description; + + /** + * Optional map from IETF BCP 47 language tags to localized descriptions. + */ + const json_t *description_i18n; + + /** + * Start time of the token family's validity period. + */ + struct GNUNET_TIME_Timestamp valid_after; + + /** + * End time of the token family's validity period. + */ + struct GNUNET_TIME_Timestamp valid_before; + + /** + * Validity duration of an issued token. + */ + struct GNUNET_TIME_Relative duration; + + /** + * Kind of token family, "subscription" or "discount". + */ + const char *kind; + + /** + * How many tokens have been issued for this family. + */ + uint64_t issued; + + /** + * How many tokens have been redeemed for this family. + */ + uint64_t redeemed; + } ok; + + } details; + +}; + +/** + * Cancel GET /tokenfamilies/$SLUG operation. + * + * @param handle operation to cancel + */ +void +TALER_MERCHANT_token_family_get_cancel ( + struct TALER_MERCHANT_TokenFamilyGetHandle *handle); + + +/** + * Function called with the result of the GET /tokenfamilies/$SLUG operation. + * + * @param cls closure + * @param pgr response details + */ +typedef void +(*TALER_MERCHANT_TokenFamilyGetCallback)( + void *cls, + const struct TALER_MERCHANT_TokenFamilyGetResponse *pgr); + +/** + * Handle for a POST /tokenfamilies operation. + */ +struct TALER_MERCHANT_TokenFamiliesPostHandle; + + +/** + * Function called with the result of the POST /tokenfamilies operation. + * + * @param cls closure + * @param hr HTTP response details + */ +typedef void +(*TALER_MERCHANT_TokenFamiliesPostCallback)( + void *cls, + const struct TALER_MERCHANT_HttpResponse *hr); + + +/** + * Make a POST /tokenfamilies request to add a token family to the + * merchant instance. + * + * @param ctx the context + * @param backend_url HTTP base URL for the backend + * @param slug short, url-safe identifier for the token family + * @param name human-readable name for the token family + * @param description description of the token family + * @param description_i18n Map from IETF BCP 47 language tags to localized descriptions + * @param valid_after when the token family becomes valid + * @param valid_before when the token family expires + * @param duration how long tokens issued by this token family are valid for + * @param kind kind of token family, "subscription" or "discount" + * @param cb function to call with the backend's result + * @param cb_cls closure for @a cb + * @return the request handle; NULL upon error + */ +struct TALER_MERCHANT_TokenFamiliesPostHandle * +TALER_MERCHANT_token_families_post ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + const char *slug, + const char *name, + const char *description, + const json_t *description_i18n, + struct GNUNET_TIME_Timestamp valid_after, + struct GNUNET_TIME_Timestamp valid_before, + struct GNUNET_TIME_Relative duration, + const char *kind, + TALER_MERCHANT_TokenFamiliesPostCallback cb, + void *cb_cls); + +/** + * Cancel POST /tokenfamilies operation. + * + * @param handle operation to cancel + */ +void +TALER_MERCHANT_token_families_post_cancel ( + struct TALER_MERCHANT_TokenFamiliesPostHandle *handle); + /* ********************* /orders ************************** */ @@ -1359,12 +2171,13 @@ typedef void * @return a handle for this request, NULL on error */ struct TALER_MERCHANT_PostOrdersHandle * -TALER_MERCHANT_orders_post (struct GNUNET_CURL_Context *ctx, - const char *backend_url, - const json_t *order, - struct GNUNET_TIME_Relative refund_delay, - TALER_MERCHANT_PostOrdersCallback cb, - void *cb_cls); +TALER_MERCHANT_orders_post ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + const json_t *order, + struct GNUNET_TIME_Relative refund_delay, + TALER_MERCHANT_PostOrdersCallback cb, + void *cb_cls); /** * Information needed per product for constructing orders from @@ -1414,7 +2227,44 @@ TALER_MERCHANT_orders_post2 ( unsigned int inventory_products_length, const struct TALER_MERCHANT_InventoryProduct inventory_products[], unsigned int uuids_length, - const char *uuids[], + const char *uuids[static uuids_length], + bool create_token, + TALER_MERCHANT_PostOrdersCallback cb, + void *cb_cls); + + +/** + * POST to /orders at the backend to setup an order and obtain + * the order ID (which may have been set by the front-end). + * + * @param ctx execution context + * @param backend_url URL of the backend + * @param order basic information about this purchase, to be extended by the backend + * @param session_id session ID to set for the order + * @param refund_delay how long can refunds happen for this order; 0 to use + * absolute value from contract (or not allow refunds). + * @param payment_target desired payment target identifier (to select merchant bank details) + * @param inventory_products_length length of the @a inventory_products array + * @param inventory_products products to add to the order from the inventory + * @param uuids_length length of the @a uuids array + * @param uuids array of UUIDs with locks on @a inventory_products + * @param create_token whether to create a claim token + * @param cb the callback to call when a reply for this request is available + * @param cb_cls closure for @a cb + * @return a handle for this request, NULL on error + */ +struct TALER_MERCHANT_PostOrdersHandle * +TALER_MERCHANT_orders_post3 ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + const json_t *order, + const char *session_id, + struct GNUNET_TIME_Relative refund_delay, + const char *payment_target, + unsigned int inventory_products_length, + const struct TALER_MERCHANT_InventoryProduct inventory_products[], + unsigned int uuids_length, + const char *uuids[static uuids_length], bool create_token, TALER_MERCHANT_PostOrdersCallback cb, void *cb_cls); @@ -1424,7 +2274,7 @@ TALER_MERCHANT_orders_post2 ( * Cancel a POST /orders request. This function cannot be used * on a request handle if a response is already served for it. * - * @param po the proposal operation request handle + * @param[in] po the proposal operation request handle */ void TALER_MERCHANT_orders_post_cancel ( @@ -1482,19 +2332,51 @@ struct TALER_MERCHANT_OrderEntry /** + * Response for a GET /private/orders request. + */ +struct TALER_MERCHANT_OrdersGetResponse +{ + /** + * HTTP response details. + */ + struct TALER_MERCHANT_HttpResponse hr; + + /** + * Details depending on HTTP status. + */ + union + { + /** + * Details for #MHD_HTTP_OK. + */ + struct + { + + /** + * length of the @e orders array + */ + unsigned int orders_length; + + /** + * array of orders the requested instance has made + */ + const struct TALER_MERCHANT_OrderEntry *orders; + } ok; + } details; + +}; + + +/** * Function called with the result of the GET /orders operation. * * @param cls closure - * @param hr HTTP response details - * @param orders_length length of the @a orders array - * @param orders array of orders the requested instance has made + * @param ogr response details */ typedef void (*TALER_MERCHANT_OrdersGetCallback)( void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - unsigned int orders_length, - const struct TALER_MERCHANT_OrderEntry orders[]); + const struct TALER_MERCHANT_OrdersGetResponse *ogr); /** @@ -1548,9 +2430,46 @@ TALER_MERCHANT_orders_get2 ( /** + * Make a GET /orders request with more filters. + * + * @param ctx the context + * @param backend_url HTTP base URL for the backend + * @param paid filter on payment status + * @param refunded filter on refund status + * @param wired filter on wire transfer status + * @param session_id filter by session ID + * @param fulfillment_url filter by fulfillment URL + * @param date range limit by date + * @param start_row range limit by order table row + * @param delta range from which @a date and @a start_row apply, positive + * to return delta items after the given limit(s), negative to + * return delta items before the given limit(s) + * @param timeout how long to wait (long polling) of zero results match the query + * @param cb function to call with the backend's inventory information + * @param cb_cls closure for @a cb + * @return the request handle; NULL upon error + */ +struct TALER_MERCHANT_OrdersGetHandle * +TALER_MERCHANT_orders_get3 ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + enum TALER_EXCHANGE_YesNoAll paid, + enum TALER_EXCHANGE_YesNoAll refunded, + enum TALER_EXCHANGE_YesNoAll wired, + const char *session_id, + const char *fulfillment_url, + struct GNUNET_TIME_Timestamp date, + uint64_t start_row, + int64_t delta, + struct GNUNET_TIME_Relative timeout, + TALER_MERCHANT_OrdersGetCallback cb, + void *cb_cls); + + +/** * Cancel GET /orders operation. * - * @param pgh operation to cancel + * @param[in] pgh operation to cancel */ void TALER_MERCHANT_orders_get_cancel ( @@ -1602,7 +2521,7 @@ struct TALER_MERCHANT_OrderWalletGetResponse */ struct TALER_Amount refund_amount; - } success; + } ok; /** * Response if a payment is required from the client. @@ -1679,7 +2598,7 @@ TALER_MERCHANT_wallet_order_get ( /** * Cancel a GET /orders/$ID request. * - * @param owgh handle to the request to be canceled + * @param[in] owgh handle to the request to be canceled */ void TALER_MERCHANT_wallet_order_get_cancel ( @@ -1871,17 +2790,6 @@ struct TALER_MERCHANT_OrderStatusResponse unsigned int wts_len; /** - * Array of wire reports about problems tracking wire transfers. - * Of length @e wrs_len. - */ - struct TALER_MERCHANT_WireReport *wrs; - - /** - * Length of the @e wrs array. - */ - unsigned int wrs_len; - - /** * Details returned by the merchant backend about refunds. * Of length @e refunds_len. */ @@ -1922,6 +2830,12 @@ struct TALER_MERCHANT_OrderStatusResponse */ bool wired; + /** + * Time of the last payment made on this order. + * Only available if the server supports protocol + * **v14** or higher, otherwise zero. + */ + struct GNUNET_TIME_Timestamp last_payment; } paid; /** @@ -1974,7 +2888,7 @@ struct TALER_MERCHANT_OrderStatusResponse } details; - } success; + } ok; } details; }; @@ -1999,10 +2913,8 @@ typedef void * @param ctx execution context * @param backend_url base URL of the merchant backend * @param order_id order id to identify the payment - * @param session_id sesion id for the payment (or NULL if the check is not + * @param session_id session id for the payment (or NULL if the check is not * bound to a session) - * @param transfer if true, obtain the wire transfer status from the exchange. - * Otherwise, the wire transfer status MAY be returned if it is available. * @param timeout timeout to use in long polling (how long may the server wait to reply * before generating an unpaid response). Note that this is just provided to * the server, we as client will block until the response comes back or until @@ -2016,7 +2928,6 @@ TALER_MERCHANT_merchant_order_get (struct GNUNET_CURL_Context *ctx, const char *backend_url, const char *order_id, const char *session_id, - bool transfer, struct GNUNET_TIME_Relative timeout, TALER_MERCHANT_OrderMerchantGetCallback cb, void *cb_cls); @@ -2025,7 +2936,7 @@ TALER_MERCHANT_merchant_order_get (struct GNUNET_CURL_Context *ctx, /** * Cancel a GET /private/orders/$ID request. * - * @param omgh handle to the request to be canceled + * @param[in] omgh handle to the request to be canceled */ void TALER_MERCHANT_merchant_order_get_cancel ( @@ -2075,7 +2986,7 @@ TALER_MERCHANT_order_delete ( /** * Cancel DELETE /orders/$ID operation. * - * @param odh operation to cancel + * @param[in] odh operation to cancel */ void TALER_MERCHANT_order_delete_cancel ( @@ -2089,22 +3000,54 @@ struct TALER_MERCHANT_OrderClaimHandle; /** + * Response to a POST /orders/$ID/claim request. + */ +struct TALER_MERCHANT_OrderClaimResponse +{ + /** + * HTTP response details + */ + struct TALER_MERCHANT_HttpResponse hr; + + /** + * Details depending on HTTP status. + */ + union + { + /** + * Details for #MHD_HTTP_OK. + */ + struct + { + /** + * the details of the contract + */ + const json_t *contract_terms; + + /** + * merchant's signature over @e contract_terms (already verified) + */ + struct TALER_MerchantSignatureP sig; + + /** + * hash over @e contract_terms (computed client-side to verify @e sig) + */ + struct TALER_PrivateContractHashP h_contract_terms; + } ok; + + } details; +}; + +/** * Callback called to process a POST /orders/$ID/claim response. * * @param cls closure - * @param hr HTTP response details - * @param contract_terms the details of the contract - * @param sig merchant's signature over @a contract_terms (already verified) - * @param h_contract_terms hash over @a contract_terms (computed - * client-side to verify @a sig) + * @param ocr response details */ typedef void (*TALER_MERCHANT_OrderClaimCallback) ( void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - const json_t *contract_terms, - const struct TALER_MerchantSignatureP *sig, - const struct TALER_PrivateContractHashP *h_contract_terms); + const struct TALER_MERCHANT_OrderClaimResponse *ocr); /** @@ -2123,19 +3066,20 @@ typedef void * @return handle for this handle, NULL upon errors */ struct TALER_MERCHANT_OrderClaimHandle * -TALER_MERCHANT_order_claim (struct GNUNET_CURL_Context *ctx, - const char *backend_url, - const char *order_id, - const struct GNUNET_CRYPTO_EddsaPublicKey *nonce, - const struct TALER_ClaimTokenP *claim_token, - TALER_MERCHANT_OrderClaimCallback cb, - void *cb_cls); +TALER_MERCHANT_order_claim ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + const char *order_id, + const struct GNUNET_CRYPTO_EddsaPublicKey *nonce, + const struct TALER_ClaimTokenP *claim_token, + TALER_MERCHANT_OrderClaimCallback cb, + void *cb_cls); /** * Cancel a POST /order/$ID/claim request. * - * @param och handle to the request to be canceled + * @param[in] och handle to the request to be canceled */ void TALER_MERCHANT_order_claim_cancel (struct TALER_MERCHANT_OrderClaimHandle *och); @@ -2179,7 +3123,12 @@ struct TALER_MERCHANT_PayResponse */ struct TALER_MerchantSignatureP merchant_sig; - } success; + /** + * Optional payment confirmation code returned by the service. + */ + const char *pos_confirmation; + + } ok; // TODO: might want to return further details on errors, // especially refund signatures on double-pay conflict. @@ -2263,6 +3212,7 @@ struct TALER_MERCHANT_PaidCoin * @param merchant_url base URL of the merchant * @param order_id which order should be paid * @param session_id session to pay for, or NULL for none + * @param wallet_data inputs from the wallet for the contract, NULL for none * @param num_coins length of the @a coins array * @param coins array of coins to pay with * @param pay_cb the callback to call when a reply for this request is available @@ -2275,8 +3225,9 @@ TALER_MERCHANT_order_pay_frontend ( const char *merchant_url, const char *order_id, const char *session_id, + const json_t *wallet_data, unsigned int num_coins, - const struct TALER_MERCHANT_PaidCoin coins[], + const struct TALER_MERCHANT_PaidCoin coins[static num_coins], TALER_MERCHANT_OrderPayCallback pay_cb, void *pay_cb_cls); @@ -2339,6 +3290,7 @@ struct TALER_MERCHANT_PayCoin * @param merchant_url base URL of the merchant * @param session_id session to pay for, or NULL for none * @param h_contract hash of the contact of the merchant with the customer + * @param wallet_data inputs from the wallet for the contract, NULL for none * @param amount total value of the contract to be paid to the merchant * @param max_fee maximum fee covered by the merchant (according to the contract) * @param merchant_pub the public key of the merchant (used to identify the merchant for refund requests) @@ -2355,23 +3307,25 @@ struct TALER_MERCHANT_PayCoin * @return a handle for this request */ struct TALER_MERCHANT_OrderPayHandle * -TALER_MERCHANT_order_pay (struct GNUNET_CURL_Context *ctx, - const char *merchant_url, - const char *session_id, - const struct TALER_PrivateContractHashP *h_contract, - const struct TALER_Amount *amount, - const struct TALER_Amount *max_fee, - const struct TALER_MerchantPublicKeyP *merchant_pub, - const struct TALER_MerchantSignatureP *merchant_sig, - struct GNUNET_TIME_Timestamp timestamp, - struct GNUNET_TIME_Timestamp refund_deadline, - struct GNUNET_TIME_Timestamp pay_deadline, - const struct TALER_MerchantWireHashP *h_wire, - const char *order_id, - unsigned int num_coins, - const struct TALER_MERCHANT_PayCoin coins[], - TALER_MERCHANT_OrderPayCallback pay_cb, - void *pay_cb_cls); +TALER_MERCHANT_order_pay ( + struct GNUNET_CURL_Context *ctx, + const char *merchant_url, + const char *session_id, + const struct TALER_PrivateContractHashP *h_contract, + const json_t *wallet_data, + const struct TALER_Amount *amount, + const struct TALER_Amount *max_fee, + const struct TALER_MerchantPublicKeyP *merchant_pub, + const struct TALER_MerchantSignatureP *merchant_sig, + struct GNUNET_TIME_Timestamp timestamp, + struct GNUNET_TIME_Timestamp refund_deadline, + struct GNUNET_TIME_Timestamp pay_deadline, + const struct TALER_MerchantWireHashP *h_wire, + const char *order_id, + unsigned int num_coins, + const struct TALER_MERCHANT_PayCoin coins[static num_coins], + TALER_MERCHANT_OrderPayCallback pay_cb, + void *pay_cb_cls); /** @@ -2393,18 +3347,46 @@ TALER_MERCHANT_order_pay_cancel (struct TALER_MERCHANT_OrderPayHandle *oph); */ struct TALER_MERCHANT_OrderPaidHandle; +/** + * Response to an /orders/$ID/paid request. + */ +struct TALER_MERCHANT_OrderPaidResponse +{ + /** + * HTTP response details. + */ + struct TALER_MERCHANT_HttpResponse hr; + /** + * HTTP-status code dependent details. + */ + union + { + /** + * Details on success. + */ + struct + { + /** + * Set to true if the order was paid but also + * refunded. + */ + bool refunded; + } ok; + } details; +}; + /** * Callbacks of this type are used to serve the result of submitting a * POST /orders/$ID/paid request to a merchant. * * @param cls closure - * @param hr HTTP response details + * @param opr response details */ typedef void (*TALER_MERCHANT_OrderPaidCallback) ( void *cls, - const struct TALER_MERCHANT_HttpResponse *hr); + const struct TALER_MERCHANT_OrderPaidResponse *opr); /** @@ -2418,6 +3400,7 @@ typedef void * @param order_id which order should be paid * @param session_id session to pay for, or NULL for none * @param h_contract_terms hash of the contract terms + * @param wallet_data_hash inputs from the wallet for the contract, NULL for none * @param merchant_sig signature from the merchant * affirming payment, or NULL on errors * @param paid_cb the callback to call when a reply for this request is available @@ -2431,6 +3414,7 @@ TALER_MERCHANT_order_paid ( const char *order_id, const char *session_id, const struct TALER_PrivateContractHashP *h_contract_terms, + const struct GNUNET_HashCode *wallet_data_hash, const struct TALER_MerchantSignatureP *merchant_sig, TALER_MERCHANT_OrderPaidCallback paid_cb, void *paid_cb_cls); @@ -2470,22 +3454,57 @@ struct TALER_MERCHANT_AbortedCoin /** + * Response to an /orders/$ID/abort request. + */ +struct TALER_MERCHANT_AbortResponse +{ + /** + * HTTP response details + */ + struct TALER_MERCHANT_HttpResponse hr; + + /** + * Details depending on HTTP status code. + */ + union + { + /** + * Details for #MHD_HTTP_OK. + */ + struct + { + + /** + * public key of the merchant + */ + const struct TALER_MerchantPublicKeyP *merchant_pub; + + /** + * size of the @e aborts array + */ + unsigned int num_aborts; + + /** + * merchant signatures refunding coins + */ + const struct TALER_MERCHANT_AbortedCoin *aborts; + } ok; + + } details; +}; + + +/** * Callbacks of this type are used to serve the result of submitting a * /orders/$ID/abort request to a merchant. * * @param cls closure - * @param hr HTTP response details - * @param merchant_pub public key of the merchant - * @param num_aborts size of the @a res array, 0 on errors - * @param aborts merchant signatures refunding coins, NULL on errors + * @param ar response details */ typedef void (*TALER_MERCHANT_AbortCallback) ( void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - const struct TALER_MerchantPublicKeyP *merchant_pub, - unsigned int num_aborts, - const struct TALER_MERCHANT_AbortedCoin aborts[]); + const struct TALER_MERCHANT_AbortResponse *ar); /** @@ -2530,15 +3549,16 @@ struct TALER_MERCHANT_AbortCoin * @return a handle for this request */ struct TALER_MERCHANT_OrderAbortHandle * -TALER_MERCHANT_order_abort (struct GNUNET_CURL_Context *ctx, - const char *merchant_url, - const char *order_id, - const struct TALER_MerchantPublicKeyP *merchant_pub, - const struct TALER_PrivateContractHashP *h_contract, - unsigned int num_coins, - const struct TALER_MERCHANT_AbortCoin coins[], - TALER_MERCHANT_AbortCallback cb, - void *cb_cls); +TALER_MERCHANT_order_abort ( + struct GNUNET_CURL_Context *ctx, + const char *merchant_url, + const char *order_id, + const struct TALER_MerchantPublicKeyP *merchant_pub, + const struct TALER_PrivateContractHashP *h_contract, + unsigned int num_coins, + const struct TALER_MERCHANT_AbortCoin coins[static num_coins], + TALER_MERCHANT_AbortCallback cb, + void *cb_cls); /** @@ -2585,13 +3605,14 @@ typedef void * @return a handle for this request. */ struct TALER_MERCHANT_OrderForgetHandle * -TALER_MERCHANT_order_forget (struct GNUNET_CURL_Context *ctx, - const char *merchant_url, - const char *order_id, - unsigned int fields_length, - const char *fields[], - TALER_MERCHANT_ForgetCallback cb, - void *cb_cls); +TALER_MERCHANT_order_forget ( + struct GNUNET_CURL_Context *ctx, + const char *merchant_url, + const char *order_id, + unsigned int fields_length, + const char *fields[static fields_length], + TALER_MERCHANT_ForgetCallback cb, + void *cb_cls); /** @@ -2599,11 +3620,11 @@ TALER_MERCHANT_order_forget (struct GNUNET_CURL_Context *ctx, * like this, you have no assurance that the request has not yet been * forwarded to the merchant. * - * @param ofh the forget request handle + * @param[in] ofh the forget request handle */ void -TALER_MERCHANT_order_forget_cancel (struct - TALER_MERCHANT_OrderForgetHandle *ofh); +TALER_MERCHANT_order_forget_cancel ( + struct TALER_MERCHANT_OrderForgetHandle *ofh); /** @@ -2613,20 +3634,51 @@ struct TALER_MERCHANT_OrderRefundHandle; /** - * Callback to process a POST /orders/ID/refund request + * Response to a POST /orders/$ID/refund request + */ +struct TALER_MERCHANT_RefundResponse +{ + /** + * HTTP response details this request + */ + struct TALER_MERCHANT_HttpResponse hr; + + /** + * Details depending on HTTP status. + */ + union + { + /** + * Details if status is #MHD_HTTP_OK. + */ + struct + { + + /** + * the refund uri offered to the wallet + */ + const char *taler_refund_uri; + + /** + * Hash of the contract a wallet may need to authorize obtaining the HTTP + * response. + */ + struct TALER_PrivateContractHashP h_contract; + } ok; + } details; +}; + + +/** + * Callback to process a POST /orders/$ID/refund request * * @param cls closure - * @param hr HTTP response details this request - * @param taler_refund_uri the refund uri offered to the wallet - * @param h_contract hash of the contract a Browser may need to authorize - * obtaining the HTTP response. + * @param rr response details this request */ typedef void (*TALER_MERCHANT_RefundCallback) ( void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - const char *taler_refund_uri, - const struct TALER_PrivateContractHashP *h_contract); + const struct TALER_MERCHANT_RefundResponse *rr); /** @@ -2641,13 +3693,14 @@ typedef void * @param cb_cls closure for cb */ struct TALER_MERCHANT_OrderRefundHandle * -TALER_MERCHANT_post_order_refund (struct GNUNET_CURL_Context *ctx, - const char *backend_url, - const char *order_id, - const struct TALER_Amount *refund, - const char *reason, - TALER_MERCHANT_RefundCallback cb, - void *cb_cls); +TALER_MERCHANT_post_order_refund ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + const char *order_id, + const struct TALER_Amount *refund, + const char *reason, + TALER_MERCHANT_RefundCallback cb, + void *cb_cls); /** * Cancel a POST /refund request. @@ -2693,17 +3746,74 @@ struct TALER_MERCHANT_RefundDetail struct TALER_Amount refund_amount; /** - * Public key of the exchange affirming the refund, - * only valid if the @e hr http_status is #MHD_HTTP_OK. + * Details depending on exchange HTTP status. */ - struct TALER_ExchangePublicKeyP exchange_pub; + union + { + /** + * Details if exchange status is #MHD_HTTP_OK. + */ + struct + { + /** + * Public key of the exchange affirming the refund, + * only valid if the @e hr http_status is #MHD_HTTP_OK. + */ + struct TALER_ExchangePublicKeyP exchange_pub; + /** + * Signature of the exchange affirming the refund, + * only valid if the @e hr http_status is #MHD_HTTP_OK. + */ + struct TALER_ExchangeSignatureP exchange_sig; + } ok; + } details; +}; + + +/** + * Response to a POST /orders/$ID/refund request + * for wallet API. + */ +struct TALER_MERCHANT_WalletRefundResponse +{ /** - * Signature of the exchange affirming the refund, - * only valid if the @e hr http_status is #MHD_HTTP_OK. + * HTTP response details this request */ - struct TALER_ExchangeSignatureP exchange_sig; + struct TALER_MERCHANT_HttpResponse hr; + + /** + * Details depending on HTTP status. + */ + union + { + /** + * Details if status is #MHD_HTTP_OK. + */ + struct + { + + /** + * Total amount of the refund that was granted + */ + struct TALER_Amount refund_amount; + + /** + * public key of the merchant signing the @e refunds + */ + struct TALER_MerchantPublicKeyP merchant_pub; + + /** + * array with details about the refunds obtained + */ + const struct TALER_MERCHANT_RefundDetail *refunds; + /** + * length of the @e refunds array + */ + unsigned int refunds_length; + } ok; + } details; }; @@ -2711,20 +3821,12 @@ struct TALER_MERCHANT_RefundDetail * Callback to process a (public) POST /orders/ID/refund request * * @param cls closure - * @param hr HTTP response details - * @param refund_amount what is the total amount of the refund that was granted - * @param merchant_pub public key of the merchant signing the @a refunds - * @param refunds array with details about the refunds obtained - * @param refunds_length length of the @a refunds array + * @param wrr HTTP response details */ typedef void (*TALER_MERCHANT_WalletRefundCallback) ( void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - const struct TALER_Amount *refund_amount, - const struct TALER_MerchantPublicKeyP *merchant_pub, - struct TALER_MERCHANT_RefundDetail refunds[], - unsigned int refunds_length); + const struct TALER_MERCHANT_WalletRefundResponse *wrr); /** @@ -2763,56 +3865,56 @@ TALER_MERCHANT_wallet_post_order_refund_cancel ( */ struct TALER_MERCHANT_PostTransfersHandle; + /** - * Information about the _total_ amount that was paid back - * by the exchange for a given h_contract_terms, by _one_ wire - * transfer. + * @brief Response to a POST /transfers operation from a merchant's backend. */ -struct TALER_MERCHANT_TrackTransferDetail +struct TALER_MERCHANT_PostTransfersResponse { - /** - * Total amount paid back by the exchange. + * HTTP response details */ - struct TALER_Amount deposit_value; + struct TALER_MERCHANT_HttpResponse hr; /** - * Total amount of deposit fees. + * Details depending on HTTP status. */ - struct TALER_Amount deposit_fee; + union + { - /** - * Order ID associated whit this payment. - */ - const char *order_id; + /** + * Details if we got an #MHD_HTTP_BAD_GATEWAY. + */ + struct + { + /** + * HTTP status of the exchange (or 0 if not available). + */ + unsigned int exchange_http_status; + + /** + * Error code of the exchange (or TALER_EC_NONE if not available). + */ + enum TALER_ErrorCode exchange_ec; + + } bad_gateway; + + } details; }; + /** * Callbacks of this type are used to work the result of submitting a * POST /transfers request to a merchant * * @param cls closure - * @param hr HTTP response details - * @param execution_time when did the transfer happen (according to the exchange), - * #GNUNET_TIME_UNIT_FOREVER_ABS if the transfer did not yet happen or if - * we have no data from the exchange about it - * @param total_amount total amount of the wire transfer, or NULL if the exchange did - * not provide any details - * @param wire_fee how much did the exchange charge in terms of wire fees, or NULL - * if the exchange did not provide any details - * @param details_length length of the @a details array - * @param details array with details about the combined transactions + * @param ptr response details */ typedef void (*TALER_MERCHANT_PostTransfersCallback) ( void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - struct GNUNET_TIME_Timestamp execution_time, - const struct TALER_Amount *total_amount, - const struct TALER_Amount *wire_fee, - unsigned int details_length, - const struct TALER_MERCHANT_TrackTransferDetail details[]); + const struct TALER_MERCHANT_PostTransfersResponse *ptr); /** @@ -2964,21 +4066,54 @@ struct TALER_MERCHANT_TransferData }; + +/** + * Response from a GET /transfers request. + */ +struct TALER_MERCHANT_GetTransfersResponse +{ + /** + * HTTP response details + */ + struct TALER_MERCHANT_HttpResponse hr; + + /** + * Details depending on HTTP status. + */ + union + { + + /** + * Details for status #MHD_HTTP_OK. + */ + struct + { + + /** + * length of the @e transfers array + */ + unsigned int transfers_length; + + /** + * array with details about the transfers we received + */ + const struct TALER_MERCHANT_TransferData *transfers; + } ok; + } details; +}; + + /** * Callbacks of this type are used to work the result of submitting a * GET /transfers request to a merchant * * @param cls closure - * @param hr HTTP response details - * @param transfers_length length of the @a transfers array - * @param transfers array with details about the transfers we received + * @param gtr HTTP response details */ typedef void (*TALER_MERCHANT_GetTransfersCallback) ( void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - unsigned int transfers_length, - const struct TALER_MERCHANT_TransferData transfers[]); + const struct TALER_MERCHANT_GetTransfersResponse *gtr); /** @@ -3033,548 +4168,353 @@ TALER_MERCHANT_transfers_get_cancel ( struct TALER_MERCHANT_GetTransfersHandle *gth); -/* ******************* /reserves *************** */ - - -/** - * @brief Handle to a POST /reserves operation at a merchant's backend. - */ -struct TALER_MERCHANT_PostReservesHandle; - - -/** - * Callbacks of this type are used to work the result of submitting a - * POST /reserves request to a merchant - * - * @param cls closure - * @param hr HTTP response details - * @param reserve_pub public key of the created reserve, NULL on error - * @param payto_uri where to make the payment to for filling the reserve, NULL on error - */ -typedef void -(*TALER_MERCHANT_PostReservesCallback) ( - void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - const struct TALER_ReservePublicKeyP *reserve_pub, - const char *payto_uri); - - -/** - * Request backend to create a reserve. - * - * @param ctx execution context - * @param backend_url base URL of the backend - * @param initial_balance desired initial balance for the reserve - * @param exchange_url what is the URL of the exchange where the reserve should be set up - * @param wire_method desired wire method, for example "iban" or "x-taler-bank" - * @param cb the callback to call when a reply for this request is available - * @param cb_cls closure for @a cb - * @return a handle for this request - */ -struct TALER_MERCHANT_PostReservesHandle * -TALER_MERCHANT_reserves_post ( - struct GNUNET_CURL_Context *ctx, - const char *backend_url, - const struct TALER_Amount *initial_balance, - const char *exchange_url, - const char *wire_method, - TALER_MERCHANT_PostReservesCallback cb, - void *cb_cls); - - -/** - * Cancel a POST /reserves request. This function cannot be used - * on a request handle if a response is already served for it. - * - * @param prh the operation to cancel - */ -void -TALER_MERCHANT_reserves_post_cancel ( - struct TALER_MERCHANT_PostReservesHandle *prh); - +/* ********************* /kyc ************************** */ /** - * Handle for a GET /reserves operation. + * Handle for getting the KYC status of instance(s). */ -struct TALER_MERCHANT_ReservesGetHandle; +struct TALER_MERCHANT_KycGetHandle; /** - * Information about a reserve. + * Information about KYC actions the merchant still must perform. */ -struct TALER_MERCHANT_ReserveSummary +struct TALER_MERCHANT_AccountKycRedirectDetail { - /** - * Public key of the reserve - */ - struct TALER_ReservePublicKeyP reserve_pub; /** - * Timestamp when it was established + * URL that the user should open in a browser to + * proceed with the KYC process (as returned + * by the exchange's /kyc-check/ endpoint). Can + * be NULL, specifically if KYC is satisfied but + * the transactions are hanging in AML. */ - struct GNUNET_TIME_Timestamp creation_time; + const char *kyc_url; /** - * Timestamp when it expires + * Base URL of the exchange this is about. */ - struct GNUNET_TIME_Timestamp expiration_time; + const char *exchange_url; /** - * Initial amount as per reserve creation call + * Our bank wire account this is about. */ - struct TALER_Amount merchant_initial_amount; + const char *payto_uri; /** - * Initial amount as per exchange, 0 if exchange did - * not confirm reserve creation yet. + * AML state for our account. */ - struct TALER_Amount exchange_initial_amount; + enum TALER_AmlDecisionState aml_status; +}; + +/** + * Information about KYC status failures at the exchange. + */ +struct TALER_MERCHANT_ExchangeKycFailureDetail +{ /** - * Amount picked up so far. + * Base URL of the exchange this is about. */ - struct TALER_Amount pickup_amount; + const char *exchange_url; /** - * Amount approved for tips that exceeds the pickup_amount. + * Error code indicating errors the exchange + * returned, or #TALER_EC_INVALID for none. */ - struct TALER_Amount committed_amount; + enum TALER_ErrorCode exchange_code; /** - * Is this reserve active (false if it was deleted but not purged) + * HTTP status code returned by the exchange when we asked for + * information about the KYC status. + * 0 if there was no response at all. */ - bool active; + unsigned int exchange_http_status; }; /** - * Callback to process a GET /reserves request - * - * @param cls closure - * @param hr HTTP response details - * @param reserves_length length of the @a reserves array - * @param reserves array with details about the reserves, NULL on error - */ -typedef void -(*TALER_MERCHANT_ReservesGetCallback) ( - void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - unsigned int reserves_length, - const struct TALER_MERCHANT_ReserveSummary reserves[]); - - -/** - * Issue a GET /reserves request to the backend. Informs the backend - * that a customer wants to pick up a reserves. - * - * @param ctx execution context - * @param backend_url base URL of the merchant backend - * @param after filter for reserves created after this date, use 0 for no filtering - * @param active filter for reserves that are active - * @param failures filter for reserves where we disagree about the balance with - * the exchange - * @param cb function to call with the result(s) - * @param cb_cls closure for @a cb - * @return handle for this operation, NULL upon errors - */ -struct TALER_MERCHANT_ReservesGetHandle * -TALER_MERCHANT_reserves_get (struct GNUNET_CURL_Context *ctx, - const char *backend_url, - struct GNUNET_TIME_Timestamp after, - enum TALER_EXCHANGE_YesNoAll active, - enum TALER_EXCHANGE_YesNoAll failures, - TALER_MERCHANT_ReservesGetCallback cb, - void *cb_cls); - - -/** - * Cancel a GET /reserves request. - * - * @param rgh handle to the request to be canceled - */ -void -TALER_MERCHANT_reserves_get_cancel ( - struct TALER_MERCHANT_ReservesGetHandle *rgh); - - -/** - * Handle for a request to obtain details on a specific - * (tipping) reserve. - */ -struct TALER_MERCHANT_ReserveGetHandle; - - -/** - * Details about a tip granted by the merchant. + * Details in a response to a GET /kyc request. */ -struct TALER_MERCHANT_TipDetails +struct TALER_MERCHANT_KycResponse { /** - * Identifier for the tip. - */ - struct TALER_TipIdentifierP tip_id; - - /** - * Total value of the tip (including fees). + * HTTP response details. */ - struct TALER_Amount amount; + struct TALER_MERCHANT_HttpResponse hr; /** - * Human-readable reason for why the tip was granted. + * Response details depending on the HTTP status. */ - const char *reason; - -}; - - -/** - * Callback to process a GET /reserve/$RESERVE_PUB request - * - * @param cls closure - * @param hr HTTP response details - * @param rs reserve summary for the reserve, NULL on error - * @param active is this reserve active (false if it was deleted but not purged) - * @param exchange_url URL of the exchange hosting the reserve, NULL if not @a active - * @param payto_uri URI to fill the reserve, NULL if not @a active or already filled - * @param tips_length length of the @a reserves array - * @param tips array with details about the tips granted, NULL on error - */ -typedef void -(*TALER_MERCHANT_ReserveGetCallback) ( - void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - const struct TALER_MERCHANT_ReserveSummary *rs, - bool active, - const char *exchange_url, - const char *payto_uri, - unsigned int tips_length, - const struct TALER_MERCHANT_TipDetails tips[]); + union + { + /** + * Information returned if the status was #MHD_HTTP_ACCEPTED, + * #MHD_HTTP_BAD_GATEWAY or #MHD_HTTP_GATEWAY_TIMEOUT. + */ + struct + { + /** + * Array with information about KYC actions the merchant still must perform. + */ + struct TALER_MERCHANT_AccountKycRedirectDetail *pending_kycs; -/** - * Issue a GET /reserve/$RESERVE_ID request to the backend. Queries the backend - * about the status of a reserve. - * - * @param ctx execution context - * @param backend_url base URL of the merchant backend - * @param reserve_pub which reserve should be queried - * @param fetch_tips should we return details about the tips issued from the reserve - * @param cb function to call with the result(s) - * @param cb_cls closure for @a cb - * @return handle for this operation, NULL upon errors - */ -struct TALER_MERCHANT_ReserveGetHandle * -TALER_MERCHANT_reserve_get (struct GNUNET_CURL_Context *ctx, - const char *backend_url, - const struct TALER_ReservePublicKeyP *reserve_pub, - bool fetch_tips, - TALER_MERCHANT_ReserveGetCallback cb, - void *cb_cls); + /** + * Array with information about KYC failures at the exchange. + */ + struct TALER_MERCHANT_ExchangeKycFailureDetail *timeout_kycs; + /** + * Length of the @e pending_kycs array. + */ + unsigned int pending_kycs_length; -/** - * Cancel a GET /reserve/$RESERVE_ID request. - * - * @param rgh handle to the request to be canceled - */ -void -TALER_MERCHANT_reserve_get_cancel ( - struct TALER_MERCHANT_ReserveGetHandle *rgh); + /** + * Length of the @e timeout_kycs array. + */ + unsigned int timeout_kycs_length; + } kyc_status; + } details; -/** - * Handle for a /tip-authorize operation. - */ -struct TALER_MERCHANT_TipAuthorizeHandle; +}; /** - * Callback for a /reserves/$RESERVE_PUB/tip-authorize request. Returns the result of - * the operation. + * Callback to with a response from a GET [/private]/kyc request * * @param cls closure - * @param hr HTTP response details - * @param tip_id which tip ID should be used to pickup the tip - * @param tip_uri URI for the tip - * @param tip_expiration when does the tip expire + * @param kr response details */ typedef void -(*TALER_MERCHANT_TipAuthorizeCallback) ( +(*TALER_MERCHANT_KycGetCallback) ( void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - struct TALER_TipIdentifierP *tip_id, - const char *tip_uri, - struct GNUNET_TIME_Timestamp tip_expiration); + const struct TALER_MERCHANT_KycResponse *kr); /** - * Issue a /tip-authorize request to the backend. Informs the backend - * that a tip should be created. + * Issue a GET /private/kycs/$KYC_ID (private variant) request to the backend. + * Returns KYC status of bank accounts. * * @param ctx execution context * @param backend_url base URL of the merchant backend - * @param reserve_pub public key of the reserve - * @param next_url where the browser should proceed after picking up the tip - * @param amount amount to be handed out as a tip - * @param justification which justification should be stored (human-readable reason for the tip) - * @param authorize_cb callback which will work the response gotten from the backend - * @param authorize_cb_cls closure to pass to @a authorize_cb + * @param h_wire which bank account to query, NULL for all + * @param exchange_url which exchange to query, NULL for all + * @param timeout how long to wait for a (positive) reply + * @param cb function to call with the result + * @param cb_cls closure for @a cb * @return handle for this operation, NULL upon errors */ -struct TALER_MERCHANT_TipAuthorizeHandle * -TALER_MERCHANT_tip_authorize2 ( +struct TALER_MERCHANT_KycGetHandle * +TALER_MERCHANT_kyc_get ( struct GNUNET_CURL_Context *ctx, const char *backend_url, - const struct TALER_ReservePublicKeyP *reserve_pub, - const char *next_url, - const struct TALER_Amount *amount, - const char *justification, - TALER_MERCHANT_TipAuthorizeCallback authorize_cb, - void *authorize_cb_cls); + const struct TALER_MerchantWireHashP *h_wire, + const char *exchange_url, + struct GNUNET_TIME_Relative timeout, + TALER_MERCHANT_KycGetCallback cb, + void *cb_cls); /** - * Issue a POST /tips request to the backend. Informs the backend that a tip - * should be created. In contrast to #TALER_MERCHANT_tip_authorize2(), the - * backend gets to pick the reserve with this API. + * Issue a GET /management/instances/$INSTANCE/kyc request to the backend. + * Returns KYC status of bank accounts. * * @param ctx execution context * @param backend_url base URL of the merchant backend - * @param next_url where the browser should proceed after picking up the tip - * @param amount amount to be handed out as a tip - * @param justification which justification should be stored (human-readable reason for the tip) - * @param authorize_cb callback which will work the response gotten from the backend - * @param authorize_cb_cls closure to pass to @a authorize_cb + * @param instance_id specific instance to query + * @param h_wire which bank account to query, NULL for all + * @param exchange_url which exchange to query, NULL for all + * @param timeout how long to wait for a (positive) reply + * @param cb function to call with the result + * @param cb_cls closure for @a cb * @return handle for this operation, NULL upon errors */ -struct TALER_MERCHANT_TipAuthorizeHandle * -TALER_MERCHANT_tip_authorize (struct GNUNET_CURL_Context *ctx, - const char *backend_url, - const char *next_url, - const struct TALER_Amount *amount, - const char *justification, - TALER_MERCHANT_TipAuthorizeCallback authorize_cb, - void *authorize_cb_cls); +struct TALER_MERCHANT_KycGetHandle * +TALER_MERCHANT_management_kyc_get ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + const char *instance_id, + const struct TALER_MerchantWireHashP *h_wire, + const char *exchange_url, + struct GNUNET_TIME_Relative timeout, + TALER_MERCHANT_KycGetCallback cb, + void *cb_cls); /** - * Cancel a pending /tip-authorize request + * Cancel a GET [/private]/kyc/$KYC_ID request. * - * @param ta handle from the operation to cancel + * @param kyc handle to the request to be canceled */ void -TALER_MERCHANT_tip_authorize_cancel ( - struct TALER_MERCHANT_TipAuthorizeHandle *ta); +TALER_MERCHANT_kyc_get_cancel ( + struct TALER_MERCHANT_KycGetHandle *kyc); -/** - * Handle for a request to delete or purge a specific reserve. - */ -struct TALER_MERCHANT_ReserveDeleteHandle; +/* ********************* /otp-devices *********************** */ /** - * Callback to process a DELETE /reserve/$RESERVE_PUB request - * - * @param cls closure - * @param hr HTTP response details + * Handle for a GET /otp-devices operation. */ -typedef void -(*TALER_MERCHANT_ReserveDeleteCallback) ( - void *cls, - const struct TALER_MERCHANT_HttpResponse *hr); - +struct TALER_MERCHANT_OtpDevicesGetHandle; /** - * Issue a DELETE /reserve/$RESERVE_ID request to the backend. Only - * deletes the private key of the reserve, preserves tipping data. - * - * @param ctx execution context - * @param backend_url base URL of the merchant backend - * @param reserve_pub which reserve should be queried - * @param cb function to call with the result - * @param cb_cls closure for @a cb - * @return handle for this operation, NULL upon errors + * Individual OTP device (minimal information + * returned via GET /otp-devices). */ -struct TALER_MERCHANT_ReserveDeleteHandle * -TALER_MERCHANT_reserve_delete ( - struct GNUNET_CURL_Context *ctx, - const char *backend_url, - const struct TALER_ReservePublicKeyP *reserve_pub, - TALER_MERCHANT_ReserveDeleteCallback cb, - void *cb_cls); +struct TALER_MERCHANT_OtpDeviceEntry +{ + /** + * OTP device identifier. + */ + const char *otp_device_id; + /** + * OTP device description. + */ + const char *device_description; -/** - * Issue a DELETE /reserve/$RESERVE_ID request to the backend. - * Purges the reserve, deleting all associated data. DANGEROUS. - * - * @param ctx execution context - * @param backend_url base URL of the merchant backend - * @param reserve_pub which reserve should be queried - * @param cb function to call with the result - * @param cb_cls closure for @a cb - * @return handle for this operation, NULL upon errors - */ -struct TALER_MERCHANT_ReserveDeleteHandle * -TALER_MERCHANT_reserve_purge (struct GNUNET_CURL_Context *ctx, - const char *backend_url, - const struct TALER_ReservePublicKeyP *reserve_pub, - TALER_MERCHANT_ReserveDeleteCallback cb, - void *cb_cls); +}; /** - * Cancel a DELETE (or purge) /reserve/$RESERVE_ID request. - * - * @param rdh handle to the request to be canceled + * Response to a GET /otp-devices operation. */ -void -TALER_MERCHANT_reserve_delete_cancel ( - struct TALER_MERCHANT_ReserveDeleteHandle *rdh); - - -/* ********************* /tips ************************** */ +struct TALER_MERCHANT_OtpDevicesGetResponse +{ + /** + * HTTP response details + */ + struct TALER_MERCHANT_HttpResponse hr; + /** + * Details depending on status. + */ + union + { + /** + * Details if status is #MHD_HTTP_OK. + */ + struct + { + /** + * length of the @e otp_devices array + */ + unsigned int otp_devices_length; -/** - * Handle for a GET /tips/$TIP_ID (public variant) operation. - */ -struct TALER_MERCHANT_TipWalletGetHandle; + /** + * array of otp_devices the requested instance offers + */ + const struct TALER_MERCHANT_OtpDeviceEntry *otp_devices; + } ok; + } details; +}; /** - * Callback to process a GET /tips/$TIP_ID request + * Function called with the result of the GET /otp-devices operation. * * @param cls closure - * @param hr HTTP response details - * @param expiration when the tip will expire - * @param exchange_url exchange from which the coins should be withdrawn - * @param amount_remaining total amount still available for the tip + * @param tgr response details */ typedef void -(*TALER_MERCHANT_TipWalletGetCallback) ( +(*TALER_MERCHANT_OtpDevicesGetCallback)( void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - struct GNUNET_TIME_Timestamp expiration, - const char *exchange_url, - const struct TALER_Amount *amount_remaining); + const struct TALER_MERCHANT_OtpDevicesGetResponse *tgr); /** - * Issue a GET /tips/$TIP_ID (public variant) request to the backend. Returns - * information needed to pick up a tip. + * Make a GET /otp-devices request. * - * @param ctx execution context - * @param backend_url base URL of the merchant backend - * @param tip_id which tip should we query - * @param cb function to call with the result + * @param ctx the context + * @param backend_url HTTP base URL for the backend + * @param cb function to call with the backend information * @param cb_cls closure for @a cb - * @return handle for this operation, NULL upon errors + * @return the request handle; NULL upon error */ -struct TALER_MERCHANT_TipWalletGetHandle * -TALER_MERCHANT_wallet_tip_get (struct GNUNET_CURL_Context *ctx, - const char *backend_url, - const struct TALER_TipIdentifierP *tip_id, - TALER_MERCHANT_TipWalletGetCallback cb, - void *cb_cls); +struct TALER_MERCHANT_OtpDevicesGetHandle * +TALER_MERCHANT_otp_devices_get ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + TALER_MERCHANT_OtpDevicesGetCallback cb, + void *cb_cls); /** - * Cancel a GET /tips/$TIP_ID request. + * Cancel GET /otp-devices operation. * - * @param tgh handle to the request to be canceled + * @param tgh operation to cancel */ void -TALER_MERCHANT_wallet_tip_get_cancel ( - struct TALER_MERCHANT_TipWalletGetHandle *tgh); +TALER_MERCHANT_otp_devices_get_cancel ( + struct TALER_MERCHANT_OtpDevicesGetHandle *tgh); /** - * Handle for a GET /private/tips/$TIP_ID (private variant) operation. + * Handle for a GET /otp-device/$ID operation. Gets details + * about a single otp_device. Do not confused with a + * `struct TALER_MERCHANT_OtpDevicesGetHandle`, which + * obtains a list of all otp_devices. */ -struct TALER_MERCHANT_TipMerchantGetHandle; +struct TALER_MERCHANT_OtpDeviceGetHandle; /** - * Summary information for a tip pickup. + * Details in a response to a GET /otp-devices request. */ -struct TALER_MERCHANT_PickupDetail +struct TALER_MERCHANT_OtpDeviceGetResponse { /** - * Identifier of the pickup. - */ - struct TALER_PickupIdentifierP pickup_id; - - /** - * Number of planchets involved. - */ - uint64_t num_planchets; - - /** - * Total amount requested for this pickup. - */ - struct TALER_Amount requested_amount; -}; - - -/** - * Details returned about a tip by the merchant. - */ -struct TALER_MERCHANT_TipStatusResponse -{ - /** - * HTTP status of the response. + * HTTP response details. */ struct TALER_MERCHANT_HttpResponse hr; /** - * Details depending on the HTTP status. + * Response details depending on the HTTP status. */ union { - /** - * Details on #MHD_HTTP_OK. + * Information returned if the status was #MHD_HTTP_OK. */ struct { /** - * Amount that was authorized under this tip - */ - struct TALER_Amount total_authorized; - - /** - * Amount that has been picked up + * description of the otp_device */ - struct TALER_Amount total_picked_up; + const char *otp_device_description; /** - * The reason given for the tip + * POS confirmation text with OTP codes that + * would be returned for a purchase over the + * amount given in the query for the respective + * time and algorithm. NULL if the confirmation + * could not be computed based on the query and + * OTP algorithm. */ - const char *reason; + const char *otp_code; /** - * Time when the tip will expire + * current counter. */ - struct GNUNET_TIME_Timestamp expiration; + uint64_t otp_ctr; /** - * reserve which is funding this tip + * OTP algorithm used. */ - struct TALER_ReservePublicKeyP reserve_pub; + enum TALER_MerchantConfirmationAlgorithm otp_alg; /** - * Length of the @e pickups array + * Timestamp in second used to compute + * @e otp_code. */ - unsigned int pickups_length; + uint64_t otp_timestamp_s; - /** - * array of pickup operations performed for this tip - */ - struct TALER_MERCHANT_PickupDetail *pickups; - } success; + } ok; } details; @@ -3582,577 +4522,446 @@ struct TALER_MERCHANT_TipStatusResponse /** - * Callback to process a GET /private/tips/$TIP_ID request + * Function called with the result of the GET /otp-device/$ID operation. * * @param cls closure - * @param tsr response details + * @param tgr HTTP response details */ typedef void -(*TALER_MERCHANT_TipMerchantGetCallback) ( +(*TALER_MERCHANT_OtpDeviceGetCallback)( void *cls, - const struct TALER_MERCHANT_TipStatusResponse *tsr); + const struct TALER_MERCHANT_OtpDeviceGetResponse *tgr); /** - * Issue a GET /private/tips/$TIP_ID (private variant) request to the backend. - * Returns information needed to pick up a tip. - * - * FIXME: lp_timeout/min_pick_up not implemented in backend! + * Make a GET /otp-device/$ID request to get details about an + * individual OTP device. * - * @param ctx execution context - * @param backend_url base URL of the merchant backend - * @param tip_id which tip should we query - * @param min_pick_up minimum amount picked up to notify about - * @param lp_timeout how long to wait for @a min_pick_up to be exceeded - * @param pickups whether to fetch associated pickups - * @param cb function to call with the result + * @param ctx the context + * @param backend_url HTTP base URL for the backend + * @param otp_device_id identifier of the otp_device to inquire about + * @param cb function to call with the backend's otp_device information * @param cb_cls closure for @a cb - * @return handle for this operation, NULL upon errors + * @return the request handle; NULL upon error */ -struct TALER_MERCHANT_TipMerchantGetHandle * -TALER_MERCHANT_merchant_tip_get (struct GNUNET_CURL_Context *ctx, - const char *backend_url, - const struct TALER_TipIdentifierP *tip_id, - const struct TALER_Amount *min_pick_up, - struct GNUNET_TIME_Relative lp_timeout, - bool pickups, - TALER_MERCHANT_TipMerchantGetCallback cb, - void *cb_cls); +struct TALER_MERCHANT_OtpDeviceGetHandle * +TALER_MERCHANT_otp_device_get ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + const char *otp_device_id, + TALER_MERCHANT_OtpDeviceGetCallback cb, + void *cb_cls); /** - * Cancel a GET /private/tips/$TIP_ID request. + * Cancel GET /otp-devices/$ID operation. * - * @param tgh handle to the request to be canceled + * @param tgh operation to cancel */ void -TALER_MERCHANT_merchant_tip_get_cancel ( - struct TALER_MERCHANT_TipMerchantGetHandle *tgh); +TALER_MERCHANT_otp_device_get_cancel ( + struct TALER_MERCHANT_OtpDeviceGetHandle *tgh); /** - * Handle for a GET /private/tips request. + * Handle for a POST /otp-devices operation. */ -struct TALER_MERCHANT_TipsGetHandle; +struct TALER_MERCHANT_OtpDevicesPostHandle; /** - * Database entry information of a tip. - */ -struct TALER_MERCHANT_TipEntry -{ - /** - * Row number of the tip in the database. - */ - uint64_t row_id; - - /** - * Identifier for the tip. - */ - struct TALER_TipIdentifierP tip_id; - - /** - * Total value of the tip (including fees). - */ - struct TALER_Amount tip_amount; - -}; - - -/** - * Callback to process a GET /private/tips request. + * Function called with the result of the POST /otp-devices operation. * * @param cls closure * @param hr HTTP response details - * @param tips_length length of the @a tips array - * @param tips the array of tips, NULL on error */ typedef void -(*TALER_MERCHANT_TipsGetCallback) ( +(*TALER_MERCHANT_OtpDevicesPostCallback)( void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - unsigned int tips_length, - const struct TALER_MERCHANT_TipEntry tips[]); - - -/** - * Issue a GET /private/tips request to the backend. - * - * @param ctx execution context - * @param backend_url base URL of the merchant backend - * @param cb function to call with the result - * @param cb_cls closure for @a cb - * @return handle for this operation, NULL upon errors - */ -struct TALER_MERCHANT_TipsGetHandle * -TALER_MERCHANT_tips_get (struct GNUNET_CURL_Context *ctx, - const char *backend_url, - TALER_MERCHANT_TipsGetCallback cb, - void *cb_cls); + const struct TALER_MERCHANT_HttpResponse *hr); /** - * Issue a GET /private/tips request with filters to the backend. + * Make a POST /otp-devices request to add an OTP device * - * @param ctx execution context - * @param backend_url base URL of the merchant backend - * @param expired yes for expired tips, no for unexpired tips, all for all tips - * @param limit number of results to return, negative for descending row id, positive for ascending - * @param offset row id to start returning results from - * @param cb function to call with the result + * @param ctx the context + * @param backend_url HTTP base URL for the backend + * @param otp_id identifier to use for the OTP device + * @param otp_device_description description of the OTP device + * @param otp_key key of the OTP device + * @param otp_alg OTP algorithm used + * @param otp_ctr counter for counter-based OTP + * @param cb function to call with the backend's result * @param cb_cls closure for @a cb - * @return handle for this operation, NULL upon errors + * @return the request handle; NULL upon error */ -struct TALER_MERCHANT_TipsGetHandle * -TALER_MERCHANT_tips_get2 (struct GNUNET_CURL_Context *ctx, - const char *backend_url, - enum TALER_EXCHANGE_YesNoAll expired, - int64_t limit, - uint64_t offset, - TALER_MERCHANT_TipsGetCallback cb, - void *cb_cls); +struct TALER_MERCHANT_OtpDevicesPostHandle * +TALER_MERCHANT_otp_devices_post ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + const char *otp_id, + const char *otp_device_description, + const char *otp_key, + enum TALER_MerchantConfirmationAlgorithm otp_alg, + uint64_t otp_ctr, + TALER_MERCHANT_OtpDevicesPostCallback cb, + void *cb_cls); /** - * Cancel a GET /private/tips request. + * Cancel POST /otp-devices operation. * - * @param tgh the operation to cancel + * @param[in] tph operation to cancel */ void -TALER_MERCHANT_tips_get_cancel (struct TALER_MERCHANT_TipsGetHandle *tgh); +TALER_MERCHANT_otp_devices_post_cancel ( + struct TALER_MERCHANT_OtpDevicesPostHandle *tph); /** - * Handle for a POST /tips/$TIP_ID/pickup operation. + * Handle for a PATCH /otp-device operation. */ -struct TALER_MERCHANT_TipPickupHandle; - - -/** - * Details about a pickup operation, as returned to the application. - */ -struct TALER_MERCHANT_PickupDetails -{ - /** - * HTTP response data. - */ - struct TALER_MERCHANT_HttpResponse hr; - - /** - * Details about the response. - */ - union - { - /** - * Details if the status is #MHD_HTTP_OK. - */ - struct - { - - /** - * Array of length @e num_sigs with details about each of the coins that - * were picked up. - */ - struct TALER_EXCHANGE_PrivateCoinDetails *pcds; - - /** - * Length of the @e pcds array. - */ - unsigned int num_sigs; - } success; - - } details; - -}; +struct TALER_MERCHANT_OtpDevicePatchHandle; /** - * Callback for a POST /tips/$TIP_ID/pickup request. Returns the result of - * the operation. + * Function called with the result of the PATCH /otp-device operation. * * @param cls closure - * @param pd HTTP response details + * @param hr HTTP response details */ typedef void -(*TALER_MERCHANT_TipPickupCallback) ( +(*TALER_MERCHANT_OtpDevicePatchCallback)( void *cls, - const struct TALER_MERCHANT_PickupDetails *pd); - - -/** - * Information per planchet. - */ -struct TALER_MERCHANT_PlanchetData -{ - /** - * Planchet secrets. - */ - struct TALER_PlanchetMasterSecretP ps; + const struct TALER_MERCHANT_HttpResponse *hr); - /** - * Denomination key desired. - */ - const struct TALER_EXCHANGE_DenomPublicKey *pk; - -}; /** - * Issue a POST /tips/$TIP_ID/pickup request to the backend. Informs the - * backend that a customer wants to pick up a tip. + * Make a PATCH /otp-device request to update OTP device details * - * @param ctx execution context - * @param exchange handle to the exchange we are picking up the tip from - * @param backend_url base URL of the merchant backend - * @param tip_id unique identifier for the tip - * @param num_planchets number of planchets provided in @a pds - * @param planchets array of planchet secrets to be signed into existence for the tip - * @param pickup_cb callback which will work the response gotten from the backend - * @param pickup_cb_cls closure to pass to @a pickup_cb - * @return handle for this operation, NULL upon errors + * @param ctx the context + * @param backend_url HTTP base URL for the backend + * @param otp_id identifier to use for the OTP device; the OTP device must exist, + * or the transaction will fail with a #MHD_HTTP_NOT_FOUND + * HTTP status code + * @param otp_device_description description of the otp_device + * @param otp_key key of the OTP device + * @param otp_alg OTP algorithm used + * @param otp_ctr counter for counter-based OTP + * @param cb function to call with the backend's result + * @param cb_cls closure for @a cb + * @return the request handle; NULL upon error */ -struct TALER_MERCHANT_TipPickupHandle * -TALER_MERCHANT_tip_pickup (struct GNUNET_CURL_Context *ctx, - struct TALER_EXCHANGE_Handle *exchange, - const char *backend_url, - const struct TALER_TipIdentifierP *tip_id, - unsigned int num_planchets, - const struct TALER_MERCHANT_PlanchetData planchets[], - TALER_MERCHANT_TipPickupCallback pickup_cb, - void *pickup_cb_cls); +struct TALER_MERCHANT_OtpDevicePatchHandle * +TALER_MERCHANT_otp_device_patch ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + const char *otp_id, + const char *otp_device_description, + const char *otp_key, + enum TALER_MerchantConfirmationAlgorithm otp_alg, + uint64_t otp_ctr, + TALER_MERCHANT_OtpDevicePatchCallback cb, + void *cb_cls); /** - * Cancel a pending /tips/$TIP_ID/pickup request + * Cancel PATCH /otp-device operation. * - * @param tph handle from the operation to cancel + * @param[in] tph operation to cancel */ void -TALER_MERCHANT_tip_pickup_cancel (struct TALER_MERCHANT_TipPickupHandle *tph); +TALER_MERCHANT_otp_device_patch_cancel ( + struct TALER_MERCHANT_OtpDevicePatchHandle *tph); /** - * Handle for a low-level /tip-pickup operation (without unblinding). + * Handle for a DELETE /otp-device/$ID operation. */ -struct TALER_MERCHANT_TipPickup2Handle; +struct TALER_MERCHANT_OtpDeviceDeleteHandle; /** - * Callback for a POST /tips/$TIP_ID/pickup request. Returns the result of - * the operation. Note that the client MUST still do the unblinding of the @a - * blind_sigs. + * Function called with the result of the DELETE /otp-device/$ID operation. * * @param cls closure * @param hr HTTP response details - * @param num_blind_sigs length of the @a blind_sigs array, 0 on error - * @param blind_sigs array of blind signatures over the planchets, NULL on error */ typedef void -(*TALER_MERCHANT_TipPickup2Callback) ( +(*TALER_MERCHANT_OtpDeviceDeleteCallback)( void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - unsigned int num_blind_sigs, - const struct TALER_BlindedDenominationSignature blind_sigs[]); + const struct TALER_MERCHANT_HttpResponse *hr); /** - * Issue a POST /tips/$TIP_ID/pickup request to the backend. Informs the - * backend that a customer wants to pick up a tip. + * Make a DELETE /otp-device/$ID request to delete an OTP device. * - * @param ctx execution context - * @param backend_url base URL of the merchant backend - * @param tip_id unique identifier for the tip - * @param num_planchets number of planchets provided in @a planchets - * @param planchets array of planchets to be signed into existence for the tip - * @param pickup_cb callback which will work the response gotten from the backend - * @param pickup_cb_cls closure to pass to @a pickup_cb - * @return handle for this operation, NULL upon errors + * @param ctx the context + * @param backend_url HTTP base URL for the backend + * @param otp_device_id identifier of the OTP device + * @param cb function to call with the backend's deletion status + * @param cb_cls closure for @a cb + * @return the request handle; NULL upon error */ -struct TALER_MERCHANT_TipPickup2Handle * -TALER_MERCHANT_tip_pickup2 (struct GNUNET_CURL_Context *ctx, - const char *backend_url, - const struct TALER_TipIdentifierP *tip_id, - unsigned int num_planchets, - const struct TALER_PlanchetDetail planchets[], - TALER_MERCHANT_TipPickup2Callback pickup_cb, - void *pickup_cb_cls); +struct TALER_MERCHANT_OtpDeviceDeleteHandle * +TALER_MERCHANT_otp_device_delete ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + const char *otp_device_id, + TALER_MERCHANT_OtpDeviceDeleteCallback cb, + void *cb_cls); /** - * Cancel a pending /tip-pickup request. + * Cancel DELETE /otp-device/$ID operation. * - * @param tp handle from the operation to cancel + * @param[in] tdh operation to cancel */ void -TALER_MERCHANT_tip_pickup2_cancel ( - struct TALER_MERCHANT_TipPickup2Handle *tp); +TALER_MERCHANT_otp_device_delete_cancel ( + struct TALER_MERCHANT_OtpDeviceDeleteHandle *tdh); -/* ********************* /kyc ************************** */ - -/** - * Handle for getting the KYC status of instance(s). - */ -struct TALER_MERCHANT_KycGetHandle; +/* ********************* /templates *********************** */ /** - * Information about KYC actions the merchant still must perform. + * Handle for a GET /templates operation. */ -struct TALER_MERCHANT_AccountKycRedirectDetail -{ - - /** - * URL that the user should open in a browser to - * proceed with the KYC process (as returned - * by the exchange's /kyc-check/ endpoint). - */ - const char *kyc_url; - - /** - * Base URL of the exchange this is about. - */ - const char *exchange_url; - - /** - * Our bank wire account this is about. - */ - const char *payto_uri; -}; - +struct TALER_MERCHANT_TemplatesGetHandle; /** - * Information about KYC status failures at the exchange. + * Individual template (minimal information + * returned via GET /templates). */ -struct TALER_MERCHANT_ExchangeKycFailureDetail +struct TALER_MERCHANT_TemplateEntry { /** - * Base URL of the exchange this is about. - */ - const char *exchange_url; - - /** - * Error code indicating errors the exchange - * returned, or #TALER_EC_INVALID for none. + * template identifier. */ - enum TALER_ErrorCode exchange_code; + const char *template_id; - /** - * HTTP status code returned by the exchange when we asked for - * information about the KYC status. - * 0 if there was no response at all. - */ - unsigned int exchange_http_status; }; /** - * Details in a response to a GET /kyc request. + * Response to a GET /templates operation. */ -struct TALER_MERCHANT_KycResponse +struct TALER_MERCHANT_TemplatesGetResponse { /** - * HTTP response details. + * HTTP response details */ struct TALER_MERCHANT_HttpResponse hr; /** - * Response details depending on the HTTP status. + * Details depending on status. */ union { /** - * Information returned if the status was #MHD_HTTP_ACCEPTED, - * #MHD_HTTP_BAD_GATEWAY or #MHD_HTTP_GATEWAY_TIMEOUT. + * Details if status is #MHD_HTTP_OK. */ struct { - - /** - * Array with information about KYC actions the merchant still must perform. - */ - struct TALER_MERCHANT_AccountKycRedirectDetail *pending_kycs; - - /** - * Array with information about KYC failures at the exchange. - */ - struct TALER_MERCHANT_ExchangeKycFailureDetail *timeout_kycs; - /** - * Length of the @e pending_kycs array. + * length of the @e templates array */ - unsigned int pending_kycs_length; + unsigned int templates_length; /** - * Length of the @e timeout_kycs array. + * array of templates the requested instance offers */ - unsigned int timeout_kycs_length; - } kyc_status; - + const struct TALER_MERCHANT_TemplateEntry *templates; + } ok; } details; - }; /** - * Callback to with a response from a GET [/private]/kyc request + * Function called with the result of the GET /templates operation. * * @param cls closure - * @param kr response details + * @param tgr response details */ typedef void -(*TALER_MERCHANT_KycGetCallback) ( +(*TALER_MERCHANT_TemplatesGetCallback)( void *cls, - const struct TALER_MERCHANT_KycResponse *kr); + const struct TALER_MERCHANT_TemplatesGetResponse *tgr); /** - * Issue a GET /private/kycs/$KYC_ID (private variant) request to the backend. - * Returns KYC status of bank accounts. - * - * @param ctx execution context - * @param backend_url base URL of the merchant backend - * @param h_wire which bank account to query, NULL for all - * @param exchange_url which exchange to query, NULL for all - * @param timeout how long to wait for a (positive) reply - * @param cb function to call with the result - * @param cb_cls closure for @a cb - * @return handle for this operation, NULL upon errors - */ -struct TALER_MERCHANT_KycGetHandle * -TALER_MERCHANT_kyc_get (struct GNUNET_CURL_Context *ctx, - const char *backend_url, - const struct TALER_MerchantWireHashP *h_wire, - const char *exchange_url, - struct GNUNET_TIME_Relative timeout, - TALER_MERCHANT_KycGetCallback cb, - void *cb_cls); - - -/** - * Issue a GET /management/instances/$INSTANCE/kyc request to the backend. - * Returns KYC status of bank accounts. + * Make a GET /templates request. * - * @param ctx execution context - * @param backend_url base URL of the merchant backend - * @param instance_id specific instance to query - * @param h_wire which bank account to query, NULL for all - * @param exchange_url which exchange to query, NULL for all - * @param timeout how long to wait for a (positive) reply - * @param cb function to call with the result + * @param ctx the context + * @param backend_url HTTP base URL for the backend + * @param cb function to call with the backend information * @param cb_cls closure for @a cb - * @return handle for this operation, NULL upon errors + * @return the request handle; NULL upon error */ -struct TALER_MERCHANT_KycGetHandle * -TALER_MERCHANT_management_kyc_get (struct GNUNET_CURL_Context *ctx, - const char *backend_url, - const char *instance_id, - const struct TALER_MerchantWireHashP *h_wire, - const char *exchange_url, - struct GNUNET_TIME_Relative timeout, - TALER_MERCHANT_KycGetCallback cb, - void *cb_cls); +struct TALER_MERCHANT_TemplatesGetHandle * +TALER_MERCHANT_templates_get ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + TALER_MERCHANT_TemplatesGetCallback cb, + void *cb_cls); /** - * Cancel a GET [/private]/kyc/$KYC_ID request. + * Cancel GET /templates operation. * - * @param kyc handle to the request to be canceled + * @param tgh operation to cancel */ void -TALER_MERCHANT_kyc_get_cancel ( - struct TALER_MERCHANT_KycGetHandle *kyc); - - -/* ********************* /templates *********************** */ +TALER_MERCHANT_templates_get_cancel ( + struct TALER_MERCHANT_TemplatesGetHandle *tgh); /** - * Handle for a GET /templates operation. + * Handle for a GET /private/template/$ID operation. Gets details + * about a single template. Do not confused with a + * `struct TALER_MERCHANT_TemplatesGetHandle`, which + * obtains a list of all templates. */ -struct TALER_MERCHANT_TemplatesGetHandle; +struct TALER_MERCHANT_TemplateGetHandle; + /** - * Individual template (minimal information - * returned via GET /templates). + * Details in a response to a GET /private/templates/$ID request. */ -struct TALER_MERCHANT_TemplateEntry +struct TALER_MERCHANT_TemplateGetResponse { /** - * template identifier. + * HTTP response details. */ - const char *template_id; + struct TALER_MERCHANT_HttpResponse hr; + + /** + * Response details depending on the HTTP status. + */ + union + { + /** + * Information returned if the status was #MHD_HTTP_OK. + */ + struct + { + + /** + * description of the template + */ + const char *template_description; + + /** + * OTP device ID used by the POS, NULL if none. + */ + const char *otp_id; + + /** + * Template for the contract. + */ + const json_t *template_contract; + + } ok; + + } details; }; /** - * Function called with the result of the GET /templates operation. + * Function called with the result of the GET /private/template/$ID operation. * * @param cls closure - * @param hr HTTP response details - * @param templates_length length of the @a templates array - * @param templates array of templates the requested instance offers + * @param tgr HTTP response details */ typedef void -(*TALER_MERCHANT_TemplatesGetCallback)( +(*TALER_MERCHANT_TemplateGetCallback)( void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - unsigned int templates_length, - const struct TALER_MERCHANT_TemplateEntry templates[]); + const struct TALER_MERCHANT_TemplateGetResponse *tgr); /** - * Make a GET /templates request. + * Make a GET /private/template/$ID request to get details about an + * individual template. * * @param ctx the context * @param backend_url HTTP base URL for the backend - * @param cb function to call with the backend information + * @param template_id identifier of the template to inquire about + * @param cb function to call with the backend's template information * @param cb_cls closure for @a cb * @return the request handle; NULL upon error */ -struct TALER_MERCHANT_TemplatesGetHandle * -TALER_MERCHANT_templates_get ( +struct TALER_MERCHANT_TemplateGetHandle * +TALER_MERCHANT_template_get ( struct GNUNET_CURL_Context *ctx, const char *backend_url, - TALER_MERCHANT_TemplatesGetCallback cb, + const char *template_id, + TALER_MERCHANT_TemplateGetCallback cb, void *cb_cls); /** - * Cancel GET /templates operation. + * Cancel GET /private/templates/$ID operation. * * @param tgh operation to cancel */ void -TALER_MERCHANT_templates_get_cancel ( - struct TALER_MERCHANT_TemplatesGetHandle *tgh); +TALER_MERCHANT_template_get_cancel ( + struct TALER_MERCHANT_TemplateGetHandle *tgh); /** - * Handle for a GET /template/$ID operation. Gets details - * about a single template. Do not confused with a - * `struct TALER_MERCHANT_TemplatesGetHandle`, which - * obtains a list of all templates. + * Handle for a (public) GET /template/$ID operation. Gets details about a + * single template. Do not confused with a `struct + * TALER_MERCHANT_TemplateGetHandle`, which is for the private API. */ -struct TALER_MERCHANT_TemplateGetHandle; +struct TALER_MERCHANT_WalletTemplateGetHandle; /** - * Function called with the result of the GET /templates operation. + * Details in a response to a GET /templates request. + */ +struct TALER_MERCHANT_WalletTemplateGetResponse +{ + /** + * HTTP response details. + */ + struct TALER_MERCHANT_HttpResponse hr; + + /** + * Response details depending on the HTTP status. + */ + union + { + /** + * Information returned if the status was #MHD_HTTP_OK. + */ + struct + { + + /** + * Template for the contract. + */ + const json_t *template_contract; + + } ok; + + } details; + +}; + + +/** + * Function called with the result of the GET /template/$ID operation. * * @param cls closure - * @param hr HTTP response details - * @param template_description description of the template - * @param image base64-encoded product image - * @param template_contract is the contract of the company + * @param tgr HTTP response details */ typedef void -(*TALER_MERCHANT_TemplateGetCallback)( +(*TALER_MERCHANT_WalletTemplateGetCallback)( void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - const char *template_description, - const char *image, - const json_t *template_contract); + const struct TALER_MERCHANT_WalletTemplateGetResponse *tgr); /** @@ -4166,12 +4975,12 @@ typedef void * @param cb_cls closure for @a cb * @return the request handle; NULL upon error */ -struct TALER_MERCHANT_TemplateGetHandle * -TALER_MERCHANT_template_get ( +struct TALER_MERCHANT_WalletTemplateGetHandle * +TALER_MERCHANT_wallet_template_get ( struct GNUNET_CURL_Context *ctx, const char *backend_url, const char *template_id, - TALER_MERCHANT_TemplateGetCallback cb, + TALER_MERCHANT_WalletTemplateGetCallback cb, void *cb_cls); @@ -4181,8 +4990,8 @@ TALER_MERCHANT_template_get ( * @param tgh operation to cancel */ void -TALER_MERCHANT_template_get_cancel ( - struct TALER_MERCHANT_TemplateGetHandle *tgh); +TALER_MERCHANT_wallet_template_get_cancel ( + struct TALER_MERCHANT_WalletTemplateGetHandle *tgh); /** @@ -4210,7 +5019,7 @@ typedef void * @param backend_url HTTP base URL for the backend * @param template_id identifier to use for the template * @param template_description description of the template - * @param image base64-encoded product image + * @param otp_id ID of the OTP device, or NULL if OTP is not used * @param template_contract is the contract of the company * @param cb function to call with the backend's result * @param cb_cls closure for @a cb @@ -4222,7 +5031,7 @@ TALER_MERCHANT_templates_post ( const char *backend_url, const char *template_id, const char *template_description, - const char *image, + const char *otp_id, const json_t *template_contract, TALER_MERCHANT_TemplatesPostCallback cb, void *cb_cls); @@ -4231,7 +5040,7 @@ TALER_MERCHANT_templates_post ( /** * Cancel POST /templates operation. * - * @param tph operation to cancel + * @param[in] tph operation to cancel */ void TALER_MERCHANT_templates_post_cancel ( @@ -4265,7 +5074,7 @@ typedef void * or the transaction will fail with a #MHD_HTTP_NOT_FOUND * HTTP status code * @param template_description description of the template - * @param image base64-encoded product image + * @param otp_id device ID of the OTP device, or NULL if OTP is not used * @param template_contract is the contract of the company * @param cb function to call with the backend's result * @param cb_cls closure for @a cb @@ -4277,7 +5086,7 @@ TALER_MERCHANT_template_patch ( const char *backend_url, const char *template_id, const char *template_description, - const char *image, + const char *otp_id, json_t *template_contract, TALER_MERCHANT_TemplatePatchCallback cb, void *cb_cls); @@ -4286,7 +5095,7 @@ TALER_MERCHANT_template_patch ( /** * Cancel PATCH /template operation. * - * @param tph operation to cancel + * @param[in] tph operation to cancel */ void TALER_MERCHANT_template_patch_cancel ( @@ -4333,7 +5142,7 @@ TALER_MERCHANT_template_delete ( /** * Cancel DELETE /template/$ID operation. * - * @param tdh operation to cancel + * @param[in] tdh operation to cancel */ void TALER_MERCHANT_template_delete_cancel ( @@ -4366,7 +5175,7 @@ TALER_MERCHANT_using_templates_post ( /** * Cancel POST /using-templates operation. * - * @param utph operation to cancel + * @param[in] utph operation to cancel */ void TALER_MERCHANT_using_templates_post_cancel ( @@ -4396,19 +5205,51 @@ struct TALER_MERCHANT_WebhookEntry /** + * Response to a GET /webhooks operation. + */ +struct TALER_MERCHANT_WebhooksGetResponse +{ + /** + * HTTP response details + */ + struct TALER_MERCHANT_HttpResponse hr; + + /** + * Details depending on status. + */ + union + { + /** + * Details if status is #MHD_HTTP_OK. + */ + struct + { + /** + * length of the @e webhooks array + */ + unsigned int webhooks_length; + + /** + * array of templates the requested instance offers + */ + const struct TALER_MERCHANT_WebhookEntry *webhooks; + + } ok; + + } details; +}; + + +/** * Function called with the result of the GET /webhooks operation. * * @param cls closure - * @param hr HTTP response details - * @param webhooks_length length of the @a webhooks array - * @param webhooks array of webhooks the requested instance offers + * @param wgr response details */ typedef void (*TALER_MERCHANT_WebhooksGetCallback)( void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - unsigned int webhooks_length, - const struct TALER_MERCHANT_WebhookEntry webhooks[]); + const struct TALER_MERCHANT_WebhooksGetResponse *wgr); /** @@ -4431,7 +5272,7 @@ TALER_MERCHANT_webhooks_get ( /** * Cancel GET /webhooks operation. * - * @param tgh operation to cancel + * @param[in] tgh operation to cancel */ void TALER_MERCHANT_webhooks_get_cancel ( @@ -4492,7 +5333,7 @@ TALER_MERCHANT_webhook_get ( /** * Cancel GET /webhooks/$ID operation. * - * @param tgh operation to cancel + * @param[in] tgh operation to cancel */ void TALER_MERCHANT_webhook_get_cancel ( @@ -4549,7 +5390,7 @@ TALER_MERCHANT_webhooks_post ( /** * Cancel POST /webhooks operation. * - * @param wph operation to cancel + * @param[in] wph operation to cancel */ void TALER_MERCHANT_webhooks_post_cancel ( @@ -4608,7 +5449,7 @@ TALER_MERCHANT_webhook_patch ( /** * Cancel PATCH /webhook operation. * - * @param wph operation to cancel + * @param[in] wph operation to cancel */ void TALER_MERCHANT_webhook_patch_cancel ( @@ -4655,7 +5496,7 @@ TALER_MERCHANT_webhook_delete ( /** * Cancel DELETE /webhook/$ID operation. * - * @param wdh operation to cancel + * @param[in] wdh operation to cancel */ void TALER_MERCHANT_webhook_delete_cancel ( |