taler-docs

commit 09f0a8331b2c0ca9207138e19f47ac118b1c40ba
parent 620cd7fb6eb6cf51896778a50c0666c5b79dad67
Author: Joel Häberli <haebu@rubigen.ch>
Date:   Fri, 26 Apr 2024 08:46:37 +0200

docs: terminal-api review

Diffstat:
M
core/api-bank-integration.rst
 | 
3
++-
M
core/api-terminal.rst
 | 
42
+++++++++++++++++++++++++++++-------------

2 files changed, 31 insertions(+), 14 deletions(-)
diff --git a/core/api-bank-integration.rst b/core/api-bank-integration.rst
@@ -47,6 +47,7 @@ to tightly integrate with GNU Taler.
 
       // libtool-style representation of the Bank protocol version, see
       // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
+ 
       // The format is "current:revision:age".
       version: string;
 
@@ -67,7 +68,7 @@ Withdrawing
 -----------
 
 Withdrawals with a Taler-integrated bank are based on withdrawal operations.
-Some user interaction (on the bank's website or a Taler-enabled ATM) creates a
+Some user interaction (on the bank's websitei) creates a
 withdrawal operation record in the bank's database.  The wallet can use a unique identifier
 for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdrawal operation.
 
diff --git a/core/api-terminal.rst b/core/api-terminal.rst
@@ -197,18 +197,13 @@ Config
       // as we may not know it at this time.
       provider_transaction_id?: string;
 
-      // An identifier, which identifies the device
-      // processing the payment for the withdrawal
-      // triggering the confirmation (e.g. Terminal
-      // or ATM). This is useful to internally link
-      // the withdrawal to a terminal owned by a
-      // specific provider.
-      terminal_id?: string;
-
-      // The non-Taler card fees the customer will have
+      // The non-Taler fees the customer will have
       // to pay to the service provider
       // they are using to make this withdrawal.
-      card_fees: Amount;
+      // If the fees cannot be precalculated,
+      // they can be specified in the /withdrawals/$WITHDRAWAL_ID/check
+      // request after the transaction was executed.
+      terminal_fees?: Amount;
 
       // Unique request ID to make retried requests idempotent.
       request_uid: string;
@@ -221,7 +216,6 @@ Config
       // may wish to use in this operation.  May only be
       // present if ``user_uuid`` is also given.
       lock?: string;
-
     }
 
   .. ts:def:: TerminalWithdrawalSetupResponse
@@ -230,7 +224,6 @@ Config
 
       // ID identifying the withdrawal operation being created.
       withdrawal_id: string;
-
     }
 
 
@@ -287,6 +280,10 @@ Config
       // backend to check that the credit was confirmed.
       provider_transaction_id?: string;
 
+      // The fees which the customer had to pay to the 
+      // provider
+      terminal_fees?: Amount;
+
       // A user-specific identifier for quota checks.
       user_uuid?: string;
 
@@ -294,10 +291,29 @@ Config
       // may wish to use in this operation.  May only be
       // present if ``user_uuid`` is also given.
       lock?: string;
-
     }
 
+.. http:get:: /withdrawals/$WITHDRAWAL_ID
+
+  Query information about a withdrawal, identified by the ``WITHDRAWAL_ID``.
+
+  **Request:**
+
+  :query long_poll_ms:
+    *Optional.*  If specified, the bank will wait up to ``long_poll_ms``
+    milliseconds for operationt state to be different from ``old_state`` before sending the HTTP
+    response.  A client must never rely on this behavior, as the bank may
+    return a response immediately.
+  :query old_state:
+    *Optional.* Default to "pending".
+
+  **Response:**
 
+  :http:statuscode:`200 OK`:
+    The withdrawal operation is known to the bank, and details are given
+    in the `BankWithdrawalOperationStatus` response body.
+  :http:statuscode:`404 Not found`:
+    The operation was not found.
 
 Endpoints for Integrated Sub-APIs
 ---------------------------------