taler-docs

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

prepare-bank-integrated-withdrawal.rst (2089B)

      1 .. ts:op:: prepareBankIntegratedWithdrawal
      2 
      3   Prepare a bank-integrated withdrawal operation.
      4 
      5   Wallet-core resolves the ``taler://withdraw`` URI against the bank's
      6   bank integration API, obtains the status of the withdrawal operation
      7   and creates a withdrawal transaction in a dialog state.  If the bank
      8   suggests an exchange that is not known to the wallet yet, it is
      9   ephemerally added to the wallet's known exchanges.
     10 
     11   After the user has reviewed the operation's details (and selected an
     12   amount and an exchange, where the bank allows choosing them), the
     13   client confirms the withdrawal with :ts:op:`confirmWithdrawal`.
     14 
     15   **Request:**
     16 
     17   The request must be a `PrepareBankIntegratedWithdrawalRequest`
     18   object.
     19 
     20   **Response:**
     21 
     22   On success, the result is a `PrepareBankIntegratedWithdrawalResponse`
     23   object.
     24 
     25   **Side effects:**
     26 
     27   Queries the bank's bank integration API over the network and creates
     28   the withdrawal transaction in the wallet database.  May also fetch
     29   and ephemerally add the exchange suggested by the bank.
     30 
     31   **Expected errors:**
     32 
     33   The caller can handle the following errors inline:
     34   ``WALLET_TALER_URI_MALFORMED``.
     35 
     36   **Details:**
     37 
     38   The operation is idempotent with respect to the URI: calling it
     39   again with the same ``talerWithdrawUri`` returns the existing
     40   withdrawal transaction instead of creating a new one.  If the bank
     41   reports the withdrawal operation as already selected, confirmed or
     42   aborted and the wallet has no transaction for it, the request fails
     43   with ``WALLET_WITHDRAWAL_OPERATION_ABORTED_BY_BANK``.
     44 
     45 .. ts:def:: PrepareBankIntegratedWithdrawalRequest
     46 
     47   interface PrepareBankIntegratedWithdrawalRequest {
     48     talerWithdrawUri: string;
     49 
     50     progressToken?: string;
     51   }
     52 
     53 .. ts:def:: PrepareBankIntegratedWithdrawalResponse
     54 
     55   interface PrepareBankIntegratedWithdrawalResponse {
     56     // Transaction ID of the withdrawal transaction (newly created or
     57     // already existing for the same URI).
     58     transactionId: TransactionIdStr;
     59 
     60     // Details of the bank-side withdrawal operation.
     61     info: WithdrawUriInfoResponse;
     62   }