From edd31c74151d6bfe3d840bcc62b619aacf7542eb Mon Sep 17 00:00:00 2001
From: Christian Grothoff <christian@grothoff.org>
Date: Wed, 20 Apr 2016 02:50:52 +0200
Subject: implementing parsing of /refund requests

---
 src/include/taler_exchange_service.h | 77 ++++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)

(limited to 'src/include/taler_exchange_service.h')

diff --git a/src/include/taler_exchange_service.h b/src/include/taler_exchange_service.h
index ffd420586..2f9a1932c 100644
--- a/src/include/taler_exchange_service.h
+++ b/src/include/taler_exchange_service.h
@@ -465,6 +465,83 @@ void
 TALER_EXCHANGE_deposit_cancel (struct TALER_EXCHANGE_DepositHandle *deposit);
 
 
+/* *********************  /refund *********************** */
+
+/**
+ * @brief A Refund Handle
+ */
+struct TALER_EXCHANGE_RefundHandle;
+
+
+/**
+ * Callbacks of this type are used to serve the result of submitting a
+ * deposit permission request to a exchange.
+ *
+ * @param cls closure
+ * @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful deposit;
+ *                    0 if the exchange's reply is bogus (fails to follow the protocol)
+ * @param obj the received JSON reply, should be kept as proof (and, in particular,
+ *            be forwarded to the customer)
+ */
+typedef void
+(*TALER_EXCHANGE_RefundResultCallback) (void *cls,
+					unsigned int http_status,
+					const json_t *obj);
+
+
+/**
+ * Submit a refund request to the exchange and get the exchange's
+ * response.  This API is used by a merchant.  Note that
+ * while we return the response verbatim to the caller for further
+ * processing, we do already verify that the response is well-formed
+ * (i.e. that signatures included in the response are all valid).  If
+ * the exchange's reply is not well-formed, we return an HTTP status code
+ * of zero to @a cb.
+ *
+ * The @a exchange must be ready to operate (i.e.  have
+ * finished processing the /keys reply).  If this check fails, we do
+ * NOT initiate the transaction with the exchange and instead return NULL.
+ *
+ * @param exchange the exchange handle; the exchange must be ready to operate
+ * @param amount the amount to be refunded; must be larger than the refund fee
+ *        (as that fee is still being subtracted), and smaller than the amount 
+ *        (with deposit fee) of the original deposit contribution of this coin
+ * @param h_contract hash of the contact of the merchant with the customer that is being refunded
+ * @param transaction_id transaction id for the transaction being refunded, must match @a h_contract
+ * @param coin_pub coin’s public key of the coin from the original deposit operation
+ * @param rtransaction_id transaction id for the transaction between merchant and customer (of refunding operation);
+ *                        this is needed as we may first do a partial refund and later a full refund.  If both
+ *                        refunds are also over the same amount, we need the @a rtransaction_id to make the disjoint
+ *                        refund requests different (as requests are idempotent and otherwise the 2nd refund might not work).
+ * @param merchant_priv the private key of the merchant, used to generate signature for refund request
+ * @param cb the callback to call when a reply for this request is available
+ * @param cb_cls closure for the above callback
+ * @return a handle for this request; NULL if the inputs are invalid (i.e.
+ *         signatures fail to verify).  In this case, the callback is not called.
+ */
+struct TALER_EXCHANGE_RefundHandle *
+TALER_EXCHANGE_refund (struct TALER_EXCHANGE_Handle *exchange,
+		       const struct TALER_Amount *amount,
+		       const struct GNUNET_HashCode *h_contract,
+		       const struct TALER_CoinSpendPublicKeyP *coin_pub,
+		       uint64_t rtransaction_id,
+		       const struct TALER_MerchantPrivateKeyP *merchant_priv,
+		       TALER_EXCHANGE_RefundResultCallback cb,
+		       void *cb_cls);
+
+
+/**
+ * Cancel a refund permission request.  This function cannot be used
+ * on a request handle if a response is already served for it.  If 
+ * this function is called, the refund may or may not have happened.
+ * However, it is fine to try to refund the coin a second time.
+ *
+ * @param refund the refund request handle
+ */
+void
+TALER_EXCHANGE_refund_cancel (struct TALER_EXCHANGE_RefundHandle *refund);
+
+
 /* ********************* /reserve/status *********************** */
 
 
-- 
cgit v1.2.3