split /recoup handler into /recoup and /recoup-refresh

1 files changed, 73 insertions, 24 deletions

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 9378eda7..6bb2b455 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -2392,11 +2392,10 @@ 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.
+  The remaining amount on the coin will be credited to the reserve
+  that ``$COIN_PUB`` was withdrawn from.
 
-  Note that the original withdrawal/refresh fees will **not** be recouped.
+  Note that the original withdrawal fees will **not** be recouped.
 
 
   **Request:** The request body must be a `RecoupRequest` object.
@@ -2404,7 +2403,7 @@ in using this API.
   **Response:**
 
   :http:statuscode:`200 OK`:
-    The request was successful, and the response is a `RecoupConfirmation`.
+    The request was successful, and the response is a `RecoupWithdrawalConfirmation`.
     Note that repeating exactly the same request
     will again yield the same response, so if the network goes down during the
     transaction or before the client can commit the coin signature to disk, the
@@ -2421,8 +2420,7 @@ in using this API.
     residual value, or because the same public key of the coin has been
     previously used with a different denomination.  Which case it is
     can be decided by looking at the error code
-    (``TALER_EC_EXCHANGE_RECOUP_COIN_BALANCE_ZERO`` or
-    ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``).
+    (usually ``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS``).
     The response is a `DepositDoubleSpendError`.
   :http:statuscode:`410 Gone`:
     The requested denomination key is not yet or no longer valid.
@@ -2436,7 +2434,7 @@ in using this API.
   .. ts:def:: RecoupRequest
 
     interface RecoupRequest {
-      // Hash of denomination public key (RSA), specifying the type of coin the client
+      // Hash of denomination public key, specifying the type of coin the client
       // would like the exchange to pay back.
       denom_pub_hash: HashCode;
 
@@ -2450,35 +2448,86 @@ in using this API.
       // the `coin's private key <coin-priv>`.
       coin_sig: EddsaSignature;
 
-      // Was the coin refreshed (and thus the recoup should go to the old coin)?
-      // 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
-
-    type RecoupConfirmation = | RecoupRefreshConfirmation
-                              | RecoupWithdrawalConfirmation;
-
   .. ts:def:: RecoupWithdrawalConfirmation
 
     interface RecoupWithdrawalConfirmation {
-      // Tag to distinguish the `RecoupConfirmation` response type.
-      refreshed: false;
-
       // Public key of the reserve that will receive the recoup.
       reserve_pub: EddsaPublicKey;
     }
 
+
+.. http:post:: /coins/$COIN_PUB/recoup-refresh
+
+  Demand that a coin be refunded via wire transfer to the original owner.
+
+  The base URL for ``/coins/``-requests may differ from the main base URL of the
+  exchange. The exchange MUST return a 307 or 308 redirection to the correct
+  base URL if this is the case.
+
+  The remaining amount on the coin will be credited to
+  the old coin that ``$COIN_PUB`` was refreshed from.
+
+  Note that the original refresh fees will **not** be recouped.
+
+
+  **Request:** The request body must be a `RecoupRefreshRequest` object.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The request was successful, and the response is a `RecoupRefreshConfirmation`.
+    Note that repeating exactly the same request
+    will again yield the same response, so if the network goes down during the
+    transaction or before the client can commit the coin signature to disk, the
+    coin is not lost.
+  :http:statuscode:`401 Unauthorized`:
+    The coin's signature is invalid.
+  :http:statuscode:`404 Not found`:
+    The denomination key is unknown, or the blinded
+    coin is not known to have been withdrawn.
+    If the denomination key is unknown, the response will be
+    a `DenominationUnknownMessage`.
+  :http:statuscode:`409 Conflict`:
+    The operation is not allowed as the coin has insufficient
+    residual value, or because the same public key of the coin has been
+    previously used with a different denomination.  Which case it is
+    can be decided by looking at the error code
+    (usually ``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_BALANCE``).
+    The response is a `DepositDoubleSpendError`.
+  :http:statuscode:`410 Gone`:
+    The requested denomination key is not yet or no longer valid.
+    It either before the validity start, past the expiration or was not yet revoked. The response is a
+    `DenominationExpiredMessage`. Clients must evaluate
+    the error code provided to understand which of the
+    cases this is and handle it accordingly.
+
+  **Details:**
+
+  .. ts:def:: RecoupRefreshRequest
+
+    interface RecoupRefreshRequest {
+      // Hash of denomination public key, specifying the type of coin the client
+      // would like the exchange to pay back.
+      denom_pub_hash: HashCode;
+
+      // Signature over the `coin public key <eddsa-coin-pub>` by the denomination.
+      denom_sig: DenominationSignature;
+
+      // Coin's blinding factor.
+      coin_blind_key_secret: DenominationBlindingKeySecret;
+
+      // Signature of `TALER_RecoupRefreshRequestPS` created with
+      // the `coin's private key <coin-priv>`.
+      coin_sig: EddsaSignature;
+    }
+
+
   .. ts:def:: RecoupRefreshConfirmation
 
     interface RecoupRefreshConfirmation {
-      // Tag to distinguish the `RecoupConfirmation` response type.
-      refreshed: true;
-
       // Public key of the old coin that will receive the recoup.
       old_coin_pub: EddsaPublicKey;
     }