Merge branch 'master' of git+ssh://taler.net/var/git/api

1 files changed, 75 insertions, 20 deletions

diff --git a/api-exchange.rst b/api-exchange.rst
index c396986a..6d94d112 100644
--- a/api-exchange.rst
+++ b/api-exchange.rst
@@ -118,6 +118,9 @@ possibly by using HTTPS.
       // Fee charged by the exchange for refreshing a coin of this denomination
       fee_refresh: Amount;
 
+      // Fee charged by the exchange for refunding a coin of this denomination
+      fee_refund: Amount;
+
       // Signature with purpose
       // `TALER_SIGNATURE_MASTER_DENOMINATION_KEY_VALIDITY` over the expiration
       // dates, value and the key, created with the exchange's master key.
@@ -125,7 +128,7 @@ possibly by using HTTPS.
     }
 
   Fees for any of the operations can be zero, but the fields must still be
-  present. The currency of the `fee_deposit` and `fee_refresh` must match the
+  present. The currency of the `fee_deposit`, `fee_refresh` and `fee_refund` must match the
   currency of the `value`.  Theoretically, the `fee_withdraw` could be in a
   different currency, but this is not currently supported by the
   implementation.
@@ -461,8 +464,8 @@ denomination.
 
   **Response:**
 
-  :status 200:
-    The operation succeeded, the exchange confirms that no double-spending took place.
+  :status 200 Ok:
+    The operation succeeded, the exchange confirms that no double-spending took place.  The response will include a `DepositSuccess`_ object.
   :status 401 Unauthorized:
     One of the signatures is invalid.
   :status 403:
@@ -536,7 +539,8 @@ denomination.
 
   .. code-block:: tsref
 
-    interface DepositSuccess {
+     .. _DepositSuccess:
+     interface DepositSuccess {
       // The string constant "DEPOSIT_OK"
       status: string;
 
@@ -566,25 +570,28 @@ denomination.
       history: CoinSpendHistoryItem[];
     }
 
+  .. _CoinSpendHistoryItem:
   .. code-block:: tsref
 
     interface CoinSpendHistoryItem {
-      // Either "deposit" or "melt"
+      // Either "deposit" or "melt" or "refund"
       type: string;
 
-      // The total amount of the coin's value absorbed by this transaction
+      // The total amount of the coin's value absorbed (or restored in the case of a refund) by this transaction
       amount: Amount;
 
       // base32 binary encoding of the transaction data as a
       // `TALER_DepositRequestPS` or `TALER_RefreshMeltCoinAffirmationPS`
+      // or `TALER_RefundRequestPS`
       // struct described in :ref:`Signatures`.  Its `purpose` should match our
       // `type`, `amount_with_fee`, should match our `amount`, and its `size`
-      // should be consistent.
+      // should be consistent with the respective struct type.
       details: string;
 
       // the EdDSA :ref:`signature` (binary-only) made with purpose
       // `TALER_SIGNATURE_WALLET_COIN_DEPOSIT` or
-      // `TALER_SIGNATURE_WALLET_COIN_MELT` over the transaction's details.
+      // `TALER_SIGNATURE_WALLET_COIN_MELT` or
+      // `TALER_SIGNATURE_MERCHANT_REFUND` over the transaction's details.
       signature: EddsaSignature;
     }
 
@@ -1094,36 +1101,84 @@ typically also view the balance.)
     }
 
 
-
 -------
 Refunds
 -------
 
   .. note::
 
-     Refunds are currently not implemented (#3641), this documentation is thus
-     rather preliminary and subject to change.
+     Refunds are currently not implemented (#3641), this documentation is thus a bit preliminary and may still change.
 
 .. _refund:
 .. http:POST:: /refund
 
   Undo deposit of the given coin, restoring its value.
 
-  **Request:**
+  **Request:** The request body must be a `RefundRequest`_ object.
+
+  **Response:**
+
+  :status 200 Ok:
+    The operation succeeded, the exchange confirms that the coin can now be refreshed.  The response will include a `RefundSuccess`_ object.
+  :status 401 Unauthorized:
+    Merchant signature is invalid.
+  :status 404 Not found: 
+    The refund operation failed as we could not find a matching deposit operation (coin, contract, transaction ID and merchant public key must all match).
+
+  **Details:**
 
+  .. _RefundRequest:
   .. code-block:: tsref
 
-    interface RefundRequest {
-      // If the coin was claimed as a refund, this field should contain the
-      // retract permission obtained from the merchant, otherwise it should not be
-      // present.
-      // TODO: document what the type
-      retract_perm: any;
+     interface RefundRequest {
+
+      // Amount to be refunded, can be a fraction of the
+      // coin's total deposit value (including deposit fee);
+      // must be larger than the refund fee.
+      refund_amount: Amount;
+
+      // Refund fee associated with the given coin.
+      // must be smaller than the refund amount.
+      refund_fee: Amount;
+
+      // SHA-512 hash of the contact of the merchant with the customer.
+      H_contract: HashCode;
+
+      // coin's public key, both ECDHE and EdDSA.
+      coin_pub: CoinPublicKey;
+
+      // 64-bit transaction id of the original transaction between merchant and customer
+      transaction_id: number;
+     
+      // 64-bit transaction id of the refund transaction between merchant and customer
+      rtransaction_id: number;
+
+      // EdDSA public key of the merchant.
+      merchant_pub: EddsaPublicKey;
+
+      // EdDSA signature of the merchant affirming the refund.
+      merchant_sig: EddsaPublicKey;
 
-      // Value returned due to the retraction.
-      retract_value: string;
     }
 
+  .. code-block:: tsref
+
+     .. _RefundSuccess:
+     interface RefundSuccess {
+      // The string constant "REFUND_OK"
+      status: string;
+
+      // 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
+      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.
+      pub: EddsaPublicKey;
+    }
 
 ------------------------------
 Administrative API: Key update