commit 1a9fedc207ac97ccb6a545b65104e301619ebb42
parent a4059c3e0cc0b5ff1f38175521b5a06a6a0c0d6f
Author: Christian Grothoff <grothoff@gnunet.org>
Date: Mon, 19 Jan 2026 11:47:39 +0100
vTEMPLATE is also v25
Diffstat:
| M | core/api-merchant.rst | | | 92 | ++++++++++++++++++++++++++++++++++++++++++------------------------------------- |
1 file changed, 49 insertions(+), 43 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -40,13 +40,11 @@ Android PoS app is currently targeting **v20**.
* ``v23``: Added various defaults, fields and some new filters
* ``v24``: Make minor changes to refund semantics
* ``v25``: adds features to group amounts internally (say to
- separate tips, taxes and revenue in reporting) and endpoints
- for periodic report generation
+ separate tips, taxes and revenue in reporting), endpoints
+ for periodic report generation and inventory-based templates
**Upcoming versions:**
-* ``vTEMPLATE``: adds template types, inventory-backed templates, and tip support
- for template instantiation
* ``vTAXES``: adds features to manage taxes
* ``vPAIVANA``: adds features for templates to support session-based payments
* ``vKYCLP``: new long-polling for KYC
@@ -2847,7 +2845,7 @@ Decimal quantities
// Fixed-point decimal string in the form "<integer>[.<fraction>]".
// Fractional part has up to six digits.
// "-1" is only valid for fields that explicitly allow "infinity".
- // Since protocol **vUNIT**; used in template selection since **vTEMPLATE**.
+ // Since protocol **vUNIT**; used in template selection since **v25**.
type DecimalQuantity = string;
@@ -3273,7 +3271,7 @@ Adding products to the inventory
// by the frontend.
// Each entry must use a distinct currency.
// Since API version **vUNIT**.
- // Currency uniqueness enforced since protocol **vTEMPLATE**.
+ // Currency uniqueness enforced since protocol **v25**.
unit_price?: Amount[];
// True if the price(s) given are a net prices, false if they are
@@ -3418,7 +3416,7 @@ Adding products to the inventory
// by the frontend.
// Each entry must use a distinct currency.
// Since API version **vUNIT**.
- // Currency uniqueness enforced since protocol **vTEMPLATE**.
+ // Currency uniqueness enforced since protocol **v25**.
unit_price?: Amount[];
// Legacy price field.
@@ -5491,7 +5489,7 @@ Adding templates
interface TemplateContractCommon {
// Template type to apply. Defaults to "fixed-order" if omitted.
// Prescribes which interface has to be followed
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
template_type?: TemplateType;
// Human-readable summary for the template.
@@ -5525,28 +5523,28 @@ Adding templates
interface TemplateContractInventoryCart {
// Inventory-cart: request a tip during instantiation.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
request_tip?: boolean;
// Inventory-cart: allow any inventory item to be selected.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
selected_all?: boolean;
// Inventory-cart: only products in these categories are selectable.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
selected_categories?: Integer[];
// Inventory-cart: only these products are selectable.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
selected_products?: string[];
// Inventory-cart: require exactly one selection entry.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
choose_one?: boolean;
// Inventory-cart: backend-provided payload with selectable data.
// Only present in ``GET /templates/$TEMPLATE_ID`` responses.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
inventory_payload?: InventoryPayload;
}
@@ -5757,7 +5755,7 @@ Using template
:http:statuscode:`200 OK`:
The backend has successfully returned the detailed information about a specific template.
- Returns a `WalletTemplateDetails`.
+ Returns a `WalletTemplateDetailsRequest`.
:http:statuscode:`404 Not found`:
The instance or template(ID) is unknown to the backend.
@@ -5768,9 +5766,17 @@ Using template
categories, and units. The payload is filtered by the template's
``selected_all``, ``selected_categories``, and ``selected_products`` settings.
- .. ts:def:: WalletTemplateDetails
+ .. ts:def:: WalletTemplateDetailsRequest
- interface WalletTemplateDetails {
+ interface WalletTemplateDetailsRequest {
+
+ // Type of the template being instantiated.
+ // Possible values include "fixed-order",
+ // "inventory-cart" and "paivana".
+ // Since protocol **v25**.
+ // Defaults to "fixed-order" while supporting previous
+ // protocol versions.
+ template_type: string;
// Hard-coded information about the contract terms
// for this template.
@@ -5798,15 +5804,15 @@ Using template
interface InventoryPayload {
// Inventory products available for selection.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
products: InventoryPayloadProduct[];
// Categories referenced by the payload products.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
categories: InventoryPayloadCategory[];
// Custom units referenced by the payload products.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
units: InventoryPayloadUnit[];
}
@@ -5814,47 +5820,47 @@ Using template
interface InventoryPayloadProduct {
// Product identifier.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
product_id: string;
// Human-readable product name.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
product_name: string;
// Human-readable product description.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
description: string;
// Localized product descriptions.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
description_i18n?: { [lang_tag: string]: string };
// Unit identifier for the product.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
unit: string;
// Price tiers for the product.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
unit_prices: Amount[];
// Whether fractional quantities are allowed for this unit.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
unit_allow_fraction: boolean;
// Maximum fractional precision (0-6) enforced for this unit.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
unit_precision_level: Integer;
// Category identifiers associated with this product.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
categories: Integer[];
// Taxes applied to the product.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
taxes?: Tax[];
// Hash of the product image (if any).
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
image_hash?: string;
}
@@ -5862,15 +5868,15 @@ Using template
interface InventoryPayloadCategory {
// Category identifier.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
category_id: Integer;
// Human-readable category name.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
category_name: string;
// Localized category names.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
category_name_i18n?: { [lang_tag: string]: string };
}
@@ -5878,31 +5884,31 @@ Using template
interface InventoryPayloadUnit {
// Unit identifier.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
unit: string;
// Human-readable long label.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
unit_name_long: string;
// Localized long labels.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
unit_name_long_i18n?: { [lang_tag: string]: string };
// Human-readable short label.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
unit_name_short: string;
// Localized short labels.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
unit_name_short_i18n?: { [lang_tag: string]: string };
// Whether fractional quantities are allowed for this unit.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
unit_allow_fraction: boolean;
// Maximum fractional precision (0-6) enforced for this unit.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
unit_precision_level: Integer;
}
@@ -5960,11 +5966,11 @@ Using template
// Optional tip amount. Must match the currency of ``amount`` or the
// fixed template currency.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
tip?: Amount;
// Inventory-cart: selected products and quantities.
- // Since protocol **vTEMPLATE**.
+ // Since protocol **v25**.
inventory_selection?: InventorySelectionEntry[];
}
