[taler-docs] branch master updated: simplify recoup API response, add some comments

[gnunet]

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

dold pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 420b0b9  simplify recoup API response, add some comments
420b0b9 is described below

commit 420b0b9d1432c06de50e96cdbb305c4a70063644
Author: Florian Dold <address@hidden>
AuthorDate: Wed Mar 18 16:39:20 2020 +0530

    simplify recoup API response, add some comments
---
 core/api-exchange.rst | 48 ++++++++++++++++++++++--------------------------
 1 file changed, 22 insertions(+), 26 deletions(-)

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 8fc1256..06130e5 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -1050,6 +1050,12 @@ in using this API.
   exchange. The exchange MUST return a 307 or 308 redirection to the correct
   base URL if this is the case.
 
+  Depending whether ``$COIN_PUB`` is a withdrawn coin or a refreshed coin,
+  the remaining amount on the coin will be credited either on the reserve or
+  the old coin that ``$COIN_PUB`` was withdrawn/refreshed from.
+
+  Note that the original withdrawal/refresh fees will **not** be recouped.
+
 
   **Request:** The request body must be a `RecoupRequest` object.
 
@@ -1090,42 +1096,32 @@ in using this API.
       coin_sig: EddsaSignature;
 
       // Was the coin refreshed (and thus the recoup should go to the old 
coin)?
-      // Optional (for backwards compatibility); if absent, "false" is assumed
+      // While this information is technically redundant, it helps the exchange
+      // to respond faster.
+      // *Optional* (for backwards compatibility); if absent, "false" is 
assumed
       refreshed?: boolean;
     }
 
 
   .. ts:def:: RecoupConfirmation
 
-    interface RecoupConfirmation {
-      // public key of the reserve that will receive the recoup,
-      // provided if refreshed was false.
-      reserve_pub?: EddsaPublicKey;
-
-      // public key of the old coin that will receive the recoup,
-      // provided if refreshed was true.
-      old_coin_pub?: EddsaPublicKey;
+    type RecoupConfirmation = | RecoupRefreshConfirmation
+                              | RecoupWithdrawalConfirmation;
 
-      // How much will the exchange pay back (needed by wallet in
-      // case coin was partially spent and wallet got restored from backup)
-      amount: Amount;
+  .. ts:def:: RecoupWithdrawalConfirmation
 
-      // Time by which the exchange received the /recoup request.
-      timestamp: Timestamp;
+    // type of response provided if refreshed was false.
+    interface RecoupWithdrawalConfirmation {
+      // public key of the reserve that will receive the recoup,
+      reserve_pub: EddsaPublicKey;
+    }
 
-      // the EdDSA signature of `TALER_RecoupConfirmationPS` (refreshed false)
-      // or `TALER_RecoupRefreshConfirmationPS` (refreshed true) using a 
current
-      // `signing key of the exchange <sign-key-priv>` affirming the successful
-      // recoup request, and that the exchange promises to transfer the funds
-      // by the date specified (this allows the exchange delaying the transfer
-      // a bit to aggregate additional recoup requests into a larger one).
-      exchange_sig: EddsaSignature;
+  .. ts:def:: RecoupRefreshConfirmation
 
-      // 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;
+    // type of response provided if refreshed was true.
+    interface RecoupRefreshConfirmation {
+      // public key of the old coin that will receive the recoup
+      old_coin_pub: EddsaPublicKey;
     }
 
 

-- 
To stop receiving notification emails like this one, please contact
address@hidden.