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 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 confirmExchangeKeyChange, so this is the point at which to warn the user.

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;
}

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[];
}

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;
}

// 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;
}

type WithdrawalKycStatus =
  | "unknown"
  | "ok"
  | "kyc-required"
  | "hard-limit";

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[];
}

type TransferOption =
  | TransferOptionPayto
  | TransferOptionUri
  | TransferOptionSwissQrBill;

interface TransferOptionPayto {
  type: "payto";
  paytoUri: string;
  qrCodes: QrCodeSpec[];
}

interface TransferOptionUri {
  type: "uri";
  uri: string;
}

interface TransferOptionSwissQrBill {
  type: "ch-qr-bill";
  paytoUri: string;
  qrReferenceNumber: string;
  qrCodes: QrCodeSpec[];
}