refund API improvements

1 files changed, 53 insertions, 20 deletions

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 35dc2ff7..4fcec23a 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -1090,23 +1090,55 @@ Payment processing
       // 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[];
+      // The rtransaction_id is implied to be 0.
+      refunds: MerchantAbortPayRefundStatus[];
     }
 
-  .. ts:def:: RefundResult
+  .. ts:def:: MerchantAbortPayRefundStatus
 
-    // RefundResult differs from RefundDetail as in this case we
-    // can generate a substantially shorter response.
-    interface RefundResult {
-      // HTTP status of the request to the exchange.
-      exchange_http_status: Integer;
+    type MerchantAbortPayRefundStatus =
+      | MerchantAbortPayRefundSuccessStatus
+      | MerchantAbortPayRefundFailureStatus;
 
-      // The full reply from the exchange. Note only actually
-      // a <RefundSuccess> if the \exchange_http_status\ is 200, otherwise
-      // the error message as defined by the refund API.  For
-      // aborts, the \rtransaction_id\ is always 0.
-      exchange_reply: RefundSuccess;
+  .. ts:def:: MerchantAbortPayRefundFailureStatus
 
+    // Details about why a refund failed.
+    interface MerchantAbortPayRefundFailureStatus {
+      // Used as tag for the sum type RefundStatus sum type.
+      success: false;
+
+      // HTTP status of the exchange request, must NOT be 200.
+      exchange_status: Integer;
+
+      // Taler error code from the exchange reply, if available.
+      exchange_code?: Integer;
+
+      // If available, HTTP reply from the exchange.
+      exchange_reply?: Object;
+    }
+
+  .. ts:def:: MerchantAbortPayRefundSuccessStatus
+
+    // Additional details needed to verify the refund confirmation signature
+    // (``h_contract_terms`` and ``merchant_pub``) are already known
+    // to the wallet and thus not included.
+    interface RefundConfirmation {
+      // Used as tag for the sum type MerchantCoinRefundStatus sum type.
+      success: true;
+
+      // HTTP status of the exchange request, 200 (integer) required for refund confirmations.
+      exchange_status: 200;
+
+      // 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
+      exchange_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.
+      exchange_pub: EddsaPublicKey;
     }
 
 
@@ -1343,7 +1375,7 @@ Payment processing
       refund_amount: Amount;
 
       // Successful refunds for this payment, empty array for none.
-      refunds: RefundStatus[];
+      refunds: MerchantCoinRefundStatus[];
 
       // Public key of the merchant.
       merchant_pub: EddsaPublicKey;
@@ -1366,15 +1398,16 @@ Payment processing
     }
 
 
-  .. ts:def:: RefundStatus
+  .. ts:def:: MerchantCoinRefundStatus
 
-    type RefundStatus = RefundFailure | RefundConfirmation
+    type MerchantCoinRefundStatus =
+      | MerchantCoinRefundSuccessStatus
+      | MerchantCoinRefundFailureStatus;
 
-
-  .. ts:def:: RefundFailure
+  .. ts:def:: MerchantCoinRefundFailureStatus
 
     // Details about why a refund failed.
-    interface RefundFailure {
+    interface MerchantCoinRefundFailureStatus {
       // Used as tag for the sum type RefundStatus sum type.
       success: false;
 
@@ -1399,13 +1432,13 @@ Payment processing
 
     }
 
-  .. ts:def:: RefundConfirmation
+  .. ts:def:: MerchantCoinRefundSuccessStatus
 
     // Additional details needed to verify the refund confirmation signature
     // (``h_contract_terms`` and ``merchant_pub``) are already known
     // to the wallet and thus not included.
     interface RefundConfirmation {
-      // Used as tag for the sum type RefundStatus sum type.
+      // Used as tag for the sum type MerchantCoinRefundStatus sum type.
       success: true;
 
       // HTTP status of the exchange request, 200 (integer) required for refund confirmations.