From f3262a657156df62f062a55aaca3b7704e0d8c35 Mon Sep 17 00:00:00 2001
From: Torsten Grote <t@grobox.de>
Date: Tue, 21 Jul 2020 13:59:22 -0300
Subject: Refinement of wallet withdrawal API

---
 taler-wallet.rst | 125 +++++++++++++++++++++++++------------------------------
 1 file changed, 57 insertions(+), 68 deletions(-)

(limited to 'taler-wallet.rst')

diff --git a/taler-wallet.rst b/taler-wallet.rst
index 604203b1..ede006ad 100644
--- a/taler-wallet.rst
+++ b/taler-wallet.rst
@@ -468,29 +468,6 @@ Add Exchange
   On success, the response is an `ExchangeListItem`.
 
 
-Get Suggested Exchanges
-~~~~~~~~~~~~~~~~~~~~~~~
-
-:Name: ``"getSuggestedExchanges"``
-:Description:
-  Get default exchange and the bank's suggested exchange for a given withdrawal URI.
-:Request:
-  .. ts:def:: ExchangeGetSuggestedRequest
-
-    interface ExchangeGetSuggestedRequest {
-      talerWithdrawUri: string;
-    }
-:Response:
-  .. ts:def:: ExchangeGetSuggestedResponse
-
-    interface ExchangeGetSuggestedResponse {
-      // Exchange suggested by the wallet
-      defaultExchange?: string;
-
-      // Exchange suggested by the bank
-      bankSuggestedExchange?: string;
-    }
-
 Get Terms of Service
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -543,6 +520,26 @@ Set Accepted Terms of Service Version
 Withdrawal
 ----------
 
+A typical API sequence for *bank-integrated* withdrawals can for example look like this:
+
+#. ``"getWithdrawalDetailsForUri"`` returns an amount and default exchange
+#. ``"getWithdrawalDetailsForAmount"`` returns fee information and that ToS are not accepted
+
+   #. ``"getExchangeTos"`` are shown to the user and return currentEtag
+   #. ``"setExchangeTosAccepted"`` called with currentEtag after user accepted
+
+#. ``"acceptWithdrawal"`` after the user confirmed withdrawal with associated fees
+
+A typical API sequence for *manual* withdrawals can for example look like this:
+
+#. ``"listExchanges"`` shows a list of exchanges to the user who picks one and an amount
+#. ``"getWithdrawalDetailsForAmount"`` returns fee information and that ToS are not accepted
+
+   #. ``"getExchangeTos"`` are shown to the user and return currentEtag
+   #. ``"setExchangeTosAccepted"`` called with currentEtag after user accepted
+
+#. ``"acceptManualWithdrawal"`` after the user confirmed withdrawal with associated fees
+
 Withdraw balance from test environment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -556,29 +553,56 @@ Withdraw balance from test environment
 :Response:
   On success, the response is an empty object.
 
-
-Get Withdrawal Info For Bank-integrated Withdrawal
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Get Details For Bank-integrated Withdrawal
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 :Name: ``"getWithdrawalDetailsForUri"``
 :Description:
-  Get information about fees for a bank-integrated withdrawal from a taler://withdraw URI.
+  Get information about exchanges for a bank-integrated withdrawal from a taler://withdraw URI.
 :Request:
-  .. ts:def:: GetManualWithdrawalDetailsRequest
+  .. ts:def:: GetWithdrawalUriDetailsRequest
 
-    interface GetManualWithdrawalDetailsRequest {
+    interface GetWithdrawalUriDetailsRequest {
       talerWithdrawUri: string;
-      exchangeBaseUrl: string;
     }
 :Response:
   .. ts:def:: WithdrawalDetailsForUri
 
     interface WithdrawalDetailsForUri {
-      // Did the user accept the current version of the exchange's
-      // terms of service?
+      // The amount that the user wants to withdraw
+      amount: Amount;
+
+      // Exchange suggested by the wallet
+      defaultExchangeBaseUrl?: string;
+
+      // A list of exchanges that can be used for this withdrawal
+      possibleExchanges: ExchangeListItem[];
+    }
+
+Get Withdrawal Details
+~~~~~~~~~~~~~~~~~~~~~~
+
+:Name: ``"getWithdrawalDetailsForAmount"``
+:Description:
+  Get information about fees and exchange for a withdrawal of a given amount.
+  Can be used for both bank-integrated and manual withdrawals.
+:CLI:
+  ``taler-wallet-cli advanced manual-withdrawal-details $URL $AMOUNT``
+:Request:
+  .. ts:def:: WithdrawalDetailsRequest
+
+    interface WithdrawalDetailsRequest {
+      exchangeBaseUrl: string;
+      amount: Amount;
+    }
+:Response:
+  .. ts:def:: WithdrawalDetails
+
+    interface WithdrawalDetails {
+      // Did the user accept the current version of the exchange's terms of service?
       tosAccepted: boolean;
 
-      // Amount that the bank will transfer to the exchange.
+      // Amount that will be transferred to the exchange.
       rawAmount: Amount;
 
       // Amount that will be added to the user's wallet balance.
@@ -606,41 +630,6 @@ Accept Bank-integrated Withdrawal
       bankConfirmationUrl?: string;
     }
 
-Get Manual Withdrawal Info
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-:Name: ``"getWithdrawalDetailsForAmount"``
-:Description:
-  Get information about fees and exchange for a manual withdrawal of a given amount.
-:CLI:
-  ``taler-wallet-cli advanced manual-withdrawal-details $URL $AMOUNT``
-:Request:
-  .. ts:def:: GetManualWithdrawalDetailsRequest
-
-    interface ExchangeAddRequest {
-      exchangeBaseUrl: string;
-      amount: string;
-    }
-:Response:
-  .. ts:def:: ManualWithdrawalDetails
-
-    interface ManualWithdrawalDetails {
-      // Did the user accept the current version of the exchange's
-      // terms of service?
-      tosAccepted: boolean;
-
-      // Amount that the user will transfer to the exchange.
-      rawAmount: Amount;
-
-      // Amount that will be added to the user's wallet balance.
-      effectiveAmount: Amount;
-
-      // Ways to pay the exchange.
-      // Does not include the amount and message, as the
-      // withdrawal has not been accepted yet.
-      paytoUris: string[];
-    }
-
 Accept Manual Withdrawal
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
cgit v1.2.3