thoughts for C2EC discussion tomorrow

2 files changed, 132 insertions, 55 deletions

diff --git a/core/api-bank-integration.rst b/core/api-bank-integration.rst
index ed4d8de0..1d0f9db9 100644
--- a/core/api-bank-integration.rst
+++ b/core/api-bank-integration.rst
@@ -1,7 +1,7 @@
 ..
   This file is part of GNU TALER.
 
-  Copyright (C) 2014-2023 Taler Systems SA
+  Copyright (C) 2014-2024 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU Affero General Public License as published by the Free Software
@@ -29,7 +29,7 @@ to tightly integrate with GNU Taler.
 .. http:get:: /config
 
   Return the protocol version and configuration information about the bank.
-  This specification corresponds to ``current`` protocol being version **2**.
+  This specification corresponds to ``current`` protocol being **v2**.
 
   **Response:**
 
@@ -91,36 +91,52 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
     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
+    The operation was not found.
 
   **Details:**
 
   .. ts:def:: BankWithdrawalOperationStatus
 
-    export class BankWithdrawalOperationStatus {
+    interface BankWithdrawalOperationStatus {
       // Current status of the operation
       // pending: the operation is pending parameters selection (exchange and reserve public key)
       // selected: the operations has been selected and is pending confirmation
       // aborted: the operation has been aborted
       // confirmed: the transfer has been confirmed and registered by the bank
-      // @since v1
+      // @since **v1**
       status: "pending" | "selected" | "aborted" | "confirmed";
 
       // Amount that will be withdrawn with this operation
-      // (raw amount without fee considerations).
-      amount: Amount;
-
-      // Bank account of the customer that is withdrawing, as a
-      // ``payto`` URI.
+      // (raw amount without fee considerations).  Only
+      // given once the amount is fixed and cannot be changed.
+      // Optional since **vC2EC**.
+      amount?: Amount;
+
+      // Suggestion for the amount to be withdrawn with this
+      // operation.  Given if a suggestion was made but the
+      // user may still change the amount.
+      // Optional since **vC2EC**.
+      suggested_amount?: Amount;
+
+      // Bank account of the customer that is debiting, as an
+      // RFC 8905 ``payto`` URI.
       sender_wire?: string;
 
-      // Suggestion for an exchange given by the bank.
+      // Base URL of the suggested exchange.  The bank may have
+      // neither a suggestion nor a requirement for the exchange.
+      // This value is typically set in the bank's configuration.
       suggested_exchange?: string;
 
+      // Base URL of an exchange that must be used.  Optional,
+      // not given *unless* a particular exchange is mandatory.
+      // This value is typically set in the bank's configuration.
+      // @since **vC2EC**
+      required_exchange?: string;
+
       // URL that the user needs to navigate to in order to
       // complete some final confirmation (e.g. 2FA).
       // Only applicable when ``status`` is ``selected`` or ``pending``.
-      // It may contain withdrawal operation id
+      // It may contain the withdrawal operation id.
       confirm_transfer_url?: string;
 
       // Wire transfer types supported by the bank.
@@ -128,25 +144,25 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
 
       // Reserve public key selected by the exchange,
       // only non-null if ``status`` is ``selected`` or ``confirmed``.
-      // @since v1
+      // @since **v1**
       selected_reserve_pub?: EddsaPublicKey;
 
-      // Exchange account selected by the wallet
+      // Exchange account selected by the wallet;
       // only non-null if ``status`` is ``selected`` or ``confirmed``.
-      // @since v1
+      // @since **v1**
       selected_exchange_account?: string;
 
-      // @deprecated since v1, use ``status`` instead
+      // @deprecated since **v1**, use ``status`` instead
       // Indicates whether the withdrawal was aborted.
       aborted: boolean;
 
-      // @deprecated since v1, use ``status`` instead
+      // @deprecated since **v1**, use ``status`` instead
       // Has the wallet selected parameters for the withdrawal operation
       // (exchange and reserve public key) and successfully sent it
       // to the bank?
       selection_done: boolean;
 
-      // @deprecated since v1, use ``status`` instead
+      // @deprecated since **v1**, use ``status`` instead
       // The transfer has been confirmed and registered by the bank.
       // Does not guarantee that the funds have arrived at the exchange already.
       transfer_done: boolean;
@@ -155,16 +171,27 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
 
 .. http:post:: /withdrawal-operation/$WITHDRAWAL_ID
 
+  This endpoint is used by the GNU Taler wallet to supply additional
+  details needed to complete a withdraw operation.
+
   **Request:**
 
   .. ts:def:: BankWithdrawalOperationPostRequest
 
     interface BankWithdrawalOperationPostRequest {
-      // Reserve public key.
+
+      // Reserve public key that should become the wire transfer
+      // subject to fund the withdrawal.
       reserve_pub: EddsaPublicKey;
 
-      // Payto address of the exchange selected for the withdrawal.
-      selected_exchange?: string;
+      // RFC 8905 (payto) address of the exchange account to be
+      // credited for the withdrawal.
+      selected_exchange: string;
+
+      // Selected amount to be transferred. Optional if the
+      // backend already knows the amount.
+      // @since **vC2EC**
+      amount?: Amount;
     }
 
   **Response:**
@@ -175,11 +202,15 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
   :http:statuscode:`404 Not found`:
     The bank does not know about a withdrawal operation with the specified ``WITHDRAWAL_ID``.
   :http:statuscode:`409 Conflict`:
-    * ``TALER_EC_BANK_WITHDRAWAL_OPERATION_RESERVE_SELECTION_CONFLICT`` :
+    * ``TALER_EC_BANK_WITHDRAWAL_OPERATION_RESERVE_SELECTION_CONFLICT``:
       The wallet selected a different exchange or reserve public key under the same withdrawal ID.
-    * ``TALER_EC_BANK_DUPLICATE_RESERVE_PUB_SUBJECT`` : the reserve public key is already used.
-    * ``TALER_EC_BANK_UNKNOWN_ACCOUNT`` : the selected exchange account was not found.
-    * ``TALER_EC_BANK_ACCOUNT_IS_NOT_EXCHANGE`` : the selected account is not an exchange.
+    * ``TALER_EC_BANK_DUPLICATE_RESERVE_PUB_SUBJECT``: the reserve public key is already used.
+    * ``TALER_EC_BANK_UNKNOWN_ACCOUNT``: the selected exchange account was not found.
+    * ``TALER_EC_BANK_ACCOUNT_IS_NOT_EXCHANGE``: the selected account is not an exchange.
+    * ``TALER_EC_BANK_AMOUNT_DIFFERS`` : the specified amount will not work for this
+      withdrawal (since **vC2EC**).
+    * ``TALER_EC_BANK_AMOUNT_REQUIRED`` : the backend requires an amount to be
+      specified  (since **vC2EC**).
 
   **Details:**
 
@@ -199,6 +230,7 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
       // Only applicable when ``status`` is ``selected`` or ``pending``.
       // It may contain withdrawal operation id
       confirm_transfer_url?: string;
+
       // The transfer has been confirmed and registered by the bank.
       // Does not guarantee that the funds have arrived at the exchange already.
       transfer_done: boolean;
@@ -206,21 +238,49 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
 
 .. http:post:: /withdrawal-operation/$WITHDRAWAL_ID/confirm
 
-  Since protocol vC2EC
+  Endpoint for providers to notify the bank about a payment having happened.
+  This will cause the bank to validate the transaction and allow the
+  withdrawal to proceed. The API is idempotent, meaning sending a payment
+  notification for the same ``WITHDRAWAL_ID`` return successfuly but not
+  change anything.  This endpoint is always *optional*, the bank, exchange and
+  wallet should all eventually notice the wire transfer with or without this
+  endpoint being called.  However, by calling this endpoint checks that might
+  otherwise only happen periodically can be triggered immediately.
+
+  .. note::
+
+    A bank shall **never** just accept this claim that the payment was
+    confirmed, but instead needs to internally attest that the payment was
+    successful using provider-specific transaction validation logic!  The point
+    of this endpoint is merely to trigger this validation **now**.
 
-  Allows a provider to notify the Bank about the payment. This will trigger a payment
-  attestation at the provider, which eventually confirms the payment and allows the
-  withdrawal. The API is idempotent, meaning sending a payment
-  notification for the same ``WITHDRAWAL_ID`` return successfuly but not change anything.
+  Since protocol **vC2EC**.
 
-  Attention: A bank shall **never** just accept the payment directly but instead attest
-  the payment using provider specific attestation logic!
+  FIXME: If this is *just* a trigger, what is the point in supplying the body?
+  After all, a wallet could just do the same POST and then we'd store/process
+  completely bogus information!
+
+  FIXME: why not use /accounts/$USERNAME/withdrawals/$WITHDRAWAL_ID/confirm?
 
   **Request:**
 
+  The body of the request must be a `BankWithdrawalConfirmationRequest`.
+
+  **Response:**
+
+  :http:statuscode:`204 No content`:
+    The payment notification was processed successfully.
+  :http:statuscode:`404 Not found`:
+    The withdrawal operation was not found.
+  :http:statuscode:`409 Conflict`:
+    The withdrawal operation has been aborted previously and can't be aborted
+
+  **Details:**
+
   .. ts:def:: BankWithdrawalConfirmationRequest
 
     interface WithdrawalConfirmationRequest {
+
       // The provider specific transaction identifier.
       // This identifier is used by the bank to attest the
       // payment at the providers backend.
@@ -234,6 +294,8 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
       // This will decide about how the withdrawal
       // is attested. The device must be known to
       // the exchange and be somehow registered.
+      //
+      // FIXME: probably more general to use a *string*.
       terminal_id: number;
 
       // The amount to withdraw. Fees are to be sent in the
@@ -244,21 +306,21 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
       card_fees: Amount;
     }
 
-  **Response**
-
-  :http:statuscode:`204 No content`:
-    The payment notification was processed successfully.
-  :http:statuscode:`404 Not found`:
-    The withdrawal operation was not found.
-  :http:statuscode:`409 Conflict`:
-    The withdrawal operation has been aborted previously and can't be aborted
-
 
 .. http:post:: /withdrawal-operation/$WITHDRAWAL_ID/abort
 
   Aborts ``WITHDRAWAL_ID`` operation.  Has no effect on an already aborted
-  operation.
-  Since protocol v2.
+  operation.  This endpoint can be used by the wallet if the user aborts
+  the transaction, ensuring that the operation is also aborted at the
+  bank.
+
+  **FIXME**: Should we not change this to be a **delete**?
+
+  Since protocol **v2**.
+
+  **Request:**
+
+  The request body is empty.
 
   **Response:**
 
@@ -267,4 +329,5 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
   :http:statuscode:`404 Not found`:
     The withdrawal operation was not found.
   :http:statuscode:`409 Conflict`:
-    The withdrawal operation has been confirmed previously and can't be aborted.
+    The withdrawal operation has been confirmed previously and
+    can't be aborted.
diff --git a/core/api-corebank.rst b/core/api-corebank.rst
index 680b2724..878542d3 100644
--- a/core/api-corebank.rst
+++ b/core/api-corebank.rst
@@ -88,7 +88,7 @@ Config
       // @since v4, will become mandatory in the next version.
       bank_name?: string;
 
-      // Advertised base URL to use when you sharing an URL with another 
+      // Advertised base URL to use when you sharing an URL with another
       // program.
       // @since v4.
       base_url?: string;
@@ -472,7 +472,7 @@ Account Management
 
       // Current status of the account
       // active: the account can be used
-      // deleted: the account has been deleted but is retained for compliance 
+      // deleted: the account has been deleted but is retained for compliance
       // reasons, only the administrator can access it
       // Default to 'active' is missing
       // @since v4, will become mandatory in the next version.
@@ -539,7 +539,7 @@ Account Management
 
       // Current status of the account
       // active: the account can be used
-      // deleted: the account has been deleted but is retained for compliance 
+      // deleted: the account has been deleted but is retained for compliance
       // reasons, only the administrator can access it
       // Default to 'active' is missing
       // @since v4, will become mandatory in the next version.
@@ -682,8 +682,8 @@ Transactions
       row_id: Integer;
     }
 
-Taler Withdrawals
------------------
+Account withdrawals
+-------------------
 
 .. http:post:: /accounts/$USERNAME/withdrawals
 
@@ -691,12 +691,7 @@ Taler Withdrawals
 
   **Request:**
 
-  .. ts:def:: BankAccountCreateWithdrawalRequest
-
-    interface BankAccountCreateWithdrawalRequest {
-      // Amount to withdraw.
-      amount: Amount;
-    }
+  The request must be a `BankAccountCreateWithdrawalRequest`.
 
   **Response:**
 
@@ -709,6 +704,25 @@ Taler Withdrawals
 
   **Details:**
 
+  .. ts:def:: BankAccountCreateWithdrawalRequest
+
+    interface BankAccountCreateWithdrawalRequest {
+
+      // Amount to withdraw.
+      // FIXME: **vC2EC**: make this optional?
+      // FIXME: **vC2EC**: allow making merely a suggestion?
+      amount: Amount;
+
+      // KYC data in case where enable somebody else
+      // to withdraw from "our" account?
+      // FIXME: what would be a good ID?
+      // FIXME: need a way to determine
+      // and return limits per ID!
+      // @since **vC2EC**?
+      kyc_link?: TBD;
+
+    }
+
   .. ts:def:: BankAccountCreateWithdrawalResponse
 
     interface BankAccountCreateWithdrawalResponse {