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