From bc4c5831a520f8927d0ee003ef50ac4de2c8ebac Mon Sep 17 00:00:00 2001 From: Daniel Scholten Date: Wed, 15 Jul 2026 16:38:58 +0200 Subject: [PATCH 1/4] Added documentation about SEPA matcher --- .../configuration/plugins/analyser-matcher.md | 58 ++++++++++++++++++- 1 file changed, 55 insertions(+), 3 deletions(-) diff --git a/docs/configuration/plugins/analyser-matcher.md b/docs/configuration/plugins/analyser-matcher.md index 04d52e54..cc1f8ce0 100644 --- a/docs/configuration/plugins/analyser-matcher.md +++ b/docs/configuration/plugins/analyser-matcher.md @@ -1203,12 +1203,64 @@ identified by an analyser: ## SEPA Matcher Plugin -You can see example configurations in the configuration database. +This plugin is for SEPA DD transactions. It creates suggestions to match a +transaction to an already existing contribution in CiviCRM. It evaluates the +magic field `sepa_mandate` and looks up if there is a SepaMandate with the +corresponding reference. For OOFF transactions, it identifies the contribution +by matching the SepaMandate reference. For recurring transactions, it also +evaluates the magic field `sepa_batch` (if present) to identify the +contribution. If `sepa_batch` is not set, it tries to identify the contribution +by it's field `receive_date`. All contribution are considered, which have a +`receive_date` not too different from the transactions `value_date`. This may +leed to several matching contributions, which makes the plugin to log a warning +and use only one contribution to create one suggestion. + +A typical value for `sepa_mandate` would be `SEPA-1-RCUR-2026-RW85J34H14Z`, +which is the reference of a CiviCRM SepaMandate. A typical value for +`sepa_batch` would be `TXG-1-OOFF-2026-07-16`, which is the reference of the +CiviCRM SEPA group (also displayed as it's name). You can see example configurations in the configuration database. -> [!NOTE] -> This section is yet to be completed. +Below is a list of config parameters: + +| Configuration Parameter | Type | Default | Description | +|------------------------------|--------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------| +| `threshold` | float: `0` - `1.0` | `0.5` | | +| `received_date_minimum` | string | `"-10 days"` | Only consider contributions with a `receive_date` greater or equal to (the transactions `value_date` plus `received_date_minimum`) | +| `received_date_maximum` | string | `"+10 days"` | Only consider contributions with a `receive_date` smaller or equal to (the transactions `value_date` plus `received_date_maximum`). | + | `deviation_penalty` | float | `0.1` | This penalty is added to the overall penalty, if the transaction's amount doesn't match the contribution's amount. The penalty is also added, if the contribution's status does not match the status `In Progress`. The penalty is also added, if the corresponding contact is marked as deleted. | +| `cancellation_enabled` | boolean: `true` or `false` | `false` | If set to `true`, the plugin will create cancellation suggestions for transactions with negative amount. | +| `cancelled_contribution_status_id` | | | | +| `cancellation_general_penalty` | float | `0.0` | This penalty is applied to all cancellation suggestions. | +| `cancellation_update_mandate_status_OOFF` | string | `"INVALID"` | | +| `cancellation_update_mandate_status_RCUR` | | | | +| `cancellation_default_reason` | string | `"Unspecified SEPA cancellation"` | | +| `cancellation_date_minimum` | string | `"-10 days"` | Only consider contributions with a `receive_date` greater or equal to (the transactions `value_date` plus `cancellation_date_minimum`). Only applies to cancellation suggestions (used instead of `received_date_minimum`). | +| `cancellation_date_maximum` | string | `"+30 days"` | Only consider contributions with a `receive_date` smaller or equal to (the transactions `value_date` plus `cancellation_date_maximum`). Only applies to cancellation suggestions (used instead of `received_date_maximum`). | +| `cancellation_status_penalty` | mapping | `['1' => 0.0, '5' => 0.2]` | Is a mapping of "contribution status id" => "penalty". If status not in list, no suggestion will be generated. (Always) adds a penalty to the suggestion, based on the contribution status. | + | `cancellation_amount_relative_minimum` | float | `1.0` | Used to calculate a penalty, if the transaction amount doesn't match the contribution amount. Only applies to cancellation suggestions. | + | `cancellation_amount_relative_maximum` | float | `1.0` | Used to calculate a penalty, if the transaction amount doesn't match the contribution amount. Only applies to cancellation suggestions. | + | `cancellation_amount_absolute_minimum` | float | `1.0` | Used to calculate a penalty, if the transaction amount doesn't match the contribution amount. Only applies to cancellation suggestions. | + | `cancellation_amount_absolute_maximum` | string | `1.0` | Used to calculate a penalty, if the transaction amount doesn't match the contribution amount. Only applies to cancellation suggestions. | + | `cancellation_amount_penalty` | float | value from `deviation_penalty` | Used to calculate a penalty, if the transaction amount doesn't match the contribution amount. Only applies to cancellation suggestions. | + | `cancellation_penalty_threshold` | float | value from `deviation_penalty` | The amount penalty only applies if the calculated penalty is above `cancellation_penalty_threshold`. Only applies to cancellation suggestions. | + | `cancellation_value_propagation` | mapping | value from `value_propagation` | | + | `cancellation_cancel_reason` | boolean: `0` or `1` | `0` | Set to `1` to enabel extended cancellation features. | + | `cancellation_cancel_reason_edit` | boolean: `0` or `1` | `1` | Set to `0` to disable user input. | + | `cancellation_cancel_reason_source` | string | `"cancel_reason"` | | + | `cancellation_cancel_reason_default` | string | `"-10 days"` | `"Unknown"` (translateable string) | + | `cancellation_cancel_fee` | boolean: `0` or `1` | `0` | Set to `1` to enable the extended cancellation feature "fee". | + | `cancellation_cancel_fee_edit` | boolean: `0` or `1` | `1` | Set to `0` to disable user input. | + | `cancellation_cancel_fee_source` | string | `"cancellation_fee` | Name of field to be evaluated for source. | + | `cancellation_cancel_fee_store` | string | `"match.cancel_fee"` | Where to store the calculated fee, for syntax see value_propagation. | + | `cancellation_date_field` | | | | + | `cancellation_create_activity` | boolean: `true` or `false` | `false` | | + | `cancellation_create_activity_type_id` | integer | `37` | | + | `cancellation_create_activity_subject` | string | `"Follow-up SEPA Cancellation"` (translateable string) | | + | `cancellation_create_activity_assignee_id` | | | | + | `cancellation_create_activity_text` | string | `""` (empty string) | | + ## Membership Matcher From 5dea24a665fba9fe0f3869d6cb9e42e348576aea Mon Sep 17 00:00:00 2001 From: Daniel Scholten Date: Thu, 23 Jul 2026 18:05:53 +0200 Subject: [PATCH 2/4] documentation: fix types and make more clear that SepaMandate entities are not from Core --- docs/configuration/plugins/analyser-matcher.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/configuration/plugins/analyser-matcher.md b/docs/configuration/plugins/analyser-matcher.md index cc1f8ce0..b6a60945 100644 --- a/docs/configuration/plugins/analyser-matcher.md +++ b/docs/configuration/plugins/analyser-matcher.md @@ -1205,9 +1205,9 @@ identified by an analyser: This plugin is for SEPA DD transactions. It creates suggestions to match a transaction to an already existing contribution in CiviCRM. It evaluates the -magic field `sepa_mandate` and looks up if there is a SepaMandate with the +magic field `sepa_mandate` and looks up if there is a `SepaMandate` with the corresponding reference. For OOFF transactions, it identifies the contribution -by matching the SepaMandate reference. For recurring transactions, it also +by matching the `SepaMandate` reference. For recurring transactions, it also evaluates the magic field `sepa_batch` (if present) to identify the contribution. If `sepa_batch` is not set, it tries to identify the contribution by it's field `receive_date`. All contribution are considered, which have a @@ -1216,9 +1216,9 @@ leed to several matching contributions, which makes the plugin to log a warning and use only one contribution to create one suggestion. A typical value for `sepa_mandate` would be `SEPA-1-RCUR-2026-RW85J34H14Z`, -which is the reference of a CiviCRM SepaMandate. A typical value for +which is the reference of a `SepaMandate`. A typical value for `sepa_batch` would be `TXG-1-OOFF-2026-07-16`, which is the reference of the -CiviCRM SEPA group (also displayed as it's name). +SEPA group (also displayed as it's name). You can see example configurations in the configuration database. From 4aa31fd79fe1edda9a90fc5380ad4f53976a9aaa Mon Sep 17 00:00:00 2001 From: Daniel Scholten Date: Thu, 23 Jul 2026 18:15:19 +0200 Subject: [PATCH 3/4] documentation for SEPA matcher: typos, correction for some default values, added documentation about value_propagation --- docs/configuration/plugins/analyser-matcher.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/configuration/plugins/analyser-matcher.md b/docs/configuration/plugins/analyser-matcher.md index b6a60945..2c74d0c2 100644 --- a/docs/configuration/plugins/analyser-matcher.md +++ b/docs/configuration/plugins/analyser-matcher.md @@ -1253,14 +1253,14 @@ Below is a list of config parameters: | `cancellation_cancel_fee` | boolean: `0` or `1` | `0` | Set to `1` to enable the extended cancellation feature "fee". | | `cancellation_cancel_fee_edit` | boolean: `0` or `1` | `1` | Set to `0` to disable user input. | | `cancellation_cancel_fee_source` | string | `"cancellation_fee` | Name of field to be evaluated for source. | - | `cancellation_cancel_fee_store` | string | `"match.cancel_fee"` | Where to store the calculated fee, for syntax see value_propagation. | - | `cancellation_date_field` | | | | + | `cancellation_cancel_fee_store` | string | `"match.cancel_fee"` | Where to store the calculated fee, for syntax see `value_propagation`. | + | `cancellation_date_field` | string | `"value_date"` | Field containing the cancellation date. The correct value would be `"booking_date"`. Though to keep previous behavior this defaults to`"value_date"`. | | `cancellation_create_activity` | boolean: `true` or `false` | `false` | | | `cancellation_create_activity_type_id` | integer | `37` | | | `cancellation_create_activity_subject` | string | `"Follow-up SEPA Cancellation"` (translateable string) | | - | `cancellation_create_activity_assignee_id` | | | | - | `cancellation_create_activity_text` | string | `""` (empty string) | | - + | `cancellation_create_activity_assignee_id` | integer | The contact ID of the logged in user | | + | `cancellation_create_activity_text` | string | template from `templates/CRM/Banking/PluginImpl/Matcher/SepaMandate.activity.tpl`| | +| `value_propagation` | JSON object: `{"key": "value"}` | - | Fields which should be copied from the `btx` namespace to the contribution. | ## Membership Matcher From 8521ed808d5108433aa6c68a482f81f0c761c399 Mon Sep 17 00:00:00 2001 From: Daniel Scholten Date: Fri, 24 Jul 2026 10:44:15 +0200 Subject: [PATCH 4/4] documentation SEPA-Matcher: added dependency on CiviSEPA --- docs/configuration/plugins/analyser-matcher.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/configuration/plugins/analyser-matcher.md b/docs/configuration/plugins/analyser-matcher.md index 2c74d0c2..f562df52 100644 --- a/docs/configuration/plugins/analyser-matcher.md +++ b/docs/configuration/plugins/analyser-matcher.md @@ -1203,7 +1203,9 @@ identified by an analyser: ## SEPA Matcher Plugin -This plugin is for SEPA DD transactions. It creates suggestions to match a +This plugin is for SEPA DD transactions. It depends on the CiviCRM extension +[CiviSEPA](https://docs.civicrm.org/civisepa/en/latest/). It creates suggestions +to match a transaction to an already existing contribution in CiviCRM. It evaluates the magic field `sepa_mandate` and looks up if there is a `SepaMandate` with the corresponding reference. For OOFF transactions, it identifies the contribution