taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

confirm-withdrawal.rst (2372B)

      1 .. ts:op:: confirmWithdrawal
      2 
      3   Confirm a withdrawal transaction.
      4 
      5   Confirms a bank-integrated withdrawal that was previously prepared
      6   with :ts:op:`prepareBankIntegratedWithdrawal`, selecting the exchange
      7   to withdraw from and, where the withdrawal operation has an editable
      8   amount, the amount to withdraw.  The exchange's terms of service must
      9   have been accepted and any pending exchange key change must have been
     10   confirmed beforehand.
     11 
     12   After the confirmation, the user authorizes the actual wire transfer
     13   to the exchange in their banking application.
     14 
     15   **Request:**
     16 
     17   The request must be a `ConfirmWithdrawalRequest` object.
     18 
     19   **Response:**
     20 
     21   On success, the result is an empty object.
     22 
     23   **Side effects:**
     24 
     25   Updates the withdrawal transaction in the wallet database and starts
     26   the background task that registers the reserve with the bank and
     27   withdraws the coins.  May talk to the exchange, the bank integration
     28   API and the bank conversion service over the network; when an amount
     29   is given, denomination verification results are stored in the
     30   database.  A sender bank account that is new to the wallet is added
     31   to its known bank accounts.
     32 
     33   **Expected errors:**
     34 
     35   The caller can handle the following errors inline:
     36   ``WALLET_KYC_LIMIT_EXCEEDED``, ``WALLET_NO_SUITABLE_EXCHANGE``,
     37   ``WALLET_EXCHANGE_TOS_NOT_ACCEPTED``, ``WALLET_TRANSACTION_NOT_FOUND``,
     38   ``GENERIC_CURRENCY_MISMATCH``, ``WALLET_CORE_API_BAD_REQUEST``,
     39   ``WALLET_EXCHANGE_KEYS_NOT_ACCEPTED``.
     40 
     41   **Details:**
     42 
     43   The ``transactionId`` must refer to a withdrawal transaction that is
     44   still in the dialog state.  Confirming is idempotent: once the
     45   withdrawal has been registered with the bank, repeating the
     46   confirmation succeeds without further effect.
     47 
     48   The ``amount`` may only be omitted for withdrawals from a foreign
     49   account (a ``taler://withdraw`` URI with
     50   ``external-confirmation=1``), where the bank fixes the amount when
     51   the transfer is confirmed.
     52 
     53 .. ts:def:: ConfirmWithdrawalRequest
     54 
     55   interface ConfirmWithdrawalRequest {
     56     transactionId: string;
     57     exchangeBaseUrl: string;
     58     amount?: AmountString | undefined;
     59     forcedDenomSel?: ForcedDenomSel;
     60     restrictAge?: number;
     61 
     62     progressToken?: string;
     63   }
     64 
     65 .. ts:def:: ForcedDenomSel
     66 
     67   interface ForcedDenomSel {
     68     denoms: {
     69       value: AmountString;
     70       count: number;
     71     }[];
     72   }