taler-docs

get-withdrawal-details-for-amount.rst (8049B)

---

 .. ts:op:: getWithdrawalDetailsForAmount
 
   Get details for withdrawing a particular amount (manual withdrawal).
 
   Computes the terms of withdrawing the given amount: the raw amount
   the user has to transfer to the exchange, the effective amount that
   will be added to the wallet balance after withdrawal fees, the number
   of coins that would be withdrawn, the exchange's bank accounts that
   can receive the transfer (including accounts that require currency
   conversion), age-restriction options and a preview of KYC
   requirements.
 
   The client uses the result to let the user review the withdrawal
   before creating it with :ts:op:`acceptManualWithdrawal`.
 
   **Request:**
 
   The request must be a `GetWithdrawalDetailsForAmountRequest` object.
 
   **Response:**
 
   On success, the result is a `WithdrawalDetailsForAmount` object.
 
   **Side effects:**
 
   May refresh the exchange's key material over the network, validates
   withdrawal denominations and stores the verification results in the
   database, and queries the bank conversion service for accounts that
   require currency conversion.  No transaction is created.
 
   **Expected errors:**
 
   The caller can handle the following errors inline:
   ``WALLET_EXCHANGE_ENTRY_NOT_FOUND``,
   ``WALLET_EXCHANGE_TOS_NOT_ACCEPTED``, ``GENERIC_CURRENCY_MISMATCH``.
 
   **Details:**
 
   The exchange is selected with ``exchangeBaseUrl``.  When it is
   omitted, ``restrictScope`` names a currency scope and the wallet's
   preferred exchange for that scope is used instead.
 
   When ``transactionId`` refers to a prepared bank-integrated
   withdrawal, the sender account of that withdrawal is taken into
   account when evaluating account-specific withdrawal rules (KYC).
 
   An ``unconfirmedKeyChange`` in the result means the exchange changed
   its key set and the user has not confirmed the change yet; accepting
   the withdrawal will be refused until the change is confirmed with
   :ts:op:`confirmExchangeKeyChange`, so this is the point at which to
   warn the user.
 
 .. ts:def:: GetWithdrawalDetailsForAmountRequest
 
   interface GetWithdrawalDetailsForAmountRequest {
     exchangeBaseUrl?: string;
 
     // Prepared bank-integrated withdrawal whose sender account should
     // be checked.
     transactionId?: TransactionIdStr;
 
     // Specify currency scope for the withdrawal.
     // May only be used when exchangeBaseUrl is not specified.
     restrictScope?: ScopeInfo;
 
     amount: AmountString;
 
     restrictAge?: number;
 
     progressToken?: string;
   }
 
 .. ts:def:: WithdrawalDetailsForAmount
 
   interface WithdrawalDetailsForAmount extends WithdrawalKycPreview {
     // Exchange base URL for the withdrawal.
     exchangeBaseUrl: string;
 
     // Amount that the user will transfer to the exchange.
     amountRaw: AmountString;
 
     // Amount that will be added to the user's wallet balance.
     amountEffective: AmountString;
 
     // Number of coins that would be used for withdrawal.
     // UIs should warn if this number is too high (roughly at >100).
     numCoins: number;
 
     // Ways to pay the exchange, including accounts that require
     // currency conversion.
     withdrawalAccountsList: WithdrawalExchangeAccountDetails[];
 
     // If the exchange supports age-restricted coins it will return
     // the array of ages.
     ageRestrictionOptions?: number[];
 
     // Scope info of the currency withdrawn.
     scopeInfo: ScopeInfo;
 
     // Set when the exchange changed its key set and the user has not
     // confirmed the change.  Accepting the withdrawal will be refused
     // until they do, so this is the point at which to warn them.
     unconfirmedKeyChange?: ExchangeKeyChangeInfo;
 
     // KYC soft limit.
     // Withdrawals over that amount will require KYC.
     kycSoftLimit?: AmountString;
 
     // KYC hard limit.
     // Withdrawals over that amount will be denied.
     kycHardLimit?: AmountString;
 
     // Ways to pay the exchange.
     // Deprecated in favor of withdrawalAccountsList.
     paytoUris: string[];
   }
 
 .. ts:def:: WithdrawalKycPreview
 
   interface WithdrawalKycPreview {
     // Whether the proposed withdrawal needs a KYC warning based on
     // this wallet's balance, known KYC allowance, advertised
     // zero-limit rules and known withdrawal volume.  This is a
     // preview, not a guarantee that the exchange will not require
     // KYC.  Optional for compatibility with older wallet-core
     // versions, which omit it.
     kycRequired?: boolean;
 
     // Balance usage from the same evaluation as kycRequired.
     balanceKyc?: BalanceKycUsage;
 
     // Account-specific withdrawal-rule preview using this wallet's
     // history.  "ok" only covers exposed rules and available local
     // history; "unknown" means account limits could not be evaluated
     // and must not be shown as clearance.  Older wallet-core versions
     // omit this field.
     withdrawalKycStatus?: WithdrawalKycStatus;
   }
 
 .. ts:def:: BalanceKycUsage
 
   // This wallet's balance at the issuing exchange at preview time,
   // using the same accounting as balance-KYC enforcement (including
   // pending refresh outputs).  Does not reserve capacity for
   // concurrent withdrawals or report account-wide
   // transaction-volume/hard-limit usage.
   interface BalanceKycUsage {
     currentBalance: AmountString;
 
     // Current balance plus the selected coins' value after withdrawal
     // fees.
     projectedBalance: AmountString;
 
     // Applicable balance threshold; omitted when no finite limit is
     // known.
     threshold?: AmountString;
 
     // Additional balance permitted, clamped to zero; omitted with
     // threshold.
     remaining?: AmountString;
   }
 
 .. ts:def:: WithdrawalKycStatus
 
   type WithdrawalKycStatus =
     | "unknown"
     | "ok"
     | "kyc-required"
     | "hard-limit";
 
 .. ts:def:: WithdrawalExchangeAccountDetails
 
   interface WithdrawalExchangeAccountDetails {
     // Payto URI of the exchange.  Depending on whether the (manual!)
     // withdrawal is accepted or just being checked, this already
     // includes the subject with the reserve public key.
     paytoUri: string;
 
     // Whether the account can be used by the user to send funds for a
     // withdrawal.  "ok": account should be shown to the user;
     // "error": account should not be shown to the user, UIs might
     // render the error (in conversionError), especially in dev mode.
     status: "ok" | "error";
 
     // Transfer amount.  Might be in a different currency than the
     // requested amount for withdrawal.  Absent if this is a
     // conversion account and the conversion failed.
     transferAmount?: AmountString;
 
     // Currency specification for the external currency.
     // Only included if this account requires a currency conversion.
     currencySpecification?: CurrencySpecification;
 
     // Further restrictions for sending money to the exchange.
     creditRestrictions?: AccountRestriction[];
 
     // Label given to the account or the account's bank by the
     // exchange.
     bankLabel?: string;
 
     // Display priority assigned to this bank account by the exchange.
     priority?: number;
 
     // Error that happened when attempting to request the conversion
     // rate.
     conversionError?: TalerErrorDetail;
 
     // Timestamp that indicates when the transfer options expire.
     // If missing, options do not expire.
     transferExpiry?: TalerProtocolTimestamp;
 
     // Options for transferring funds to the exchange for the
     // withdrawal.
     transferOptions: TransferOption[];
   }
 
 .. ts:def:: TransferOption
 
   type TransferOption =
     | TransferOptionPayto
     | TransferOptionUri
     | TransferOptionSwissQrBill;
 
 .. ts:def:: TransferOptionPayto
 
   interface TransferOptionPayto {
     type: "payto";
     paytoUri: string;
     qrCodes: QrCodeSpec[];
   }
 
 .. ts:def:: TransferOptionUri
 
   interface TransferOptionUri {
     type: "uri";
     uri: string;
   }
 
 .. ts:def:: TransferOptionSwissQrBill
 
   interface TransferOptionSwissQrBill {
     type: "ch-qr-bill";
     paytoUri: string;
     qrReferenceNumber: string;
     qrCodes: QrCodeSpec[];
   }