api revisions (#5987)

1 files changed, 43 insertions, 9 deletions

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 70241b09..3c3f670a 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -912,7 +912,7 @@ Receiving Payments
 
       // The session for which the payment is made (or replayed).
       // Only set for session-based payments.
-      session_id: string;
+      session_id?: string;
 
     }
 
@@ -920,13 +920,13 @@ Receiving Payments
 
     export interface CoinPaySig {
       // Signature by the coin.
-      coin_sig: string;
+      coin_sig: EddsaSignature;
 
       // Public key of the coin being spend.
-      coin_pub: string;
+      coin_pub: EddsaPublicKey;
 
       // Signature made by the denomination public key.
-      ub_sig: string;
+      ub_sig: RsaSignature;
 
       // The hash of the denomination public key associated with this coin.
       h_denom: HashCode;
@@ -968,7 +968,8 @@ Receiving Payments
     The merchant's interaction with the exchange failed in some way.
     The error from the exchange is included.
 
-  The backend will return verbatim the error codes received from the exchange's
+  The backend will return an `abort response <AbortResponse>`, which includes
+  verbatim the error codes received from the exchange's
   :ref:`refund <_refund>` API.  The frontend should pass the replies verbatim to
   the browser/wallet.
 
@@ -980,18 +981,51 @@ Receiving Payments
       // wallet/customer in case $ORDER_ID is guessable).
       h_contract: HashCode;
 
-
       // List of coins the wallet would like to see refunds for.
       // (Should be limited to the coins for which the original
       // payment succeeded, as far as the wallet knows.)
-      coins: AbortedCoin[];
+      coins: AbortingCoin[];
     }
 
-  .. ts:def:: AbortedCoin
+  .. ts:def:: AbortingCoin
 
-    interface AbortedCoin {
+    interface AbortingCoin {
       // Public key of a coin for which the wallet is requesting an abort-related refund.
       coin_pub: EddsaPublicKey;
+
+      // The amount to be refunded (matches the original contribution)
+      contribution: Amount;
+
+      // The refund fee the wallet expects to pay (based on the coin's denomination)
+      refund_fee: Amount;
+
+      // URL of the exchange this coin was withdrawn from.
+      exchange_url: string;
+    }
+
+
+  .. ts:def:: AbortResponse
+
+    interface AbortResponse {
+
+      // List of refund responses about the coins that the wallet
+      // requested an abort for.  In the same order as the 'coins'
+      // from the original request.
+      refunds: RefundResult[];
+    }
+
+  .. ts:def:: RefundResult
+
+    interface RefundResult {
+      // HTTP status of the request to the exchange.
+      exchange_status: integer;
+
+      // The full reply from the exchange. Note only actually
+      // a <RefundSuccess> if the `exchange_status` is 200, otherwise
+      // the error message as defined by the refund API.  For
+      // aborts, the `rtransaction_id` is always 0.
+      exchange_body: RefundSuccess;
+
     }