[taler-docs] branch master updated: add merchant POST /orders/$ORDER_ID/refund

[gnunet]

This is an automated email from the git hooks/post-receive script.

jonathan-buchanan pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new b86bb33  add merchant POST /orders/$ORDER_ID/refund
b86bb33 is described below

commit b86bb3377a8052e3a88645287311ce1dd39bc8c5
Author: Jonathan Buchanan <jonathan.russ.buchanan@gmail.com>
AuthorDate: Fri Aug 14 20:57:54 2020 -0400

    add merchant POST /orders/$ORDER_ID/refund
---
 core/api-merchant.rst | 170 ++++++++++++++++++++++++++++++--------------------
 1 file changed, 101 insertions(+), 69 deletions(-)

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index db1bf9c..cff71d0 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -1428,9 +1428,6 @@ Payment processing
       // Amount that was refunded in total.
       refund_amount: Amount;
 
-      // Successful refunds for this payment, empty array for none.
-      refunds: MerchantCoinRefundStatus[];
-
       // Public key of the merchant.
       merchant_pub: EddsaPublicKey;
 
@@ -1458,6 +1455,106 @@ Payment processing
       fulfillment_url: string;
     }
 
+
+.. http:delete:: /private/orders/$ORDER_ID
+
+  Delete information about an order.  Fails if the order was paid in the
+  last 10 years (or whatever TAX_RECORD_EXPIRATION is set to) or was
+  claimed but is unpaid and thus still a valid offer.
+
+  **Response:**
+
+  :status 204 No content:
+    The backend has successfully deleted the order.
+  :status 404 Not found:
+    The backend does not know the instance or the order.
+  :status 409 Conflict:
+    The backend refuses to delete the order.
+
+
+.. _merchant_refund:
+
+--------------
+Giving Refunds
+--------------
+
+.. http:post:: /private/orders/$ORDER_ID/refund
+
+  Increase the refund amount associated with a given order.  The user should be
+  redirected to the ``taler_refund_uri`` to trigger refund processing in the 
wallet.
+
+  **Request:**
+
+  The request body is a `RefundRequest` object.
+
+  **Response:**
+
+  :status 200 OK:
+    The refund amount has been increased, the backend responds with a 
`MerchantRefundResponse`
+  :status 404 Not found:
+    The order is unknown to the merchant
+  :status 410 Gone:
+    It is too late for aborting, the exchange may have already wired the funds
+    to the merchant.
+  :status 409 Conflict:
+    The refund amount exceeds the amount originally paid
+
+  .. ts:def:: RefundRequest
+
+    interface RefundRequest {
+      // Amount to be refunded
+      refund: Amount;
+
+      // Human-readable refund justification
+      reason: string;
+    }
+
+  .. ts:def:: MerchantRefundResponse
+
+    interface MerchantRefundResponse {
+
+      // URL (handled by the backend) that the wallet should access to
+      // trigger refund processing.
+      // taler://refund/[$H_CONTRACT/$AMOUNT????]
+      taler_refund_uri: string;
+    }
+
+
+.. http:post:: /orders/$ORDER_ID/refund
+
+  Obtain refunds for an order. After talking to the exchange, the refunds will
+  no longer be pending if processed successfully.
+
+  **Request:**
+
+  :query h_contract=HASH: hash of the order's contract terms (this is used to 
authenticate the wallet/customer in case $ORDER_ID is guessable). Required.
+
+  **Response:**
+
+  :status 200 OK:
+    The response is a `WalletRefundResponse`.
+  :status 403 Forbidden:
+    The ``h_contract`` does not match the order.
+  :status 404 Not found:
+    The merchant backend is unaware of the order.
+
+  .. ts:def:: WalletRefundResponse
+
+    interface WalletRefundResponse {
+      // Was the payment refunded (even partially, via refund or abort)?
+      refunded: boolean;
+
+      // Amount that was refunded in total.
+      refund_amount: Amount;
+
+      // Successful refunds for this payment, empty array for none.
+      refunds: MerchantCoinRefundStatus[];
+
+      // Public key of the merchant.
+      merchant_pub: EddsaPublicKey;
+
+    }
+
   .. ts:def:: MerchantCoinRefundStatus
 
     type MerchantCoinRefundStatus =
@@ -1497,7 +1594,7 @@ Payment processing
     // Additional details needed to verify the refund confirmation signature
     // (``h_contract_terms`` and ``merchant_pub``) are already known
     // to the wallet and thus not included.
-    interface RefundConfirmation {
+    interface MerchantCoinRefundSuccessStatus {
       // Used as tag for the sum type MerchantCoinRefundStatus sum type.
       type: "success";
 
@@ -1528,71 +1625,6 @@ Payment processing
     }
 
 
-.. http:delete:: /private/orders/$ORDER_ID
-
-  Delete information about an order.  Fails if the order was paid in the
-  last 10 years (or whatever TAX_RECORD_EXPIRATION is set to) or was
-  claimed but is unpaid and thus still a valid offer.
-
-  **Response:**
-
-  :status 204 No content:
-    The backend has successfully deleted the order.
-  :status 404 Not found:
-    The backend does not know the instance or the order.
-  :status 409 Conflict:
-    The backend refuses to delete the order.
-
-
-.. _merchant_refund:
-
---------------
-Giving Refunds
---------------
-
-.. http:post:: /private/orders/$ORDER_ID/refund
-
-  Increase the refund amount associated with a given order.  The user should be
-  redirected to the ``taler_refund_uri`` to trigger refund processing in the 
wallet.
-
-  **Request:**
-
-  The request body is a `RefundRequest` object.
-
-  **Response:**
-
-  :status 200 OK:
-    The refund amount has been increased, the backend responds with a 
`MerchantRefundResponse`
-  :status 404 Not found:
-    The order is unknown to the merchant
-  :status 410 Gone:
-    It is too late for aborting, the exchange may have already wired the funds
-    to the merchant.
-  :status 409 Conflict:
-    The refund amount exceeds the amount originally paid
-
-  .. ts:def:: RefundRequest
-
-    interface RefundRequest {
-      // Amount to be refunded
-      refund: Amount;
-
-      // Human-readable refund justification
-      reason: string;
-    }
-
-  .. ts:def:: MerchantRefundResponse
-
-    interface MerchantRefundResponse {
-
-      // URL (handled by the backend) that the wallet should access to
-      // trigger refund processing.
-      // taler://refund/[$H_CONTRACT/$AMOUNT????]
-      taler_refund_uri: string;
-    }
-
-
-
 ------------------------
 Tracking Wire Transfers
 ------------------------

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.