diff options
Diffstat (limited to 'src/include/taler_merchant_service.h')
| -rw-r--r-- | src/include/taler_merchant_service.h | 268 |
1 files changed, 199 insertions, 69 deletions
diff --git a/src/include/taler_merchant_service.h b/src/include/taler_merchant_service.h index 170e627f..1e62f4ed 100644 --- a/src/include/taler_merchant_service.h +++ b/src/include/taler_merchant_service.h @@ -1104,6 +1104,7 @@ TALER_MERCHANT_product_delete_cancel ( /** * Handle to a POST /orders operation */ +// FIXME: rename: Operation => Handle! struct TALER_MERCHANT_PostOrdersOperation; /** @@ -2146,22 +2147,19 @@ TALER_MERCHANT_post_order_refund_cancel ( struct TALER_MERCHANT_OrderRefundHandle *orh); -/* ********************* OLD ************************** */ - - -/* ********************* /track/transfer *********************** */ +/* ********************* /transfers *********************** */ /** - * @brief Handle to a /track/transfer operation at a merchant's backend. + * @brief Handle to a POST /transfers operation at a merchant's backend. */ -struct TALER_MERCHANT_TrackTransferHandle; +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. */ -struct TALER_MERCHANT_TrackTransferDetails +struct TALER_MERCHANT_TrackTransferDetail { /** @@ -2182,14 +2180,18 @@ struct TALER_MERCHANT_TrackTransferDetails }; /** - * Callbacks of this type are used to work the result of submitting a /track/transfer request to a merchant + * 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 sign_key exchange key used to sign @a json, or NULL - * @param h_wire hash of the wire transfer address the transfer went to, or NULL on error - * @param total_amount total amount of the wire transfer, or NULL if the exchange could - * not provide any @a wtid (set only if @a http_status is #MHD_HTTP_OK) + * @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 */ @@ -2197,125 +2199,177 @@ typedef void (*TALER_MERCHANT_TrackTransferCallback) ( void *cls, const struct TALER_MERCHANT_HttpResponse *hr, - const struct TALER_ExchangePublicKeyP *sign_key, - const struct GNUNET_HashCode *h_wire, + struct GNUNET_TIME_Absolute execution_time, const struct TALER_Amount *total_amount, + const struct TALER_Amount *wire_fee, unsigned int details_length, - const struct TALER_MERCHANT_TrackTransferDetails *details); + const struct TALER_MERCHANT_TrackTransferDetails details[]); /** - * Request backend to return deposits associated with a given wtid. + * Request backend to remember that we received the given + * wire transfer and to request details about the aggregated + * transactions from the exchange. * * @param ctx execution context * @param backend_url base URL of the backend - * @param wire_method wire method used for the wire transfer + * @param credit_amount how much money did we receive (without wire fee) * @param wtid base32 string indicating a wtid - * @param exchange base URL of the exchange in charge of returning the wanted information - * @param track_transfer_cb the callback to call when a reply for this request is available - * @param track_transfer_cb_cls closure for @a track_transfer_cb + * @param payto_uri which account was credited by the wire transfer + * @param exchange_url what is the URL of the exchange that made the transfer + * @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_TrackTransferHandle * -TALER_MERCHANT_track_transfer ( +struct TALER_MERCHANT_PostTransfersHandle * +TALER_MERCHANT_transfers_post ( struct GNUNET_CURL_Context *ctx, const char *backend_url, - const char *wire_method, + const struct TALER_Amount *credit_amount, const struct TALER_WireTransferIdentifierRawP *wtid, + const char *payto_uri, const char *exchange_url, - TALER_MERCHANT_TrackTransferCallback - track_transfer_cb, - void *track_transfer_cb_cls); + TALER_MERCHANT_TrackTransferCallback cb, + void *cls); /** - * Cancel a /track/transfer request. This function cannot be used + * Cancel a POST /transfers request. This function cannot be used * on a request handle if a response is already served for it. * - * @param co the deposit's tracking operation + * @param pth the operation to cancel */ void -TALER_MERCHANT_track_transfer_cancel ( - struct TALER_MERCHANT_TrackTransferHandle *tdo); - +TALER_MERCHANT_transfers_post_cancel ( + struct TALER_MERCHANT_PostTransfersHandle *pth); -/* ********************* /track/transaction *********************** */ /** - * @brief Handle to a /track/transaction operation at a merchant's backend. + * @brief Handle to a GET /transfers operation at a merchant's backend. */ -struct TALER_MERCHANT_TrackTransactionHandle; +struct TALER_MERCHANT_GetTransfersHandle; /** - * Information about a coin aggregated in a wire transfer for a - * /track/transaction response. + * Information about the _total_ amount that was paid back + * by the exchange for a given h_contract_terms, by _one_ wire + * transfer. */ -struct TALER_MERCHANT_CoinWireTransfer +struct TALER_MERCHANT_TransferData { /** - * Public key of the coin. + * Total amount wired by the exchange (without wire fee) */ - struct TALER_CoinSpendPublicKeyP coin_pub; + struct TALER_Amount credit_amount; /** - * Value of the coin including deposit fee. + * Wire transfer identifier used. */ - struct TALER_Amount amount_with_fee; + struct TALER_WireTransferIdentifierRawP wtid; /** - * Deposit fee for the coin. + * URI of the target account. */ - struct TALER_Amount deposit_fee; + const char *payto_uri; -}; + /** + * URL of the exchange that made the transfer. + */ + const char *exchange_url; + /** + * Serial number of the credit operation in the merchant backend. + */ + uint64_t credit_serial; + + /** + * Time of the wire transfer, according to the exchange. + */ + struct GNUNET_TIME_Absolute execution_time; + + /** + * Did we check the exchange's answer and are happy about it? False + * if we did not check or are unhappy with the answer. + */ + bool verified; + + /** + * Did we confirm the wire transfer happened (via #TALER_MERCHANT_transfers_post())? + */ + bool confirmed; + +}; /** * Callbacks of this type are used to work the result of submitting a - * /track/transaction request to a merchant + * GET /transfers request to a merchant * * @param cls closure - * @param http_status HTTP status code we got, 0 on exchange protocol violation - * @param ec taler-specific error code - * @param json original json reply from the backend - * @param num_transfers number of wire transfers the exchange used for the transaction - * @param transfers details about each transfer and which coins are aggregated in it -*/ + * @param hr HTTP response details + * @param transfers_length length of the @a transfers array + * @param transfers array with details about the transfers we received + */ typedef void -(*TALER_MERCHANT_TrackTransactionCallback) ( +(*TALER_MERCHANT_GetTransfersCallback) ( void *cls, - const struct TALER_MERCHANT_HttpResponse *hr); + const struct TALER_MERCHANT_HttpResponse *hr, + unsigned int transfers_length, + const struct TALER_MERCHANT_TransferData transfers[]); /** - * Request backend to return deposits associated with a given wtid. + * Request backend to return list of all wire transfers that + * we received (or that the exchange claims we should have received). + * + * Note that when filtering by timestamp (using “before” and/or “after”), we + * use the time reported by the exchange and thus will ONLY return results for + * which we already have a response from the exchange. This should be + * virtually all transfers, however it is conceivable that for some transfer + * the exchange responded with a temporary error (i.e. HTTP status 500+) and + * then we do not yet have an execution time to filter by. Thus, IF timestamp + * filters are given, transfers for which we have no response from the + * exchange yet are automatically excluded. * * @param ctx execution context * @param backend_url base URL of the backend - * @param order_id which order should we trace - * @param track_transaction_cb the callback to call when a reply for this request is available - * @param track_transaction_cb_cls closure for @a track_transaction_cb + * @param payto_uri filter by this credit account of the merchant + * @param before limit to transactions before this timestamp, use + * #GNUNET_TIME_UNIT_FOREVER_ABS to not filter by @a before + * @param after limit to transactions after this timestamp, use + * #GNUNET_TIME_UNIT_ZERO_ABS to not filter by @a after + * @param limit return at most ths number of results; negative to descend in execution time + * @param offset start at this "credit serial" number (exclusive) + * @param verified filter results by verification status + * @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_TrackTransactionHandle * -TALER_MERCHANT_track_transaction ( +struct TALER_MERCHANT_GetTransfersHandle * +TALER_MERCHANT_transfers_post ( struct GNUNET_CURL_Context *ctx, const char *backend_url, - const char *order_id, - TALER_MERCHANT_TrackTransactionCallback track_transaction_cb, - void *track_transaction_cb_cls); + const char *payto_uri, + const struct GNUNET_TIME_Absolute before, + const struct GNUNET_TIME_Absolute after, + int64_t limit, + uint64_t offset, + enum TALER_MERCHANT_YesNoAll verified, + TALER_MERCHANT_GetTransfersCallback cb, + void *cls); /** - * Cancel a /track/transaction request. This function cannot be used + * Cancel a POST /transfers request. This function cannot be used * on a request handle if a response is already served for it. * - * @param tdo the tracking request to cancel + * @param pth the operation to cancel */ void -TALER_MERCHANT_track_transaction_cancel ( - struct TALER_MERCHANT_TrackTransactionHandle *tdo); +TALER_MERCHANT_transfers_get_cancel ( + struct TALER_MERCHANT_GetTransfersHandle *gth); + + +/* ********************* OLD ************************** */ /* ********************** /tip-authorize ********************** */ @@ -2519,9 +2573,6 @@ TALER_MERCHANT_tip_pickup2_cancel ( struct TALER_MERCHANT_TipPickup2Operation *tp); -/* ********************** /check-payment ************************* */ - - /* ********************** /tip-query ************************* */ /** @@ -2585,4 +2636,83 @@ void TALER_MERCHANT_tip_query_cancel (struct TALER_MERCHANT_TipQueryOperation *tqh); +/* ********************* /track/transaction (UNSPEC!) *********************** */ + +/** + * @brief Handle to a /track/transaction operation at a merchant's backend. + */ +struct TALER_MERCHANT_TrackTransactionHandle; + +/** + * Information about a coin aggregated in a wire transfer for a + * /track/transaction response. + */ +struct TALER_MERCHANT_CoinWireTransfer +{ + + /** + * Public key of the coin. + */ + struct TALER_CoinSpendPublicKeyP coin_pub; + + /** + * Value of the coin including deposit fee. + */ + struct TALER_Amount amount_with_fee; + + /** + * Deposit fee for the coin. + */ + struct TALER_Amount deposit_fee; + +}; + + +/** + * Callbacks of this type are used to work the result of submitting a + * /track/transaction request to a merchant + * + * @param cls closure + * @param http_status HTTP status code we got, 0 on exchange protocol violation + * @param ec taler-specific error code + * @param json original json reply from the backend + * @param num_transfers number of wire transfers the exchange used for the transaction + * @param transfers details about each transfer and which coins are aggregated in it +*/ +typedef void +(*TALER_MERCHANT_TrackTransactionCallback) ( + void *cls, + const struct TALER_MERCHANT_HttpResponse *hr); + + +/** + * Request backend to return deposits associated with a given wtid. + * + * @param ctx execution context + * @param backend_url base URL of the backend + * @param order_id which order should we trace + * @param track_transaction_cb the callback to call when a reply for this request is available + * @param track_transaction_cb_cls closure for @a track_transaction_cb + * @return a handle for this request + */ +struct TALER_MERCHANT_TrackTransactionHandle * +TALER_MERCHANT_track_transaction ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + const char *order_id, + TALER_MERCHANT_TrackTransactionCallback track_transaction_cb, + void *track_transaction_cb_cls); + + +/** + * Cancel a /track/transaction request. This function cannot be used + * on a request handle if a response is already served for it. + * + * @param tdo the tracking request to cancel + */ +void +TALER_MERCHANT_track_transaction_cancel ( + struct TALER_MERCHANT_TrackTransactionHandle *tdo); + + #endif /* _TALER_MERCHANT_SERVICE_H */ |