commit e1231e04f0570f913115c92a0efae1052f0cb886
parent e8edb1a8944c8abbcc14202e49cc3de75823672a
Author: Christian Grothoff <christian@grothoff.org>
Date: Fri, 26 Dec 2025 07:53:03 +0100
better name
Diffstat:
5 files changed, 340 insertions(+), 116 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -5248,8 +5248,11 @@ Using template
Webhooks
--------
-The webhook is a backend feature that is used to send a confirmation to the merchant. It can be send with a SMS, email or with another method. It will confirm that the
-customer paid the merchant. It will show the date and the price the customer paid. For details on setup and supported event payloads, see the
+The webhook is a backend feature that is used to trigger an HTTP request
+to some business logic of the merchant in real-time whenever a specified
+type of event happens. Depending on the type of the event, webhooks
+may include additional meta-data, such as the amount or contract paid
+by the customer. For details on setup and supported event payloads, see the
`Merchant manual – Setting up a webhook <https://docs.taler.net/taler-merchant-manual.html#setting-up-a-webhook>`_.
Each webhook is bound to an ``event_type``. The backend currently recognizes the following types, which are mirrored in the ``WebhookEventType`` enum so API clients can
@@ -5475,6 +5478,225 @@ Removing webhook
The webhook(ID) or the instance is unknown to the backend.
+-------------
+Notifications
+-------------
+
+Notifications are a backend feature that is used to send periodic
+reports to the merchant. Notifications are sent using notification
+helper programs which must be configured for each merchant backend.
+
+
+
+Adding notifications
+^^^^^^^^^^^^^^^^^^^^
+
+.. http:post:: [/instances/$INSTANCES]/private/notifications
+
+ This is used to create a notification.
+
+ **Required permission:** ``notifications-write``
+
+ **Request:**
+
+ The request must be a `NotificationAddRequest`.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The backend has successfully added a new notification. Returns a `NotificationAddedResponse`.
+
+ :http:statuscode:`404 Not found`:
+ The merchant instance is unknown.
+
+ **Details:**
+
+ .. ts:def:: NotificationAddRequest
+
+ interface NotificationAddRequest {
+
+ // Description of the notification. Possibly included
+ // in the notification message.
+ description: string;
+
+ // Merchant backend configuration section specifying
+ // the program to use to transmit the notification
+ program_section: string;
+
+ // Mime-type to request from the data source.
+ mime_type: string;
+
+ // Base URL to request the data from.
+ data_source: string;
+
+ // Address where the notification program should send
+ // the notification.
+ target_address: string;
+
+ // Notification frequency
+ notification_frequency: RelativeTime;
+
+ // Notification frequency shift
+ notification_frequency_shift: Integer;
+
+ }
+
+ .. ts:def:: NotificationAddedResponse
+
+ interface NotificationAddedResponse {
+
+ // Unique ID for the notification.
+ notification_serial_id: Integer;
+
+ }
+
+
+Editing webhooks
+^^^^^^^^^^^^^^^^
+
+.. http:patch:: [/instances/$INSTANCES]/private/webhooks/$WEBHOOK_ID
+
+ This is used to update a webhook.
+
+ **Required permission:** ``webhooks-write``
+
+ **Request:**
+
+ The request must be a `WebhookPatchDetails`.
+
+ **Response:**
+
+ :http:statuscode:`204 No content`:
+ The webhook has successfully modified.
+ :http:statuscode:`404 Not found`:
+ The webhook(ID) is unknown to the backend.
+ :http:statuscode:`409 Conflict`:
+ The provided information is inconsistent with the current state of the webhook. Changes made is the same with another store.
+
+ **Details:**
+
+ .. ts:def:: WebhookPatchDetails
+
+ interface WebhookPatchDetails {
+
+ // The event of the webhook: why the webhook is used.
+ event_type: WebhookEventType;
+
+ // URL of the webhook where the customer will be redirected.
+ url: string;
+
+ // Method used by the webhook
+ http_method: string;
+
+ // Header template of the webhook
+ header_template?: string;
+
+ // Body template by the webhook
+ body_template?: string;
+
+ }
+
+
+
+Inspecting webhook
+^^^^^^^^^^^^^^^^^^
+
+.. http:get:: [/instances/$INSTANCES]/private/webhooks
+
+ This is used to return all the webhooks that are present in our backend.
+
+ **Required permission:** ``webhooks-read``
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The backend has successfully returned all the webhooks. Returns a `WebhookSummaryResponse`.
+
+ :http:statuscode:`404 Not found`:
+ The backend has does not know about the instance.
+
+ **Details:**
+
+ .. ts:def:: WebhookSummaryResponse
+
+ interface WebhookSummaryResponse {
+
+ // Return webhooks that are present in our backend.
+ webhooks: WebhookEntry[];
+
+ }
+
+ The `WebhookEntry` object describes a webhook. It has the following structure:
+
+ .. ts:def:: WebhookEntry
+
+ interface WebhookEntry {
+
+ // Webhook identifier, as found in the webhook.
+ webhook_id: string;
+
+ // The event of the webhook: why the webhook is used.
+ event_type: WebhookEventType;
+
+ }
+
+
+.. http:get:: [/instances/$INSTANCES]/private/webhooks/$WEBHOOK_ID
+
+ This is used to obtain detailed information about apecific template.
+
+ **Required permission:** ``webhooks-read``
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The backend has successfully returned the detailed information about a specific webhook. Returns a `WebhookDetails`.
+
+ :http:statuscode:`404 Not found`:
+ The webhook(ID) is unknown to the backend.
+
+ **Details:**
+
+ .. ts:def:: WebhookDetails
+
+ interface WebhookDetails {
+
+ // The event of the webhook: why the webhook is used.
+ event_type: WebhookEventType;
+
+ // URL of the webhook where the customer will be redirected.
+ url: string;
+
+ // Method used by the webhook
+ http_method: string;
+
+ // Header template of the webhook
+ header_template?: string;
+
+ // Body template by the webhook
+ body_template?: string;
+
+ }
+
+
+Removing webhook
+^^^^^^^^^^^^^^^^
+
+.. http:delete:: [/instances/$INSTANCES]/private/webhooks/$WEBHOOK_ID
+
+ This is used to delete information about a webhook.
+
+ **Required permission:** ``webhooks-write``
+
+ **Response:**
+
+ :http:statuscode:`204 No content`:
+ The backend has successfully deleted the webhook.
+
+ :http:statuscode:`404 Not found`:
+ The webhook(ID) or the instance is unknown to the backend.
+
+
----------------------------------------
Token Families: Subscriptions, Discounts
diff --git a/design-documents/078-taxes.rst b/design-documents/078-taxes.rst
@@ -62,9 +62,9 @@ same way for accounting and tax purposes, avoiding the need to
configure each product individually.
There can only be one group per product, all products that are not explicitly
-in a group should be in some "default" group that always exists. The product
-groups will be used for sales statistics (revenue per group) and will be the
-basis for associating taxes with products in the next phase(s).
+in a group should be in some ``__default__`` group that always exists. The
+product groups will be used for sales statistics (revenue per group) and will
+be the basis for associating taxes with products in the next phase(s).
Unlike categories, product group membership is mutually exclusive and not used
for the point-of-sale app display. Re-using categories would confuse a feature
@@ -75,6 +75,7 @@ for taxes/accounting with a feature for user-interfaces of sales people.
(0) product group serial number
(1) instance ID (foreign key)
(2) product group name (unique with instance ID)
+ (3) product group description
* Expand ``inventory_products`` table with:
@@ -110,9 +111,10 @@ statistics.
(0) money pot serial number
(1) instance ID (foreign key)
(2) money pot name (unique with instance ID)
- (3) money pot total amount
+ (3) money pot description
+ (4) money pot total amount
-* Add a trigger to update statistics whenever the money pot
+* Code should update statistics whenever the money pot
total amount is incremented.
diff --git a/design-documents/079-notifications.rst b/design-documents/079-notifications.rst
@@ -1,108 +0,0 @@
-DD 79: Notifications
-####################
-
-Summary
-=======
-
-Provide a way for merchants to be periodically sent
-reports about payments without requiring them to open
-the merchant backend in a browser.
-
-Motivation
-==========
-
-* We had merchants say that receiving e-mails with
- transaction statistics is a "MUST" requirement for them
- (see #10803).
-* We had banks say that sending merchants reports on
- transaction amounts and especially transaction fees is
- a legal requirement for them to be able to say that the
- merchant accepted the fees (see #9361).
-
-Requirements
-============
-
-* Frequencies differ, daily, weekly, monthly, quarterly, yearly
- are all frequencies we have already been told as desirable.
-* In some cases, an offset is desired, like every day at 3am
- to ensure business concluded around midnight is included in the
- "daily" report received in the morning.
-* The reports should include statistics grouped by "category".
- We are right now interpreting "category" as "tax classes", and
- thus should report the statistics with the sale amounts in
- each tax category and the respective amount of taxes due in
- each category, and the payment fees that were charged ---
- and the total number of transactions made.
-* We want this to be reasonably generic, so probably best to
- immediately plan for E-mail, SMS and other transmission mechanisms.
- So we should use a helper-program for the actual transmission.
-* The target e-mail may not be the public e-mail address associated
- with the instance.
-* Multiple alerts at different frequencies and different content
- may apply to the same instance.
-
-
-Proposed Solution
-=================
-
-* Do a "GET" request to some endpoint of the
- instance to generate the PDF/CSV/TEXT/HTML and then pass that
- on to the helper program instead of re-implementing the main
- reporting logic. This way, the configuration would just
- pick the endpoint (and content-type), which is quite flexible.
-* Add new "notifications" or "alerts" table with
- (0) serial, (1) instance, (2) name, (3) frequency,
- (4) time offset, (5) address type, (6) address,
- (7) mime-type of the data to send, (7) URL
- path (below /instance/$ID) to request the data from,
- (8) next-transmission timestamp, (9) last error (EC),
- (10) last error detail (text).
-* Define helper programs in the configuration for each supported
- address type that deal with the transmission of the notification.
-* Expose supported notification address types in /config.
-* Add CRUD API to manipulate notification list.
-* Implement helper program that scans the notifications table,
- requests the data and invokes the helper program for
- transmission and possibly stores/clears errors.
-
-Test Plan
-=========
-
-* Shell-script based tests for the new CRUD API.
-* Shell-script based tests for notifications using
- a "cat"-based helper that writes to a local file.
-* Manual tests for SPA.
-* Manual tests for PDF/CSV/etc. generation.
-
-
-Definition of Done
-==================
-
-* Specification updated
-* Database updated
-* Merchant backend updated:
-
- * CRUD API for notification definitions
- * INI-based configuration for reporting helper programs
- * New background process for creating notifications
- * New endpoints for generating reports (#9361)
-
-* Merchant backend SPA updated:
-
- * CRUD for notification definitions
- * Statistics (?) page with links to various
- GET pages that generate (PDF, CSV) reports (#10487)
-
-
-Alternatives
-============
-
-None.
-
-Drawbacks
-=========
-
-Discussion / Q&A
-================
-
-(This should be filled in with results from discussions on mailing lists / personal communication.)
diff --git a/design-documents/079-reports.rst b/design-documents/079-reports.rst
@@ -0,0 +1,108 @@
+DD 79: Reports
+##############
+
+Summary
+=======
+
+Provide a way for merchants to be periodically sent
+reports about payments without requiring them to open
+the merchant backend in a browser.
+
+Motivation
+==========
+
+* We had merchants say that receiving e-mails with
+ transaction statistics is a "MUST" requirement for them
+ (see #10803).
+* We had banks say that sending merchants reports on
+ transaction amounts and especially transaction fees is
+ a legal requirement for them to be able to say that the
+ merchant accepted the fees (see #9361).
+
+Requirements
+============
+
+* Frequencies differ, daily, weekly, monthly, quarterly, yearly
+ are all frequencies we have already been told as desirable.
+* In some cases, an offset is desired, like every day at 3am
+ to ensure business concluded around midnight is included in the
+ "daily" report received in the morning.
+* The reports should include statistics grouped by "category".
+ We are right now interpreting "category" as "tax classes", and
+ thus should report the statistics with the sale amounts in
+ each tax category and the respective amount of taxes due in
+ each category, and the payment fees that were charged ---
+ and the total number of transactions made.
+* We want this to be reasonably generic, so probably best to
+ immediately plan for E-mail, SMS and other transmission mechanisms.
+ So we should use a helper-program for the actual transmission.
+* The target e-mail may not be the public e-mail address associated
+ with the instance.
+* Multiple alerts at different frequencies and different content
+ may apply to the same instance.
+
+
+Proposed Solution
+=================
+
+* Do a "GET" request to some endpoint of the
+ instance to generate the PDF/CSV/TEXT/HTML and then pass that
+ on to the helper program instead of re-implementing the main
+ reporting logic. This way, the configuration would just
+ pick the endpoint (and content-type), which is quite flexible.
+* Add new "reports" or "alerts" table with
+ (0) serial, (1) instance, (2) name, (3) frequency,
+ (4) time offset, (5) address type, (6) address,
+ (7) mime-type of the data to send, (7) URL
+ path (below /instance/$ID) to request the data from,
+ (8) next-transmission timestamp, (9) last error (EC),
+ (10) last error detail (text).
+* Define helper programs in the configuration for each supported
+ address type that deal with the transmission of the report.
+* Expose supported report address types in /config.
+* Add CRUD API to manipulate report list.
+* Implement helper program that scans the reports table,
+ requests the data and invokes the helper program for
+ transmission and possibly stores/clears errors.
+
+Test Plan
+=========
+
+* Shell-script based tests for the new CRUD API.
+* Shell-script based tests for reports using
+ a "cat"-based helper that writes to a local file.
+* Manual tests for SPA.
+* Manual tests for PDF/CSV/etc. generation.
+
+
+Definition of Done
+==================
+
+* Specification updated
+* Database updated
+* Merchant backend updated:
+
+ * CRUD API for report definitions
+ * INI-based configuration for reporting helper programs
+ * New background process for creating reports
+ * New endpoints for generating reports (#9361)
+
+* Merchant backend SPA updated:
+
+ * CRUD for report definitions
+ * Statistics (?) page with links to various
+ GET pages that generate (PDF, CSV) reports (#10487)
+
+
+Alternatives
+============
+
+None.
+
+Drawbacks
+=========
+
+Discussion / Q&A
+================
+
+(This should be filled in with results from discussions on mailing lists / personal communication.)
diff --git a/design-documents/index.rst b/design-documents/index.rst
@@ -90,5 +90,5 @@ Design documents that start with "XX" are considered deprecated.
076-paywall-proxy
077-merchant-self-provisioning
078-taxes
- 079-notifications
+ 079-reports
999-template
