taler-docs

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

commit 763e3f5469c77e0b21401590143192e2963fb41e
parent ac3c38e8599e8a4c72506fc3af2563fc2cb48a8f
Author: Florian Dold <dold@taler.net>
Date:   Wed,  4 Nov 2026 09:28:39 +0100

wallet API: document payment template balance snapshots

Issue: https://bugs.taler.net/n/11798

Diffstat:
Mcore/wallet-core/payments/check-pay-for-template.rst | 28++++++++++++++++++++++++++--
Mwallet/wallet-core.md | 20++++++++++++++++++++
2 files changed, 46 insertions(+), 2 deletions(-)

diff --git a/core/wallet-core/payments/check-pay-for-template.rst b/core/wallet-core/payments/check-pay-for-template.rst @@ -6,8 +6,9 @@ Fetches the template details from the merchant, applies the overrides encoded in the URI (such as amount or summary), and returns the template details together with the currencies supported by the - merchant. This allows the client to present the editable template - fields to the user before calling :ts:op:`preparePayForTemplateV2`. + merchant and scoped wallet balance snapshots. This allows the client + to present the editable template fields to the user before calling + :ts:op:`preparePayForTemplateV2`. **Request:** @@ -34,6 +35,23 @@ by the merchant backend (a `WalletTemplateDetailsResponse` of the merchant API), with the URI overrides already applied. + ``availableBalances`` is returned for all template types, including + fixed and editable amounts. It includes wallet balances whose scope + currency appears in ``supportedCurrencies``, preserving the scopes + and ordering from :ts:op:`getBalances`. Known zero balances are + included; an empty array means there are no matching balance entries. + No scopes are synthesized. + + ``amountAvailable`` uses the same semantics as ``getBalances.available``, + including expected pending refresh outputs. It is not a guaranteed + maximum payment amount or proof of merchant acceptance. Merchant + acceptance, age restrictions, fees and final payment eligibility are + checked during payment preparation. Template currency requirements + still apply, and balances may change after the response. Missing or + empty advisory ``exchange_candidates`` do not suppress balances. + Clients must not use this snapshot as an authoritative affordability + check or exact input limit. + .. ts:def:: CheckPayTemplateRequest interface CheckPayTemplateRequest { @@ -53,4 +71,10 @@ // Currencies supported by the merchant, sorted. supportedCurrencies: string[]; + + // Wallet balance snapshots in backend-supported currencies, per scope. + availableBalances: { + scopeInfo: ScopeInfo; + amountAvailable: AmountString; + }[]; }; diff --git a/wallet/wallet-core.md b/wallet/wallet-core.md @@ -1891,8 +1891,28 @@ export interface CheckPayTemplateRequest { export type CheckPayTemplateReponse = { templateDetails: WalletTemplateDetailsResponse; supportedCurrencies: string[]; + availableBalances: { + scopeInfo: ScopeInfo; + amountAvailable: AmountString; + }[]; }; ``` + +`availableBalances` is always returned, for fixed and editable amounts and all +template types. It contains wallet balance snapshots for scopes whose currency +appears in `supportedCurrencies`, preserving the scopes and ordering from +`getBalances`. Known zero balances are included; an empty array means there are +no matching wallet balance entries. No scopes are synthesized. + +`amountAvailable` has the same meaning as `getBalances.available`, including +expected outputs from pending refreshes. It is not a guaranteed maximum payment +amount or proof that the merchant accepts these funds. Merchant acceptance, age +restrictions, fees and final payment eligibility are checked during payment +preparation. Template currency requirements still apply, and balances may change +after the response. Missing or empty advisory `exchange_candidates` do not +suppress wallet balances. Clients must not use this snapshot as an authoritative +affordability check or exact input limit. + ```{ts:def} WalletTemplateDetailsResponse export interface WalletTemplateDetailsResponse { template_contract: TemplateContractDetails;