taler-docs

confirm-pay.rst (13880B)

---

 .. ts:op:: confirmPay
 
   Confirm a payment that was previously prepared with
   :ts:op:`preparePayForUriV2`, :ts:op:`preparePayForTemplateV2` or
   :ts:op:`preparePayForPaivana`.
 
   The wallet selects the coins (and, for a contract v1 order, the
   tokens) for the payment and submits it to the merchant.  For a
   contract v1 order, ``choiceIndex`` must refer to one of the choices
   returned by :ts:op:`getChoicesForPayment`.
 
   **Request:**
 
     The ``args`` must be a `ConfirmPayRequest` object.
 
   **Response:**
 
     On success, the result is a `ConfirmPayResult` object.
 
   **Side effects:**
 
     Confirms the prepared payment: the wallet spends the coins and
     submits the payment to the merchant over the network.
 
   **Expected errors:**
 
     The caller can handle the following errors inline:
     ``WALLET_PAY_MERCHANT_INSUFFICIENT_BALANCE``,
     ``WALLET_TRANSACTION_NOT_FOUND``,
     ``WALLET_REQUEST_TRANSACTION_STATE_UNSUPPORTED``,
     ``WALLET_CORE_API_BAD_REQUEST``.
 
   **Details:**
 
     Unless ``noWait`` is set, the operation waits for the first
     payment result: when the payment succeeded, the result has type
     ``done``; when the payment could not be completed (yet), the
     result has type ``pending`` and carries the last error of the
     payment.  With ``noWait``, the operation returns a ``pending``
     result immediately and the payment status is communicated via
     notifications.
 
     The ``WALLET_PAY_MERCHANT_INSUFFICIENT_BALANCE`` error carries
     ``insufficientBalanceDetails`` of type
     `PaymentInsufficientBalanceDetails` in its error detail.
 
 .. ts:def:: PaymentInsufficientBalanceDetails
 
   // Detailed reason for why the wallet's balance is insufficient.
   //
   // Current wallet-core versions emit all structured fields.  The
   // legacy-only alternative lets clients continue decoding responses
   // from older cores without allowing partially populated structured
   // diagnostics.
   type PaymentInsufficientBalanceDetails =
     PaymentInsufficientBalanceCompatibilityDetails &
       (PaymentInsufficientBalanceStructuredDetails
        | PaymentInsufficientBalanceLegacyOnly);
 
 .. ts:def:: PaymentInsufficientBalanceStructuredDetails
 
   // Structured explanation emitted by current wallet-core versions.
   interface PaymentInsufficientBalanceStructuredDetails {
     // Balance in the requested sender scope before payment
     // restrictions.
     balance: CoinSelectionBalanceSnapshot;
 
     // Maximum contribution attainable under the failed request's
     // actual restrictions and fee policy.  For peer payments this is
     // the maximum at one exchange, since peer payments cannot combine
     // exchanges.
     maximumPayableAmount: AmountString;
 
     // Operation-wide reasons, in deterministic evaluation order.
     reasons: CoinSelectionFailureReason[];
 
     // Detailed analysis for every same-currency exchange known to
     // the wallet.
     exchanges: Record<string, CoinSelectionExchangeFailureDiagnostics>;
   }
 
 .. ts:def:: CoinSelectionBalanceSnapshot
 
   // Balance amounts before age, receiver, wire and fee restrictions.
   interface CoinSelectionBalanceSnapshot {
     // Balance that the wallet believes it can spend immediately.
     material: AmountString;
 
     // Expected effective output of unfinished refresh operations.
     pendingRefresh: AmountString;
 
     // Material balance plus pending refresh output.
     available: AmountString;
   }
 
 .. ts:def:: CoinSelectionExchangeFailureDiagnostics
 
   interface CoinSelectionExchangeFailureDiagnostics {
     // Balance held at this exchange before payment restrictions.
     balance: CoinSelectionBalanceSnapshot;
 
     // Maximum contribution selectable from this exchange for
     // this request.
     maximumPayableAmount: AmountString;
 
     // Exchange-local reasons, in deterministic evaluation order.
     reasons: CoinSelectionFailureReason[];
   }
 
 .. ts:def:: PaymentInsufficientBalanceCompatibilityDetails
 
   // Request context and compatibility fields shared by old and current
   // insufficient-balance responses.  Fields marked as deprecated are
   // compatibility-only and planned for removal after consumers migrate.
   interface PaymentInsufficientBalanceCompatibilityDetails {
     // Amount requested by the merchant.
     amountRequested: AmountString;
 
     // Wire method for the requested payment, only applicable
     // for merchant payments.
     wireMethod?: string | undefined;
 
     // Hint as to why the balance is insufficient.
     //
     // If this hint is not provided, the balance hints of the
     // individual exchanges should be shown, as the overall reason
     // might be a combination of the reasons for different exchanges.
     //
     // Deprecated: use `reasons`.
     causeHint?: InsufficientBalanceHint;
 
     // Balance of type "available".
     // Deprecated: use `balance.available`.
     balanceAvailable: AmountString;
 
     // Balance of type "material".
     // Deprecated: use `balance.material`.
     balanceMaterial: AmountString;
 
     // Balance of type "age-acceptable".
     // Deprecated: use `reasons` and `exchanges`.
     balanceAgeAcceptable: AmountString;
 
     // Balance of type "receiver-acceptable".
     // Deprecated: use `reasons` and `exchanges`.
     balanceReceiverAcceptable: AmountString;
 
     // Balance of type "receiver-exchange-url-acceptable".
     // Deprecated: use `exchanges[url].reasons`.
     balanceReceiverExchangeUrlAcceptable: AmountString;
 
     // Balance of type "receiver-exchange-pub-acceptable".
     // Deprecated: use `exchanges[url].reasons`.
     balanceReceiverExchangePubAcceptable: AmountString;
 
     // Balance of type "receiver-auditor-url-acceptable".
     // Deprecated: use `exchanges[url].reasons`.
     balanceReceiverAuditorUrlAcceptable: AmountString;
 
     // Balance of type "merchant-depositable".
     // Deprecated: use `maximumPayableAmount` and `reasons`.
     balanceReceiverDepositable: AmountString;
 
     // Deprecated: use `maximumPayableAmount` and `reasons`.
     balanceExchangeDepositable: AmountString;
 
     // Maximum effective amount that the wallet can spend,
     // when all fees are paid by the wallet.
     // Deprecated: use `maximumPayableAmount`.
     maxEffectiveSpendAmount: AmountString;
 
     // Deprecated: use `exchanges`.
     perExchange: {
       [url: string]: {
         // Deprecated: use `exchanges[url].balance.available`.
         balanceAvailable: AmountString;
 
         // Deprecated: use `exchanges[url].balance.material`.
         balanceMaterial: AmountString;
 
         // Deprecated: use `exchanges[url].maximumPayableAmount`
         // and `exchanges[url].reasons`.
         balanceExchangeDepositable: AmountString;
 
         // Deprecated: use `exchanges[url].reasons`.
         balanceAgeAcceptable: AmountString;
 
         // Deprecated: use `exchanges[url].reasons`.
         balanceReceiverAcceptable: AmountString;
 
         // Deprecated: use `exchanges[url].reasons`.
         balanceReceiverExchangeUrlAcceptable: AmountString;
 
         // Deprecated: use `exchanges[url].reasons`.
         balanceReceiverExchangePubAcceptable: AmountString;
 
         // Deprecated: use `exchanges[url].reasons`.
         balanceReceiverAuditorUrlAcceptable: AmountString;
 
         // Deprecated: use `exchanges[url].maximumPayableAmount`.
         balanceReceiverDepositable: AmountString;
 
         // Deprecated: use `exchanges[url].maximumPayableAmount`.
         maxEffectiveSpendAmount: AmountString;
 
         // The exchange master public key configured by the merchant
         // backend differs from the one of the coins stored in
         // the wallet.
         // Deprecated: use the receiver-exchange-master-pub-mismatch
         // reason.
         exchangeMasterPubMismatch: boolean;
 
         // Exchange doesn't have global fees configured for the
         // relevant year, p2p payments aren't possible.
         // Deprecated: use the exchange-global-fees-unavailable reason.
         missingGlobalFees: boolean;
 
         // Hint that UIs should show to explain the insufficient
         // balance.
         // Deprecated: use `exchanges[url].reasons`.
         causeHint?: InsufficientBalanceHint | undefined;
       };
     };
   }
 
 .. ts:def:: PaymentInsufficientBalanceLegacyOnly
 
   // Alternative emitted by older cores: none of the structured
   // fields are present.
   interface PaymentInsufficientBalanceLegacyOnly {
     balance?: undefined;
     maximumPayableAmount?: undefined;
     reasons?: undefined;
     exchanges?: undefined;
   }
 
 .. ts:def:: CoinSelectionFailureReason
 
   // Machine-readable reasons that prevented a requested coin
   // selection.  Unlike `InsufficientBalanceHint`, these values are
   // exhaustive and can be reported together.  Consumers must branch
   // on the discriminator instead of assuming that the first entry
   // is the only cause.
   type CoinSelectionFailureReason =
     | {
         type: CoinSelectionFailureReasonType.AvailableBalanceInsufficient;
         amountAvailable: AmountString;
       }
     | {
         type: CoinSelectionFailureReasonType.PendingRefresh;
         amountPendingRefresh: AmountString;
       }
     | {
         type: CoinSelectionFailureReasonType.MinimumAge;
         requiredMinimumAge: number;
         amountAgeAcceptable: AmountString;
       }
     | {
         type: CoinSelectionFailureReasonType.ScopeRestricted;
         scopeInfo: ScopeInfo;
       }
     | { type: CoinSelectionFailureReasonType.ReceiverNotAccepted }
     | {
         type: CoinSelectionFailureReasonType.ReceiverExchangeMasterPubMismatch;
         walletMasterPub: string;
         receiverMasterPubs: string[];
       }
     | {
         type: CoinSelectionFailureReasonType.WireMethodUnsupported;
         wireMethod: string;
       }
     | {
         type: CoinSelectionFailureReasonType.WireFeeUnavailable;
         wireMethod: string;
       }
     | {
         type: CoinSelectionFailureReasonType.DepositAccountRestricted;
         wireMethod: string;
         accountRestrictions: Record<string, AccountRestriction[]>;
       }
     | { type: CoinSelectionFailureReasonType.ExchangeGlobalFeesUnavailable }
     | {
         type: CoinSelectionFailureReasonType.FeesNotCovered;
         maximumPayableAmount: AmountString;
       }
     | {
         type: CoinSelectionFailureReasonType.BalanceFragmented;
         combinedMaximumPayableAmount: AmountString;
       }
     | {
         type: CoinSelectionFailureReasonType.SupersededExchangeMasterPub;
         amountAffected: AmountString;
       }
     | { type: CoinSelectionFailureReasonType.SelectionFailed };
 
 .. ts:def:: CoinSelectionFailureReasonType
 
   type CoinSelectionFailureReasonType =
     | "available-balance-insufficient"
     | "pending-refresh"
     | "minimum-age"
     | "scope-restricted"
     | "receiver-not-accepted"
     | "receiver-exchange-master-pub-mismatch"
     | "wire-method-unsupported"
     | "wire-fee-unavailable"
     | "deposit-account-restricted"
     | "exchange-global-fees-unavailable"
     | "fees-not-covered"
     | "balance-fragmented"
     | "superseded-exchange-master-pub"
     | "selection-failed";
 
 .. ts:def:: InsufficientBalanceHint
 
   // Deprecated: use `CoinSelectionFailureReason` instead.
   type InsufficientBalanceHint =
     // Merchant doesn't accept money from exchange(s) that the
     // wallet supports.
     | "merchant-accept-insufficient"
     // Merchant accepts funds from a matching exchange, but the funds
     // can't be deposited with the wire method.
     | "merchant-deposit-insufficient"
     // While in principle the balance is sufficient, the age
     // restriction on coins causes the spendable balance to be
     // insufficient.
     | "age-restricted"
     // Wallet has enough available funds, but the material funds are
     // insufficient.  Usually because there is a pending refresh
     // operation.
     | "wallet-balance-material-insufficient"
     // The wallet simply doesn't have enough available funds.
     | "wallet-balance-available-insufficient"
     // Exchange is missing the global fee configuration, thus fees are
     // unknown and funds from this exchange can't be used for p2p
     // payments.
     | "exchange-missing-global-fees"
     // Even though the balance looks sufficient for the instructed
     // amount, the fees can be covered by neither the merchant nor
     // the remaining wallet balance.
     | "fees-not-covered";
 
 .. ts:def:: ConfirmPayRequest
 
   interface ConfirmPayRequest {
     // Transaction identifier of the prepared payment.
     transactionId: TransactionIdStr;
 
     // Request that a donation receipt for this payment is collected
     // via the configured donau, if the selected choice offers a
     // matching tax-receipt output.
     useDonau?: boolean;
 
     // Session ID override for the payment.
     sessionId?: string;
 
     // Currently ignored by wallet-core.
     forcedCoinSel?: ForcedCoinSel;
 
     // Legacy compatibility option for v1 orders.  Ignored: tokens can
     // only be spent at their issuing merchant, even when this is true.
     forcedTokenSel?: boolean;
 
     // Only applies to v1 orders.
     choiceIndex?: number;
 
     // Do not wait for the first payment success or error
     // before returning a response.  Instead, status will
     // be communicated via notifications.
     //
     // Will become the default in future versions.
     noWait?: boolean;
   }
 
 .. ts:def:: ConfirmPayResult
 
   // Result for confirmPay.
   type ConfirmPayResult = ConfirmPayResultDone | ConfirmPayResultPending;
 
 .. ts:def:: ConfirmPayResultDone
 
   interface ConfirmPayResultDone {
     type: ConfirmPayResultType.Done;
     contractTerms: MerchantContractTermsV0;
     transactionId: TransactionIdStr;
   }
 
 .. ts:def:: ConfirmPayResultPending
 
   interface ConfirmPayResultPending {
     type: ConfirmPayResultType.Pending;
     transactionId: TransactionIdStr;
     lastError?: TalerErrorDetail | undefined;
   }
 
 .. ts:def:: ConfirmPayResultType
 
   type ConfirmPayResultType = "done" | "pending";