taler-docs

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

check-pay-for-template.rst (2848B)


      1 .. ts:op:: checkPayForTemplate
      2 
      3   Check a ``taler://pay-template/`` URI without creating a payment
      4   transaction.
      5 
      6   Fetches the template details from the merchant, applies the overrides
      7   encoded in the URI (such as amount or summary), and returns the
      8   template details together with the currencies supported by the
      9   merchant and scoped wallet balance snapshots.  This allows the client
     10   to present the editable template fields to the user before calling
     11   :ts:op:`preparePayForTemplateV2`.
     12 
     13   **Request:**
     14 
     15   The ``args`` must be a `CheckPayTemplateRequest` object.
     16 
     17   **Response:**
     18 
     19   On success, the result is a `CheckPayTemplateReponse` object.
     20 
     21   **Side effects:**
     22 
     23   Fetches the payment template and the merchant's configuration over
     24   the network; does not change wallet state.
     25 
     26   **Expected errors:**
     27 
     28   The caller can handle the following errors inline:
     29   ``WALLET_TALER_URI_MALFORMED``,
     30   ``WALLET_CONTRACT_TERMS_UNSUPPORTED``.
     31 
     32   **Details:**
     33 
     34   The ``templateDetails`` field is the template information served
     35   by the merchant backend (a `WalletTemplateDetailsResponse` of the
     36   merchant API), with the URI overrides already applied.
     37 
     38   ``availableBalances`` is returned for all template types, including
     39   fixed and editable amounts. It includes wallet balances whose scope
     40   currency appears in ``supportedCurrencies``, preserving the scopes
     41   and ordering from :ts:op:`getBalances`. Known zero balances are
     42   included; an empty array means there are no matching balance entries.
     43   No scopes are synthesized.
     44 
     45   ``amountAvailable`` uses the same semantics as ``getBalances.available``,
     46   including expected pending refresh outputs. It is not a guaranteed
     47   maximum payment amount or proof of merchant acceptance. Merchant
     48   acceptance, age restrictions, fees and final payment eligibility are
     49   checked during payment preparation. Template currency requirements
     50   still apply, and balances may change after the response. Missing or
     51   empty advisory ``exchange_candidates`` do not suppress balances.
     52   Clients must not use this snapshot as an authoritative affordability
     53   check or exact input limit.
     54 
     55 .. ts:def:: CheckPayTemplateRequest
     56 
     57   interface CheckPayTemplateRequest {
     58     // The taler://pay-template/ URI to check.
     59     talerPayTemplateUri: string;
     60 
     61     // Enables progress correlation and cancellation through
     62     // cancelProgressToken.
     63     progressToken?: string;
     64   }
     65 
     66 .. ts:def:: CheckPayTemplateReponse
     67 
     68   type CheckPayTemplateReponse = {
     69     // Template details served by the merchant backend.
     70     templateDetails: WalletTemplateDetailsResponse;
     71 
     72     // Currencies supported by the merchant, sorted.
     73     supportedCurrencies: string[];
     74 
     75     // Wallet balance snapshots in backend-supported currencies, per scope.
     76     availableBalances: {
     77       scopeInfo: ScopeInfo;
     78       amountAvailable: AmountString;
     79     }[];
     80   };