add /refresh/payback and related coin history

1 files changed, 49 insertions, 1 deletions

diff --git a/api-exchange.rst b/api-exchange.rst
index c764b6b7..9a3111a1 100644
--- a/api-exchange.rst
+++ b/api-exchange.rst
@@ -649,7 +649,7 @@ denomination.
   .. code-block:: tsref
 
     interface CoinSpendHistoryItem {
-      // Either "DEPOSIT", "MELT", "REFUND" or "PAYBACK"
+      // Either "DEPOSIT", "MELT", "REFUND" or "PAYBACK", "REFRESH_PAYBACK"
       type: string;
 
       // The total amount of the coin's value absorbed (or restored in the case of a refund) by this transaction.
@@ -681,6 +681,7 @@ denomination.
       melt_fee: Amount;
 
       // Commitment from the melt operation.
+      // Present if `type` is "MELT" or "REFRESH_PAYBACK"
       rc: TALER_RefreshCommitmentP;
 
       // Hash of the bank account from where we received the funds.
@@ -711,6 +712,14 @@ denomination.
 
       // public key used to sign `exchange_sig`, only present if `exchange_sig` present.
       exchange_pub?: EddsaPublicKey;
+
+      // Blinding factor of the revoked new coin,
+      // only present if `type` is "REFRESH_PAYBACK".
+      new_coin_blinding_secret: RsaBlindingKeySecret;
+
+      // Blinded public key of the revoked new coin,
+      // only present if `type` is "REFRESH_PAYBACK".
+      new_coin_ev: RsaBlindingKeySecret;
     }
 
 ----------
@@ -913,6 +922,45 @@ the API during normal operation.
     }
 
 
+.. http:post:: /refresh/payback
+
+  When a fresh coin that was obtained via refresh is revoked, the refresh payback can be used
+  to revert the refresh and credit the old coin with the refreshed coin's value.
+
+  :status 200 OK:
+    The old coin was successfully credited with the value of the revoked new coin.
+  :status 404 Not Found:
+    Either the refresh commitment has not been seen by the exchange before,
+    the old coin was not found among the refreshed coins,
+    or the blinded new coin's public key has not been seen and signed before
+    by the exchange.
+  :status 401 Unauthorized:
+    The blinding secret does not match the signature stored by the exchange
+    the new_coin_ev.
+
+  **Details:**
+
+  Request body contains a JSON object with the following fields:
+
+  .. code-block:: tsref
+
+    interface RefreshPaybackRequest {
+      // Public key of the old coin that should receive the
+      // refund for the refreshed coin.
+      old_coin_pub: RsaPublicKey;
+
+      // Blinded public key of the coin of the revoked denomination.
+      new_coin_ev: CoinEnvelope;
+
+      // Secret blinding factor of the new coin
+      new_coin_blinding_secret: RsaBlindingKeySecret;
+
+      // Commitment that identifies the refresh operation.
+      // Redundant, but speeds up the exchange's database lookup.
+      rc: HashCode;
+    }
+
+
 .. http:get:: /refresh/link
 
   Link the old public key of a melted coin to the coin(s) that were exchangeed during the refresh operation.