GET /orders/ID API design

1 files 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
@@ -1316,6 +1316,346 @@ TALER_MERCHANT_orders_get_cancel (
 
 
 /**
+ * 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.
  */
 struct TALER_MERCHANT_OrderDeleteHandle;
@@ -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 */