From 86274e64807f70386baea68557b9b8535d5fdf24 Mon Sep 17 00:00:00 2001
From: Christian Grothoff <christian@grothoff.org>
Date: Fri, 1 May 2020 13:44:30 +0200
Subject: more refund documentation

---
 core/api-merchant.rst | 34 +++++++++++++++++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

(limited to 'core')

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index e20b5319..2cc57ae0 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -1021,6 +1021,8 @@ Receiving Payments
 
   .. ts:def:: RefundResult
 
+    // RefundResult differs from RefundDetail as in this case we
+    // can generate a substantially shorter response.
     interface RefundResult {
       // HTTP status of the request to the exchange.
       exchange_status: integer;
@@ -1185,7 +1187,7 @@ Receiving Payments
       // Amount that was refunded in total.
       refund_amount: Amount;
 
-      // Refunds for this payment, empty array for none.
+      // Successful refunds for this payment, empty array for none.
       refunds: RefundDetail[];
 
       // URI that the wallet must process to complete the payment.
@@ -1197,6 +1199,36 @@ Receiving Payments
 
     }
 
+  .. ts:def:: RefundDetail
+
+    // 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 RefundDetail {
+
+      // the EdDSA :ref:`signature` (binary-only) with purpose
+      // `TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND` using a current signing key of the
+      // exchange affirming the successful refund
+      exchange_sig: EddsaSignature;
+
+      // public EdDSA key of the exchange that was used to generate the signature.
+      // Should match one of the exchange's signing keys from /keys.  It is given
+      // explicitly as the client might otherwise be confused by clock skew as to
+      // which signing key was used.
+      exchange_pub: EddsaPublicKey;
+
+      // Refund transaction ID.
+      rtransaction_id: Integer;
+
+      // public key of a coin that was refunded
+      coin_pub: EddsaPublicKey;
+
+      // Amount that was refunded, including refund fee charged by the exchange
+      // to the customer.
+      refund_amout: Amount;
+
+    }
+
 
 .. http:delete:: /private/orders/$ORDER_ID
 
-- 
cgit v1.2.3