implementing parsing of /refund requests

3 files changed, 196 insertions, 0 deletions

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 *********************** */
 
 
diff --git a/src/include/taler_exchangedb_plugin.h b/src/include/taler_exchangedb_plugin.h
index 3646981cd..e364d6b95 100644
--- a/src/include/taler_exchangedb_plugin.h
+++ b/src/include/taler_exchangedb_plugin.h
@@ -299,6 +299,67 @@ struct TALER_EXCHANGEDB_Deposit
 
 
 /**
+ * @brief Specification for a /refund operation.  The combination of
+ * the coin's public key, the merchant's public key and the
+ * transaction ID must be unique.  While a coin can (theoretically) be
+ * deposited at the same merchant twice (with partial spending), the
+ * merchant must either use a different public key or a different
+ * transaction ID for the two transactions.  The same goes for
+ * refunds, hence we also have a "rtransaction" ID which is disjoint
+ * from the transaction ID.  The same coin must not be used twice at
+ * the same merchant for the same transaction or rtransaction ID.
+ */
+struct TALER_EXCHANGEDB_Refund
+{
+  /**
+   * Information about the coin that is being refunded.
+   */
+  struct TALER_CoinPublicInfo coin;
+
+  /**
+   * Public key of the merchant. 
+   */
+  struct TALER_MerchantPublicKeyP merchant_pub;
+  
+  /**
+   * Signature from the merchant affirming the refund. 
+   */
+  struct TALER_MerchantSignatureP merchant_sig;
+
+  /**
+   * Hash over the contract between merchant and customer
+   * (remains unknown to the Exchange).
+   */
+  struct GNUNET_HashCode h_contract;
+
+  /**
+   * Merchant-generated transaction ID to detect duplicate
+   * transactions, of the original transaction that is being
+   * refunded.
+   */
+  uint64_t transaction_id;
+  
+  /**
+   * Merchant-generated REFUND transaction ID to detect duplicate
+   * refunds.
+   */
+  uint64_t rtransaction_id;
+
+  /**
+   * Fraction of the original deposit's value to be refunded, including
+   * refund fee (if any).  The coin is identified by @e coin_pub.
+   */
+  struct TALER_Amount refund_amount;
+
+  /**
+   * Refund fee to be covered by the customer.
+   */
+  struct TALER_Amount refund_fee;
+
+};
+
+
+/**
  * @brief Global information for a refreshing session.  Includes
  * dimensions of the operation, security parameters and
  * client signatures from "/refresh/melt" and "/refresh/commit".
diff --git a/src/include/taler_signatures.h b/src/include/taler_signatures.h
index 154e11610..f1586aa8c 100644
--- a/src/include/taler_signatures.h
+++ b/src/include/taler_signatures.h
@@ -396,6 +396,64 @@ struct TALER_DepositConfirmationPS
 
 
 /**
+ * @brief Format used to generate the signature on a request to refund
+ * a coin into the account of the customer.
+ */
+struct TALER_RefundRequestPS
+{
+  /**
+   * Purpose must be #TALER_SIGNATURE_MERCHANT_REFUND.
+   */
+  struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+
+  /**
+   * Hash over the contract which is being refunded.
+   */
+  struct GNUNET_HashCode h_contract GNUNET_PACKED;
+
+  /**
+   * Merchant-generated transaction ID of the orginal transaction.
+   */
+  uint64_t transaction_id GNUNET_PACKED;
+
+  /**
+   * The coin's public key.  This is the value that must have been
+   * signed (blindly) by the Exchange.  
+   */
+  struct TALER_CoinSpendPublicKeyP coin_pub;
+
+  /**
+   * The Merchant's public key.  Allows the merchant to later refund
+   * the transaction or to inquire about the wire transfer identifier.
+   */
+  struct TALER_MerchantPublicKeyP merchant;
+
+  /**
+   * Merchant-generated transaction ID for the refund.
+   */
+  uint64_t rtransaction_id GNUNET_PACKED;
+
+  /**
+   * Amount to be refunded, including refund fee charged by the
+   * exchange to the customer.
+   */
+  struct TALER_AmountNBO refund_amount;
+
+  /**
+   * Refund fee charged by the exchange.  This must match the
+   * Exchange's denomination key's refund fee.  If the client puts in
+   * an invalid refund fee (too high or too low) that does not match
+   * the Exchange's denomination key, the refund operation is invalid
+   * and will be rejected by the exchange.  The @e amount_with_fee
+   * minus the @e refund_fee is the amount that will be credited to
+   * the original coin.
+   */
+  struct TALER_AmountNBO refund_fee;
+
+};
+
+
+/**
  * @brief Message signed by a coin to indicate that the coin should be
  * melted.
  */