14.79. DD 79: Notifications#

14.79.1. Summary#

Provide a way for merchants to be periodically sent reports about payments without requiring them to open the merchant backend in a browser.

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).

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.

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.

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.

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)

None.

(This should be filled in with results from discussions on mailing lists / personal communication.)