commit bf92fe936b548f40a9128529e7303dd33eb5cea3
parent 1a9fedc207ac97ccb6a545b65104e301619ebb42
Author: Christian Grothoff <grothoff@gnunet.org>
Date: Tue, 20 Jan 2026 07:48:40 +0100
improve Paivana spec: template needs to specify price(s)
Diffstat:
| M | core/api-merchant.rst | | | 134 | ++++++++++++++++++++++++++++++++++++++----------------------------------------- |
1 file changed, 65 insertions(+), 69 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -5495,37 +5495,45 @@ Adding templates
// Human-readable summary for the template.
summary?: string;
+ // Required currency for payments to the template.
+ // This parameter is optional and should not be present
+ // if "amount" is given.
+ currency?: string;
+
// The time the customer need to pay before his order will be deleted.
// It is deleted if the customer did not pay and if the duration is over.
pay_duration: RelativeTime;
+
+ // Minimum age buyer must have (in years). Default is 0.
+ minimum_age: Integer;
+
+ // Inventory-cart: request a tip during instantiation.
+ // Since protocol **v25**.
+ request_tip?: boolean;
+ }
+
+ .. ts:def:: TemplateType
+
+ enum TemplateType {
+ FIXED_ORDER = "fixed-order",
+ INVENTORY_CART = "inventory-cart",
+ PAIVANA = "paivana"
}
.. ts:def:: TemplateContractFixedOrder
interface TemplateContractFixedOrder {
- // Required currency for payments to the template.
- // The user may specify any amount, but it must be
- // in this currency.
- // This parameter is optional and should not be present
- // if "amount" is given.
- currency?: string;
// The price is imposed by the merchant and cannot be changed by the customer.
// This parameter is optional.
amount?: Amount;
- // Minimum age buyer must have (in years). Default is 0.
- minimum_age: Integer;
}
.. ts:def:: TemplateContractInventoryCart
interface TemplateContractInventoryCart {
- // Inventory-cart: request a tip during instantiation.
- // Since protocol **v25**.
- request_tip?: boolean;
-
// Inventory-cart: allow any inventory item to be selected.
// Since protocol **v25**.
selected_all?: boolean;
@@ -5552,33 +5560,15 @@ Adding templates
interface TemplateContractPaivana {
- // Required currency for payments to the template.
- // The user may specify any amount, but it must be
- // in this currency.
- // This parameter is optional and should not be present
- // if "amount" is given.
- currency?: string;
-
- // The price is imposed by the merchant and cannot be changed by the customer.
- // This parameter is optional.
- amount?: Amount;
-
- // Minimum age buyer must have (in years). Default is 0.
- minimum_age: Integer;
-
- // Paivana: identifier of the session or campaign.
+ // Regular expression over URLs for which
+ // this template is valid.
+ // Optional, if not given all URLs are accepted.
// Since protocol **vPAIVANA**.
- paivana_id?: string;
- }
-
- .. ts:def:: TemplateType
-
- enum TemplateType {
- FIXED_ORDER = "fixed-order",
- INVENTORY_CART = "inventory-cart",
- PAIVANA = "paivana"
- }
+ website_regex?: string;
+ // Methods to pay for the contract.
+ choices: OrderChoice[];
+ }
Editing templates
@@ -5921,7 +5911,6 @@ Using template
**Request:**
The request must be a `UsingTemplateDetailsRequest` and we accept JSON application and URL encoded.
-
**Response:**
@@ -5930,38 +5919,27 @@ Using template
**Details:**
- FIXME: This is not the correct style of doing it. We should
- use a union type (|) and include a field (template_type)
- to make it explicit which of the structures is being used
- (even if the backend knows what to expect, it is better for
- parsers and clarity; make the template_type optional and
- default to "fixed-order" if omitted for backwards-compatibility!)
-
- Based on the template type, provide one of the following request bodies:
-
- 1. For ``fixed-order``, use `UsingTemplateDetailsRequest`.
-
.. ts:def:: UsingTemplateDetailsRequest
- interface UsingTemplateDetailsRequest {
+ type UsingTemplateDetailsRequest = (UsingTemplateFixedOrderRequest | UsingTemplateInventoryCartRequest | UsingTemplatePaivanaRequest) & UsingTemplateCommonRequest;
- // Summary of the template
- summary?: string;
+ .. ts:def:: UsingTemplateCommonRequest
- // The amount entered by the customer.
- amount?: Amount;
- }
+ interface UsingTemplateCommonRequest {
- 2. For ``inventory-cart``, use `UsingTemplateDetailsInventoryRequest`.
-
- .. ts:def:: UsingTemplateDetailsInventoryRequest
-
- interface UsingTemplateDetailsInventoryRequest {
+ // 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;
- // Summary of the template
+ // Summary to use in the contract. Only if
+ // not already specified by the template.
summary?: string;
- // The amount entered by the customer.
+ // The amount to be paid, including tip.
amount?: Amount;
// Optional tip amount. Must match the currency of ``amount`` or the
@@ -5969,6 +5947,20 @@ Using template
// Since protocol **v25**.
tip?: Amount;
+ }
+
+ .. ts:def:: UsingTemplateFixedOrderRequest
+
+ interface UsingTemplateFixedOrderRequest {
+ template_type: "fixed-order";
+
+ }
+
+ .. ts:def:: UsingTemplateInventoryCartRequest
+
+ interface UsingTemplateInventoryCartRequest {
+ template_type: "inventory-cart";
+
// Inventory-cart: selected products and quantities.
// Since protocol **v25**.
inventory_selection?: InventorySelectionEntry[];
@@ -5984,17 +5976,21 @@ Using template
quantity: DecimalQuantity;
}
- 3. For ``paivana``, use `UsingTemplateDetailsPaivana`.
+ .. ts:def:: UsingTemplatePaivanaRequest
- .. ts:def:: UsingTemplateDetailsPaivana
+ interface UsingTemplatePaivanaRequest {
+ template_type: "paivana";
- interface UsingTemplateDetailsPaivana {
+ // URL of the Paivana-protected website to be
+ // accessed. Will become the fulfillment URL in
+ // the contract.
+ website: string;
- // Summary of the template
- summary?: string;
+ // Client Paivana ID to grant access to.
+ // This becomes the "session_id" for session-based
+ // access control.
+ paivana_id: string;
- // The amount entered by the customer.
- amount?: Amount;
}
