From 607c8d8a015c677f9a4f2aa5cc46285c57ebb714 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 3 May 2020 17:06:00 +0200 Subject: GET /orders/ID API design --- src/include/taler_merchant_service.h | 662 ++++++++++++++++++----------------- 1 file changed, 340 insertions(+), 322 deletions(-) diff --git a/src/include/taler_merchant_service.h b/src/include/taler_merchant_service.h index c8b22ebe..cfed7436 100644 --- a/src/include/taler_merchant_service.h +++ b/src/include/taler_merchant_service.h @@ -1315,6 +1315,346 @@ TALER_MERCHANT_orders_get_cancel ( struct TALER_MERCHANT_OrdersGetHandle *pgh); +/** + * Handle for a GET /orders/$ID operation. (Wallet's public endpoint, + * not to be confused with the private endpoint for the merchant.) + */ +struct TALER_MERCHANT_OrderWalletGetHandle; + + +/** + * Detail about a refund lookup result. + */ +struct TALER_MERCHANT_RefundDetail +{ + + /** + * Exchange response details. Full details are only included + * upon failure (HTTP status is not #MHD_HTTP_OK). + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Coin this detail is about. + */ + struct TALER_CoinSpendPublicKeyP coin_pub; + + /** + * Refund transaction ID used. + */ + uint64_t rtransaction_id; + + /** + * Amount to be refunded for this coin. + */ + struct TALER_Amount refund_amount; + + /** + * Applicable refund transaction fee. + */ + struct TALER_Amount refund_fee; + + /** + * 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; + +}; + + +/** + * Callback to process a GET /orders/$ID request + * + * @param cls closure + * @param hr HTTP response details + * @param paid #GNUNET_YES if the payment is settled, #GNUNET_NO if not + * settled, #GNUNET_SYSERR on error + * (note that refunded payments are returned as paid!) + * @param refunded #GNUNET_YES if there is at least on refund on this payment, + * #GNUNET_NO if refunded, #GNUNET_SYSERR or error + * @param refunded_amount amount that was refunded, NULL if there + * was no refund + * @param taler_pay_uri the URI that instructs the wallets to process + * the payment + * @param merchant_pub public key of the merchant + * @param num_refunds length of the @a refunds array + * @param refunds details about the refund processing + */ +typedef void +(*TALER_MERCHANT_OrderWalletGetCallback) ( + void *cls, + const struct TALER_MERCHANT_HttpResponse *hr, + enum GNUNET_GenericReturnValue paid, + enum GNUNET_GenericReturnValue refunded, + struct TALER_Amount *refund_amount, + const char *taler_pay_uri, + const struct TALER_MerchantPublicKeyP *merchant_pub, + unsigned int num_refunds, + const struct TALER_MERCHANT_RefundDetail *refunds); + + +/** + * Checks the status of a payment. Issue a GET /orders/$ID request to the + * backend. The @a h_contract serves as identification of the wallet and is + * used to authorize the request. + * + * @param ctx execution context + * @param backend_url base URL of the merchant backend + * @param order_id order id to identify the payment + * @param h_contract hash of the contract to authenticate the wallet + * @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 + * #TALER_MERCHANT_order_get_cancel() is called. + * @param min_refund long poll for the service to approve a refund exceeding this value; + * use NULL to not wait for any refund (only for payment). Only makes sense + * with a non-zero @a timeout. Can be NULL. + * @param cb callback which will work the response gotten from the backend + * @param cb_cls closure to pass to @a cb + * @return handle for this operation, NULL upon errors + */ +struct TALER_MERCHANT_OrderWalletGetHandle * +TALER_MERCHANT_order_wallet_get (struct GNUNET_CURL_Context *ctx, + const char *backend_url, + const char *order_id, + const struct GNUNET_HashCode *h_contract, + struct GNUNET_TIME_Relative timeout, + const struct TALER_Amount *min_refund, + TALER_MERCHANT_OrderWalletGetCallback cb, + void *cb_cls); + +/** + * Cancel a GET /orders/$ID request. + * + * @param owgh handle to the request to be canceled + */ +void +TALER_MERCHANT_order_wallet_get_cancel ( + struct TALER_MERCHANT_OrderWalletGetHandle *owgh); + + +/** + * Handle for a GET /private/orders/$ID operation (merchant's internal + * API, not to be confused with the endpoint for wallets). + */ +struct TALER_MERCHANT_OrderMerchantGetHandle; + + +/** + * Details about a wire transfer to the merchant related to the order. + */ +struct TALER_MERCHANT_WireTransfer +{ + /** + * Base URL of the exchange that made the transfer. + */ + const char *exchange_uri; + + /** + * When the transfer took place (note: may not be exact, + * as the time at which the exchange initiated the transfer + * may differ from the time the bank or the merchant observed). + */ + struct GNUNET_TIME_Absolute execution_time; + + /** + * Wire transfer subject. + */ + struct TALER_WireTransferIdentifierRawP wtid; + + /** + * Total amount that was transferred. + */ + struct TALER_Amount total_amount; + + /** + * Whether this transfer was confirmed by the merchant using + * the POST /transfers API, or whether it was merely claimed + * by the exchange. + */ + bool confirmed; +}; + + +/** + * Details about the status of an order. + */ +struct TALER_MERCHANT_OrderStatusResponse +{ + + /** + * #GNUNET_YES if the payment is settled, #GNUNET_NO if not + * settled, #GNUNET_SYSERR if we got conflicting transaction proofs. + */ + enum GNUNET_GenericReturnValue paid; + + union + { + + /** + * Details provided if @e paid is #GNUNET_YES. + */ + struct + { + /** + * Refunded #GNUNET_YES if there is at least on refund on this payment, + * #GNUNET_NO if there are no refunds. + */ + enum GNUNET_GenericReturnValue refunded; + + /** + * Amount that was refunded. + */ + struct TALER_Amount refund_amount; + + /** + * Hash of the contract terms. + */ + struct GNUNET_HashCode h_contract_terms; + + /** + * Array of wire transfers made for this payment to the + * merchant by the exchange. Of length @e wt_len. + */ + struct TALER_MERCHANT_WireTransfer *wt; + + /** + * Length of the @e wt array. + */ + unsigned int wt_len; + + } paid; + + /** + * Details provided if @e paid is #GNUNET_NO. + */ + struct + { + + /** + * URI that should be shown to the wallet to trigger a payment. + */ + const char *taler_pay_uri; + + /** + * Alternative order ID which was paid for already in the same session. + * Only given if the same product was purchased before in the same session. + * Otherwise NULL. + */ + const char *already_paid_order_id; + + } unpaid; + + /** + * Details provided if @e paid is #GNUNET_SYSERR. + */ + struct + { + + // FIXME: we probably should return an ARRAY of these, + // as there could be multiple errors involving multiple + // coins. Also, we should compute the losses and + // return those! => need specification update first! + + /** + * Error code explaining the nature of the conflict. Can either be that + * @e coin_pub is not (or with a different amount) included in @e + * wtid_claim despite @e deposit_claim saying it should be, or that the + * amounts in @e wtid_claim do not add up. + */ + enum TALER_ErrorCode code; + + /** + * Human-readable error description. + */ + const char *hint; + + /** + * Public key of the coin involved. + */ + struct TALER_CoinSpendPublicKeyP coin_pub; + + /** + * A claim by the exchange about the transactions associated + * with a given wire transfer. + */ + // FIXME: should update exchange API first to define the struct! + /* struct TALER_EXCHANGE_TransferData * */ void *wtid_claim; + + /** + * A claim by the exchange that the given transaction is included + * in the above WTID. + */ + // FIXME: should update exchange API first to define the struct! + /* struct TALER_EXCHANGE_DepositData * */ void *deposit_claim; + + } conflict; + + } details; +}; + + +/** + * Callback to process a GET /orders/$ID request + * + * @param cls closure + * @param hr HTTP response details + * @param osr order status response details (on success) + */ +typedef void +(*TALER_MERCHANT_OrderMerchantGetCallback) ( + void *cls, + const struct TALER_MERCHANT_HttpResponse *hr, + const struct TALER_MERCHANT_OrderStatusResponse *osr); + + +/** + * Checks the status of a payment. Issue a GET /private/orders/$ID request to + * the backend. + * + * @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 + * bound to a session) + * @param transfer if true, obtain the wire transfer status from the exhcange. + * 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 + * #TALER_MERCHANT_order_get_cancel() is called. + * @param cb callback which will work the response gotten from the backend + * @param cb_cls closure to pass to @a cb + * @return handle for this operation, NULL upon errors + */ +struct TALER_MERCHANT_OrderMerchantGetHandle * +TALER_MERCHANT_order_merchant_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); + + +/** + * Cancel a GET /private/orders/$ID request. + * + * @param omgh handle to the request to be canceled + */ +void +TALER_MERCHANT_order_merchant_get_cancel ( + struct TALER_MERCHANT_OrderMerchantGetHandle *omgh); + + /** * Handle for a DELETE /orders/$ID operation. */ @@ -1790,114 +2130,6 @@ TALER_MERCHANT_post_order_refund_cancel ( /* ********************* OLD ************************** */ -/* ********************* /refund ************************** */ - -/** - * Handle for a GET /refund operation. - */ -struct TALER_MERCHANT_RefundLookupOperation; - - -/** - * Detail about a refund lookup result. - */ -struct TALER_MERCHANT_RefundDetail -{ - - /** - * Exchange response details. Full details are only included - * upon failure (HTTP status is not #MHD_HTTP_OK). - */ - struct TALER_EXCHANGE_HttpResponse hr; - - /** - * Coin this detail is about. - */ - struct TALER_CoinSpendPublicKeyP coin_pub; - - /** - * Refund transaction ID used. - */ - uint64_t rtransaction_id; - - /** - * Amount to be refunded for this coin. - */ - struct TALER_Amount refund_amount; - - /** - * Applicable refund transaction fee. - */ - struct TALER_Amount refund_fee; - - /** - * 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; - -}; - - -/** - * Callback to process a GET /refund request - * - * @param cls closure - * @param hr HTTP response details - * @param h_contract_terms hash of the contract terms to which the refund is applied - * @param merchant_pub public key of the merchant - * @param num_details length of the @a details array - * @param details details about the refund processing - */ -typedef void -(*TALER_MERCHANT_RefundLookupCallback) ( - void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - const struct GNUNET_HashCode *h_contract_terms, - const struct TALER_MerchantPublicKeyP *merchant_pub, - unsigned int num_details, - const struct TALER_MERCHANT_RefundDetail *details); - - -/** - * Does a GET /refund. - * - * @param ctx execution context - * @param backend_url base URL of the merchant backend - * @param order_id order id used to perform the lookup - * @param cb callback which will work the response gotten from the backend - * @param cb_cls closure to pass to the callback - * @return handle for this operation, NULL upon errors - */ -struct TALER_MERCHANT_RefundLookupOperation * -TALER_MERCHANT_refund_lookup (struct GNUNET_CURL_Context *ctx, - const char *backend_url, - const char *order_id, - TALER_MERCHANT_RefundLookupCallback cb, - void *cb_cls); - -/** - * Cancel a GET /refund request. - * - * @param rlo the refund increasing operation to cancel - */ -void -TALER_MERCHANT_refund_lookup_cancel ( - struct TALER_MERCHANT_RefundLookupOperation *rlo); - - -/* ********************* /proposal *********************** */ - - -/* ********************* /pay *********************** */ - - /* ********************* /track/transfer *********************** */ /** @@ -2066,76 +2298,6 @@ void TALER_MERCHANT_track_transaction_cancel ( struct TALER_MERCHANT_TrackTransactionHandle *tdo); -/* ********************* /history *********************** */ - -struct TALER_MERCHANT_HistoryOperation; - -/** - * Callback for a /history request. It's up to this function how - * to render the array containing transactions details (FIXME link to - * documentation) - * - * @param cls closure - * @param hr HTTP response details - */ -typedef void -(*TALER_MERCHANT_HistoryOperationCallback) ( - void *cls, - const struct TALER_MERCHANT_HttpResponse *hr); - - -/** - * Issue a /history request to the backend. - * - * @param ctx execution context - * @param backend_url base URL of the merchant backend - * @param start return @a delta records starting from position @a start - * @param delta return @a delta records starting from position @a start - * @param date only transactions younger than/equals to date will be returned - * @param history_cb callback which will work the response gotten from the backend - * @param history_cb_cls closure to pass to @a history_cb - * @return handle for this operation, NULL upon errors - */ -struct TALER_MERCHANT_HistoryOperation * -TALER_MERCHANT_history (struct GNUNET_CURL_Context *ctx, - const char *backend_url, - unsigned long long start, - long long delta, - struct GNUNET_TIME_Absolute date, - TALER_MERCHANT_HistoryOperationCallback history_cb, - void *history_cb_cls); - -/** - * Issue a /history request to the backend. - * - * @param ctx execution context - * @param backend_url base URL of the merchant backend - * @param start return `delta` records starting from position `start`. - * If given as zero, then no initial skip of `start` records is done. - * @param delta return `delta` records starting from position `start` - * @param date only transactions younger than/equals to date will be returned - * @param history_cb callback which will work the response gotten from the backend - * @param history_cb_cls closure to pass to @a history_cb - * @return handle for this operation, NULL upon errors - */ -struct TALER_MERCHANT_HistoryOperation * -TALER_MERCHANT_history_default_start ( - struct GNUNET_CURL_Context *ctx, - const char *backend_url, - long long delta, - struct GNUNET_TIME_Absolute date, - TALER_MERCHANT_HistoryOperationCallback history_cb, - void *history_cb_cls); - - -/** - * Cancel a pending /history request - * - * @param ho handle from the operation to cancel - */ -void -TALER_MERCHANT_history_cancel (struct TALER_MERCHANT_HistoryOperation *ho); - /* ********************** /tip-authorize ********************** */ @@ -2341,73 +2503,6 @@ TALER_MERCHANT_tip_pickup2_cancel ( /* ********************** /check-payment ************************* */ -/** - * Handle for a /check-payment operation. - */ -struct TALER_MERCHANT_CheckPaymentOperation; - - -/** - * Callback to process a GET /check-payment request - * - * @param cls closure - * @param hr HTTP response details - * @param paid #GNUNET_YES if the payment is settled, #GNUNET_NO if not - * settled, $GNUNET_SYSERR on error - * (note that refunded payments are returned as paid!) - * @param refunded #GNUNET_YES if there is at least on refund on this payment, - * #GNUNET_NO if refunded, #GNUNET_SYSERR or error - * @param refunded_amount amount that was refunded, NULL if there - * was no refund - * @param taler_pay_uri the URI that instructs the wallets to process - * the payment - */ -typedef void -(*TALER_MERCHANT_CheckPaymentCallback) ( - void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - int paid, - int refunded, - struct TALER_Amount *refund_amount, - const char *taler_pay_uri); - - -/** - * Issue a /check-payment request to the backend. Checks the status - * of a payment. - * - * @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 payment is not bound to a session) - * @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 - * #TALER_MERCHANT_check_payment_cancel() is called. - * @param check_payment_cb callback which will work the response gotten from the backend - * @param check_payment_cb_cls closure to pass to @a check_payment_cb - * @return handle for this operation, NULL upon errors - */ -struct TALER_MERCHANT_CheckPaymentOperation * -TALER_MERCHANT_check_payment (struct GNUNET_CURL_Context *ctx, - const char *backend_url, - const char *order_id, - const char *session_id, - struct GNUNET_TIME_Relative timeout, - TALER_MERCHANT_CheckPaymentCallback - check_payment_cb, - void *check_payment_cls); - -/** - * Cancel a GET /check-payment request. - * - * @param cpo handle to the request to be canceled - */ -void -TALER_MERCHANT_check_payment_cancel ( - struct TALER_MERCHANT_CheckPaymentOperation *cpo); - - /* ********************** /tip-query ************************* */ /** @@ -2471,81 +2566,4 @@ void TALER_MERCHANT_tip_query_cancel (struct TALER_MERCHANT_TipQueryOperation *tqh); -/* ********************** /public/poll-payment ************************* */ - - -/** - * Handle for a /public/poll-payment operation. - */ -struct TALER_MERCHANT_PollPaymentOperation; - - -/** - * Callback to process a GET /poll-payment request - * - * @param cls closure - * @param hr HTTP response details - * @param paid #GNUNET_YES if the payment is settled, #GNUNET_NO if not - * settled, $GNUNET_SYSERR on error - * (note that refunded payments are returned as paid!) - * @param refunded #GNUNET_YES if there is at least on refund on this payment, - * #GNUNET_NO if refunded, #GNUNET_SYSERR or error - * @param refunded_amount amount that was refunded, NULL if there - * was no refund - * @param taler_pay_uri the URI that instructs the wallets to process - * the payment - */ -typedef void -(*TALER_MERCHANT_PollPaymentCallback) ( - void *cls, - const struct TALER_MERCHANT_HttpResponse *hr, - int paid, - int refunded, - struct TALER_Amount *refund_amount, - const char *taler_pay_uri); - - -/** - * Issue a /poll-payment request to the backend. Polls the status - * of a payment. - * - * @param ctx execution context - * @param backend_url base URL of the merchant backend - * @param order_id order id to identify the payment - * @param h_contract hash of the contract for @a order_id - * @param session_id sesion id for the payment (or NULL if the payment is not bound to a session) - * @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 - * #TALER_MERCHANT_poll_payment_cancel() is called. - * @param min_refund long poll for the service to approve a refund exceeding this value; - * use NULL to not wait for any refund (only for payment). Only makes sense - * with a non-zero @a timeout. - * @param poll_payment_cb callback which will work the response gotten from the backend - * @param poll_payment_cb_cls closure to pass to @a poll_payment_cb - * @return handle for this operation, NULL upon errors - */ -struct TALER_MERCHANT_PollPaymentOperation * -TALER_MERCHANT_poll_payment ( - struct GNUNET_CURL_Context *ctx, - const char *backend_url, - const char *order_id, - const struct GNUNET_HashCode *h_contract, - const char *session_id, - struct GNUNET_TIME_Relative timeout, - const struct TALER_Amount *min_refund, - TALER_MERCHANT_PollPaymentCallback poll_payment_cb, - void *poll_payment_cls); - - -/** - * Cancel a GET /public/poll-payment request. - * - * @param cpo handle to the request to be canceled - */ -void -TALER_MERCHANT_poll_payment_cancel ( - struct TALER_MERCHANT_PollPaymentOperation *cpo); - - #endif /* _TALER_MERCHANT_SERVICE_H */ -- cgit v1.2.3