work on /pay API revision

1 files changed, 265 insertions, 239 deletions

diff --git a/src/include/taler_merchant_service.h b/src/include/taler_merchant_service.h
index a4312c09..3335aeab 100644
--- a/src/include/taler_merchant_service.h
+++ b/src/include/taler_merchant_service.h
@@ -1391,6 +1391,7 @@ typedef void
 /**
  * Calls the POST /orders/$ID/claim API at the backend.  That is,
  * retrieve the final contract terms including the client nonce.
+ *
  * This is a PUBLIC API for wallets.
  *
  * @param ctx execution context
@@ -1419,188 +1420,112 @@ void
 TALER_MERCHANT_order_claim_cancel (struct TALER_MERCHANT_OrderClaimHandle *och);
 
 
-/* *********************   OLD ************************** */
-
+/**
+ * @brief Handle to a POST /orders/$ID/pay operation at a merchant.  Note that
+ * we use the same handle for interactions with frontends (API for wallets) or
+ * backends (API for frontends).  The difference is that for the frontend API,
+ * we need the private keys of the coins, while for the backend API we need
+ * the public keys and signatures received from the wallet.
+ */
+struct TALER_MERCHANT_OrderPayHandle;
 
-/* ********************* /refund ************************** */
 
 /**
- * Handle for a GET /refund operation.
+ * Callbacks of this type are used to serve the result of submitting a
+ * POST /orders/$ID/pay request to a merchant.
+ *
+ * @param cls closure
+ * @param hr HTTP response details
  */
-struct TALER_MERCHANT_RefundLookupOperation;
+typedef void
+(*TALER_MERCHANT_OrderPayCallback) (
+  void *cls,
+  const struct TALER_MERCHANT_HttpResponse *hr);
 
 
 /**
- * Detail about a refund lookup result.
+ * Information we need from the frontend (ok, the frontend sends just JSON)
+ * when forwarding a payment to the backend.
  */
-struct TALER_MERCHANT_RefundDetail
+struct TALER_MERCHANT_PaidCoin
 {
+  /**
+   * Denomination key with which the coin is signed
+   */
+  struct TALER_DenominationPublicKey denom_pub;
 
   /**
-   * Exchange response details.  Full details are only included
-   * upon failure (HTTP status is not #MHD_HTTP_OK).
+   * Exchange’s unblinded signature of the coin
    */
-  struct TALER_EXCHANGE_HttpResponse hr;
+  struct TALER_DenominationSignature denom_sig;
 
   /**
-   * Coin this detail is about.
+   * Overall value that coins of this @e denom_pub have.
+   */
+  struct TALER_Amount denom_value;
+
+  /**
+   * Coin's public key.
    */
   struct TALER_CoinSpendPublicKeyP coin_pub;
 
   /**
-   * Refund transaction ID used.
+   * Coin's signature key.
    */
-  uint64_t rtransaction_id;
+  struct TALER_CoinSpendSignatureP coin_sig;
 
   /**
-   * Amount to be refunded for this coin.
+   * Amount this coin contributes to (including fee).
    */
-  struct TALER_Amount refund_amount;
+  struct TALER_Amount amount_with_fee;
 
   /**
-   * Applicable refund transaction fee.
+   * Amount this coin contributes to (without fee).
    */
-  struct TALER_Amount refund_fee;
+  struct TALER_Amount amount_without_fee;
 
   /**
-   * Public key of the exchange affirming the refund,
-   * only valid if the @e hr http_status is #MHD_HTTP_OK.
+   * Fee the exchange charges for refunds of this coin.
    */
-  struct TALER_ExchangePublicKeyP exchange_pub;
+  struct TALER_Amount refund_fee;
 
   /**
-   * Signature of the exchange affirming the refund,
-   * only valid if the @e hr http_status is #MHD_HTTP_OK.
+   * What is the URL of the exchange that issued @a coin_pub?
    */
-  struct TALER_ExchangeSignatureP exchange_sig;
+  const char *exchange_url;
 
 };
 
 
 /**
- * Callback to process a GET /refund request
+ * Pay a merchant.  API for frontends talking to backends. Here,
+ * the frontend does not have the coin's private keys, but just
+ * the public keys and signatures.  Note the sublte difference
+ * in the type of @a coins compared to #TALER_MERCHANT_pay().
  *
- * @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.
+ * This is a PUBLIC API, albeit in this form useful for the frontend,
+ * in case the frontend is proxying the request.
  *
  * @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);
-
-
-/**
- * Handle for a POST /refund operation.
- */
-struct TALER_MERCHANT_RefundIncreaseOperation;
-
-
-/**
- * Callback to process a POST /refund request
- *
- * @param cls closure
- * @param http_status HTTP status code for this request
- * @param ec taler-specific error code
- */
-typedef void
-(*TALER_MERCHANT_RefundIncreaseCallback) (
-  void *cls,
-  const struct TALER_MERCHANT_HttpResponse *hr);
-
-
-/**
- * Increase the refund associated to a order
- *
- * @param ctx the CURL context used to connect to the backend
- * @param backend_url backend's base URL, including final "/"
- * @param order_id id of the order whose refund is to be increased
- * @param refund amount to which increase the refund
- * @param reason human-readable reason justifying the refund
- * @param cb callback processing the response from /refund
- * @param cb_cls closure for cb
- */
-struct TALER_MERCHANT_RefundIncreaseOperation *
-TALER_MERCHANT_refund_increase (struct GNUNET_CURL_Context *ctx,
-                                const char *backend_url,
-                                const char *order_id,
-                                const struct TALER_Amount *refund,
-                                const char *reason,
-                                TALER_MERCHANT_RefundIncreaseCallback cb,
-                                void *cb_cls);
-
-/**
- * Cancel a POST /refund request.
- *
- * @param rio the refund increasing operation to cancel
- */
-void
-TALER_MERCHANT_refund_increase_cancel (
-  struct TALER_MERCHANT_RefundIncreaseOperation *rio);
-
-
-/* *********************  /proposal *********************** */
-
-
-/* *********************  /pay *********************** */
-
-
-/**
- * @brief Handle to a /pay operation at a merchant.  Note that we use
- * the same handle for interactions with frontends (API for wallets)
- * or backends (API for frontends).  The difference is that for the
- * frontend API, we need the private keys of the coins, while for
- * the backend API we need the public keys and signatures received
- * from the wallet.  Also, the frontend returns a redirect URL on
- * success, while the backend just returns a success status code.
- */
-struct TALER_MERCHANT_Pay;
-
-
-/**
- * Callbacks of this type are used to serve the result of submitting a
- * /pay request to a merchant.
- *
- * @param cls closure
- * @param hr HTTP response details
+ * @param merchant_url base URL of the merchant
+ * @param merchant_pub public key of the merchant
+ * @param order_id which order should be paid
+ * @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
+ * @param pay_cb_cls closure for @a pay_cb
+ * @return a handle for this request
  */
-typedef void
-(*TALER_MERCHANT_PayCallback) (void *cls,
-                               const struct TALER_MERCHANT_HttpResponse *hr);
+struct TALER_MERCHANT_OrderPayHandle *
+TALER_MERCHANT_order_pay_frontend (
+  struct GNUNET_CURL_Context *ctx,
+  const char *merchant_url,
+  const struct TALER_MerchantPublicKeyP *merchant_pub,
+  const char *order_id,
+  unsigned int num_coins,
+  const struct TALER_MERCHANT_PaidCoin coins[],
+  TALER_MERCHANT_PayCallback pay_cb,
+  void *pay_cb_cls);
 
 
 /**
@@ -1655,6 +1580,8 @@ struct TALER_MERCHANT_PayCoin
 /**
  * Pay a merchant.  API for wallets that have the coin's private keys.
  *
+ * This is a PUBLIC API for wallets.
+ *
  * @param ctx execution context
  * @param merchant_url base URL of the merchant
  * @param h_wire hash of the merchant’s account details
@@ -1674,29 +1601,50 @@ struct TALER_MERCHANT_PayCoin
  * @param pay_cb_cls closure for @a pay_cb
  * @return a handle for this request
  */
-struct TALER_MERCHANT_Pay *
-TALER_MERCHANT_pay_wallet (struct GNUNET_CURL_Context *ctx,
-                           const char *merchant_url,
-                           const struct GNUNET_HashCode *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_Absolute timestamp,
-                           struct GNUNET_TIME_Absolute refund_deadline,
-                           struct GNUNET_TIME_Absolute pay_deadline,
-                           const struct GNUNET_HashCode *h_wire,
-                           const char *order_id,
-                           unsigned int num_coins,
-                           const struct TALER_MERCHANT_PayCoin *coins,
-                           TALER_MERCHANT_PayCallback pay_cb,
-                           void *pay_cb_cls);
+struct TALER_MERCHANT_OrderPayHandle *
+TALER_MERCHANT_order_pay (
+  struct GNUNET_CURL_Context *ctx,
+  const char *merchant_url,
+  const struct GNUNET_HashCode *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_Absolute timestamp,
+  struct GNUNET_TIME_Absolute refund_deadline,
+  struct GNUNET_TIME_Absolute pay_deadline,
+  const struct GNUNET_HashCode *h_wire,
+  const char *order_id,
+  unsigned int num_coins,
+  const struct TALER_MERCHANT_PayCoin coins[],
+  TALER_MERCHANT_PayCallback pay_cb,
+  void *pay_cb_cls);
+
+
+/**
+ * Cancel a POST /orders/$ID/pay request.  Note that if you cancel a request
+ * like this, you have no assurance that the request has not yet been
+ * forwarded to the merchant. Thus, the payment may still succeed or fail.
+ * Re-issue the original /pay request to resume/retry and obtain a definitive
+ * result, or refresh the coins involved to ensure that the merchant can no
+ * longer complete the payment.
+ *
+ * @param oph the payment request handle
+ */
+void
+TALER_MERCHANT_order_pay_cancel (struct TALER_MERCHANT_OrderPayHandle *oph);
+
+
+/**
+ * Handle for an POST /orders/$ID/abort operation.
+ */
+struct TALER_MERCHANT_AbortHandle;
 
 
 /**
  * Entry in the array of refunded coins.
  */
-struct TALER_MERCHANT_RefundEntry
+struct TALER_MERCHANT_AbortedCoin
 {
   /**
    * Merchant signature affirming the refund.
@@ -1717,28 +1665,31 @@ struct TALER_MERCHANT_RefundEntry
 
 /**
  * Callbacks of this type are used to serve the result of submitting a
- * /pay request to a merchant.
+ * /orders/$ID/abort request to a merchant.
  *
  * @param cls closure
  * @param hr HTTP response details
  * @param merchant_pub public key of the merchant
  * @param h_contract hash of the contract
- * @param num_refunds size of the @a res array, 0 on errors
- * @param res merchant signatures refunding coins, NULL on errors
+ * @param num_aborts size of the @a res array, 0 on errors
+ * @param aborts merchant signatures refunding coins, NULL on errors
  */
 typedef void
-(*TALER_MERCHANT_PayRefundCallback) (
+(*TALER_MERCHANT_PayAbortCallback) (
   void *cls,
   const struct TALER_MERCHANT_HttpResponse *hr,
   const struct TALER_MerchantPublicKeyP *merchant_pub,
   const struct GNUNET_HashCode *h_contract,
-  unsigned int num_refunds,
-  const struct TALER_MERCHANT_RefundEntry *res);
+  unsigned int num_aborts,
+  const struct TALER_MERCHANT_AbortedCoin aborts[]);
 
 
 /**
- * Run a payment abort operation, asking for refunds for coins
- * that were previously spend on a /pay that failed to go through.
+ * Run a payment abort operation, asking for the payment to be aborted,
+ * yieldingrefunds for coins that were previously spend on a payment that
+ * failed to go through.
+ *
+ * This is a PUBLIC API for wallets.
  *
  * @param ctx execution context
  * @param merchant_url base URL of the merchant
@@ -1759,119 +1710,194 @@ typedef void
  * @param payref_cb_cls closure for @a pay_cb
  * @return a handle for this request
  */
-struct TALER_MERCHANT_Pay *
-TALER_MERCHANT_pay_abort (struct GNUNET_CURL_Context *ctx,
-                          const char *merchant_url,
-                          const struct GNUNET_HashCode *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_Absolute timestamp,
-                          struct GNUNET_TIME_Absolute refund_deadline,
-                          struct GNUNET_TIME_Absolute pay_deadline,
-                          const struct GNUNET_HashCode *h_wire,
-                          const char *order_id,
-                          unsigned int num_coins,
-                          const struct TALER_MERCHANT_PayCoin *coins,
-                          TALER_MERCHANT_PayRefundCallback payref_cb,
-                          void *payref_cb_cls);
+struct TALER_MERCHANT_AbortHandle *
+TALER_MERCHANT_order_abort (struct GNUNET_CURL_Context *ctx,
+                            const char *merchant_url,
+                            const struct GNUNET_HashCode *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_Absolute timestamp,
+                            struct GNUNET_TIME_Absolute refund_deadline,
+                            struct GNUNET_TIME_Absolute pay_deadline,
+                            const struct GNUNET_HashCode *h_wire,
+                            const char *order_id,
+                            unsigned int num_coins,
+                            const struct TALER_MERCHANT_PayCoin coins[],
+                            TALER_MERCHANT_PayAbortCallback cb,
+                            void *cb_cls);
 
 
 /**
- * Information we need from the frontend (ok, the frontend sends just JSON)
- * when forwarding a payment to the backend.
+ * Cancel a POST /orders/$ID/abort request.  Note that if you cancel a request
+ * like this, you have no assurance that the request has not yet been
+ * forwarded to the merchant.
+ *
+ * @param oah the abort request handle
  */
-struct TALER_MERCHANT_PaidCoin
-{
-  /**
-   * Denomination key with which the coin is signed
-   */
-  struct TALER_DenominationPublicKey denom_pub;
+void
+TALER_MERCHANT_order_abort_cancel (struct TALER_MERCHANT_OrderAbortandle *oah);
 
-  /**
-   * Exchange’s unblinded signature of the coin
-   */
-  struct TALER_DenominationSignature denom_sig;
+
+/* *********************   OLD ************************** */
+
+
+/* ********************* /refund ************************** */
+
+/**
+ * Handle for a GET /refund operation.
+ */
+struct TALER_MERCHANT_RefundLookupOperation;
+
+
+/**
+ * Detail about a refund lookup result.
+ */
+struct TALER_MERCHANT_RefundDetail
+{
 
   /**
-   * Overall value that coins of this @e denom_pub have.
+   * Exchange response details.  Full details are only included
+   * upon failure (HTTP status is not #MHD_HTTP_OK).
    */
-  struct TALER_Amount denom_value;
+  struct TALER_EXCHANGE_HttpResponse hr;
 
   /**
-   * Coin's public key.
+   * Coin this detail is about.
    */
   struct TALER_CoinSpendPublicKeyP coin_pub;
 
   /**
-   * Coin's signature key.
+   * Refund transaction ID used.
    */
-  struct TALER_CoinSpendSignatureP coin_sig;
+  uint64_t rtransaction_id;
 
   /**
-   * Amount this coin contributes to (including fee).
+   * Amount to be refunded for this coin.
    */
-  struct TALER_Amount amount_with_fee;
+  struct TALER_Amount refund_amount;
 
   /**
-   * Amount this coin contributes to (without fee).
+   * Applicable refund transaction fee.
    */
-  struct TALER_Amount amount_without_fee;
+  struct TALER_Amount refund_fee;
 
   /**
-   * Fee the exchange charges for refunds of this coin.
+   * Public key of the exchange affirming the refund,
+   * only valid if the @e hr http_status is #MHD_HTTP_OK.
    */
-  struct TALER_Amount refund_fee;
+  struct TALER_ExchangePublicKeyP exchange_pub;
 
   /**
-   * What is the URL of the exchange that issued @a coin_pub?
+   * Signature of the exchange affirming the refund,
+   * only valid if the @e hr http_status is #MHD_HTTP_OK.
    */
-  const char *exchange_url;
+  struct TALER_ExchangeSignatureP exchange_sig;
 
 };
 
 
 /**
- * Pay a merchant.  API for frontends talking to backends. Here,
- * the frontend does not have the coin's private keys, but just
- * the public keys and signatures.  Note the sublte difference
- * in the type of @a coins compared to #TALER_MERCHANT_pay().
+ * Callback to process a GET /refund request
  *
- * @param ctx execution context
- * @param merchant_url base URL of the merchant
+ * @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 order_id which order should be paid
- * @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
- * @param pay_cb_cls closure for @a pay_cb
- * @return a handle for this request
+ * @param num_details length of the @a details array
+ * @param details details about the refund processing
  */
-struct TALER_MERCHANT_Pay *
-TALER_MERCHANT_pay_frontend (
-  struct GNUNET_CURL_Context *ctx,
-  const char *merchant_url,
+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,
-  const char *order_id,
-  unsigned int num_coins,
-  const struct TALER_MERCHANT_PaidCoin *coins,
-  TALER_MERCHANT_PayCallback pay_cb,
-  void *pay_cb_cls);
+  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);
+
+
+/**
+ * Handle for a POST /refund operation.
+ */
+struct TALER_MERCHANT_RefundIncreaseOperation;
 
 
 /**
- * Cancel a /pay request.  Note that if you cancel a request like
- * this, you have no assurance that the request has not yet been
- * forwarded to the merchant. Thus, the payment may still succeed or
- * fail.  Re-issue the original /pay request to resume/retry and
- * obtain a definitive result, or /refresh the coins involved to
- * ensure that the merchant can no longer complete the payment.
+ * Callback to process a POST /refund request
  *
- * @param ph the payment request handle
+ * @param cls closure
+ * @param http_status HTTP status code for this request
+ * @param ec taler-specific error code
+ */
+typedef void
+(*TALER_MERCHANT_RefundIncreaseCallback) (
+  void *cls,
+  const struct TALER_MERCHANT_HttpResponse *hr);
+
+
+/**
+ * Increase the refund associated to a order
+ *
+ * @param ctx the CURL context used to connect to the backend
+ * @param backend_url backend's base URL, including final "/"
+ * @param order_id id of the order whose refund is to be increased
+ * @param refund amount to which increase the refund
+ * @param reason human-readable reason justifying the refund
+ * @param cb callback processing the response from /refund
+ * @param cb_cls closure for cb
+ */
+struct TALER_MERCHANT_RefundIncreaseOperation *
+TALER_MERCHANT_refund_increase (struct GNUNET_CURL_Context *ctx,
+                                const char *backend_url,
+                                const char *order_id,
+                                const struct TALER_Amount *refund,
+                                const char *reason,
+                                TALER_MERCHANT_RefundIncreaseCallback cb,
+                                void *cb_cls);
+
+/**
+ * Cancel a POST /refund request.
+ *
+ * @param rio the refund increasing operation to cancel
  */
 void
-TALER_MERCHANT_pay_cancel (struct TALER_MERCHANT_Pay *ph);
+TALER_MERCHANT_refund_increase_cancel (
+  struct TALER_MERCHANT_RefundIncreaseOperation *rio);
+
+
+/* *********************  /proposal *********************** */
+
+
+/* *********************  /pay *********************** */
 
 
 /* ********************* /track/transfer *********************** */