You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
(\*) If you didn’t save them when you installed Magento 2, this command will ask for your Magento authentication keys (https://devdocs.magento.com/guides/v2.3/install-gde/prereq/connect-auth.html).
43
+
(\*) If you didn’t save them when you installed Magento 2, this command will ask for your Magento authentication keys (https://experienceleague.adobe.com/en/docs/commerce-operations/installation-guide/prerequisites/authentication-keys).
41
44
Login = Public Key
42
45
Password = Private Key
43
46
@@ -62,16 +65,15 @@ If you get a missing class error message while following the install process:
62
65
[ReflectionException] Class Payplug\Authentication does not exist
63
66
```
64
67
65
-
It’s likely that the Payplug PHP library was not installed along with the Magento module. This will happen if you did not run composer to install the module.
66
-
To fix it, you should require the missing dependency with composer :
68
+
It’s likely that the Payplug PHP library was not installed along with the Magento module.
69
+
This normally never happens when installing through Composer, since the module already
70
+
declares `payplug/payplug-php` and `giggsey/libphonenumber-for-php` (used to normalize the
71
+
customers' phone number) as dependencies. If for any reason they are missing, you can require
72
+
them explicitly:
67
73
68
74
```
69
-
composer require payplug/payplug-php:^3.0
70
-
```
71
-
72
-
You will then need to install another library which we use to normalize the customers' phone number
(\*) To determine which value for `VERSION_YOU_WANT_TO_UPDATE_TO`, you can check out our [last releases](https://github.com/payplug/payplug-magento2/releases)
(\*\*) With the languages option, you can define for which language you want to generate your static content. Languages should be separated with a space.
Starting with **version 4.3.0**, the Payplug module for Magento introduces an **asynchronous** workflow that runs **in parallel** with the standard (immediate) payment flow. This addition ensures that orders are updated automatically when payment confirmations are delayed by the bank or by Payplug, preventing them from getting stuck in “payment review.”
3
+
The Payplug module relies on Magento's cron for **two distinct asynchronous mechanisms**, both of which are required for the module to work correctly:
4
+
5
+
1.**Order status reconciliation** (from **v4.3.0**) — runs in the **`payplug`** cron group. It ensures that orders are updated automatically when payment confirmations are delayed by the bank or by Payplug, preventing them from getting stuck in “payment review.”
6
+
2.**Message queue consumers** for **invoice creation and refunds** — triggered by Magento's native `consumers_runner` job, which lives in the **`default`** cron group. See [Message Queue Consumers (invoices & refunds)](#message-queue-consumers-invoices--refunds) below.
7
+
8
+
> ⚠️ **Both the `default` and the `payplug` cron groups must run.** Enabling only `payplug` reconciles order statuses but leaves invoices and refunds unprocessed.
9
+
>
10
+
> **Note:** The **`default`** cron group is not a Payplug-specific requirement — it is a prerequisite of *any* Magento installation. Magento's cron (the `default` group among others) already powers core features such as asynchronous order confirmation emails, reindexing, stock/inventory maintenance and admin grid updates. On a correctly configured store it is therefore **already running**. Before adding a dedicated crontab entry, first verify that it is actually being executed (see [Verifying Cron Execution and Logs](#verifying-cron-execution-and-logs)); only add one if the `default` group is missing.
4
11
5
12
---
6
13
@@ -17,6 +24,28 @@ As of v4.3.0, Magento leverages **Magento’s cron** to periodically check the p
17
24
18
25
---
19
26
27
+
## Message Queue Consumers (invoices & refunds)
28
+
29
+
Beyond order-status reconciliation, the module creates **invoices** and processes **refunds** asynchronously through Magento's message queue. Two consumers are declared in `etc/queue_consumer.xml` (both on the MySQL `db` connection):
30
+
31
+
| Topic | Consumer | Handler | Purpose |
32
+
| --- | --- | --- | --- |
33
+
|`payplug.order.invoicing`|`payplug.order.invoicing`|`Payplug\Payments\Service\CreateOrderInvoice::execute`| Creates the invoice for a paid order |
34
+
|`payplug.order.refunding`|`payplug.order.refunding`|`Payplug\Payments\Service\CreateOrderRefund::execute`| Creates the credit memo / refund for an order |
35
+
36
+
When a payment is captured or a refund is received (e.g. via IPN), the module **publishes** a message to the relevant topic instead of processing it inline. The message is then picked up by the corresponding consumer.
37
+
38
+
Because these consumers use the `db` connection, they are executed by Magento's native **`consumers_runner`** cron job, which belongs to the **`default`** cron group (module `Magento_MessageQueue`). In other words:
39
+
40
+
- If the **`default`** cron group does **not** run, published messages pile up in the queue and **no invoice or refund is ever created**, even though payments and order statuses look fine.
41
+
- This is independent from the `payplug` cron group, which only handles `check_order_consistency` and `auto_capture_deferred_payments`.
42
+
43
+
> **Note:**`consumers_runner` behavior can be tuned in `app/etc/env.php` (`cron_run`, `max_messages`, `consumers`, `multiple_processes`). Make sure it is not disabled (`cron_run` must not be set to `false`) and, if the `consumers` allow-list is used, that `payplug.order.invoicing` and `payplug.order.refunding` are not excluded.
44
+
>
45
+
> ⚠️ **Do not configure `multiple_processes` for the Payplug consumers** (`payplug.order.invoicing`, `payplug.order.refunding`). Running several parallel processes for the same consumer can process messages targeting the same order concurrently, leading to race conditions such as duplicated invoices or refunds. Keep these consumers running as a single process.
46
+
47
+
---
48
+
20
49
## Prerequisites
21
50
22
51
1.**Magento’s Cron**
@@ -48,13 +77,19 @@ Some users customize their crontab to run specific cron groups. For example, a c
48
77
***** /usr/local/bin/php /var/www/project/magento/bin/magento cron:run --group=default 2>&1| grep -v "Ran jobs by schedule">> /var/www/project/magento/var/log/magento.cron.log
49
78
```
50
79
51
-
In such cases, **you must add the `payplug` cron group** to your crontab to ensure that the asynchronous order status updates are processed. For example:
80
+
In such cases, **you must make sure that both the `default` and the `payplug` cron groups run**:
81
+
82
+
- The **`default`** group runs Magento's `consumers_runner` job, which processes the invoice and refund message queue consumers (see [Message Queue Consumers](#message-queue-consumers-invoices--refunds)).
83
+
- The **`payplug`** group runs `payplug_payments_check_order_consistency` and `payplug_payments_auto_capture_deferred_payments`.
84
+
85
+
For example:
52
86
53
87
```bash
88
+
***** /usr/local/bin/php /var/www/project/magento/bin/magento cron:run --group=default 2>&1| grep -v "Ran jobs by schedule">> /var/www/project/magento/var/log/magento.cron.log
54
89
***** /usr/local/bin/php /var/www/project/magento/bin/magento cron:run --group=payplug 2>&1| grep -v "Ran jobs by schedule">> /var/www/project/magento/var/log/magento.cron.log
55
90
```
56
91
57
-
This will ensure that the Payplug cron tasks (`payplug_payments_check_order_consistency` and `payplug_payments_auto_capture_deferred_payments`) are executed according to the schedule defined in your `crontab.xml`.
92
+
> ⚠️ Running **only**`--group=payplug` reconciles order statuses but leaves the `default` group's `consumers_runner` unexecuted, so **invoices and refunds will never be created**.
58
93
59
94
## Dynamic Cron Group Execution
60
95
@@ -104,12 +139,13 @@ As an alternative approach, you could dynamically list all cron groups declared
104
139
105
140
## Summary
106
141
107
-
- **Change in v4.3.0**: An asynchronous mechanism now reconciles delayed payment confirmations automatically via the `payplug` cron group.
142
+
- **Order status reconciliation (v4.3.0)**: An asynchronous mechanism reconciles delayed payment confirmations automatically via the `payplug` cron group.
143
+
- **Invoices & refunds**: These are created asynchronously through Magento message queue consumers, executed by the `consumers_runner` job of the **`default`** cron group.
108
144
- **No Impact on Standard Workflow**: Orders still follow the immediate confirmation process when payments are processed quickly.
109
145
- **Required Merchant Action**:
110
-
1. If you use the native Magento cron installation (`bin/magento cron:install`), everything should work automatically.
111
-
2. If you have a custom crontab that runs specific groups, ensure that you add an entry for the **`payplug`** cron group.
112
-
- **Benefit**: This asynchronous flow helps prevent orders from being stuck in “payment review” due to delayed confirmations.
146
+
1. If you use the native Magento cron installation (`bin/magento cron:install`), everything should work automatically (all groups run).
147
+
2. If you have a custom crontab that runs specific groups, ensure that **both** the **`default`** group (invoices/refunds via `consumers_runner`) **and** the **`payplug`** group (status reconciliation & auto-capture) are executed.
148
+
- **Benefit**: This asynchronous flow prevents orders from being stuck in “payment review” and ensures invoices and refunds are processed reliably.
0 commit comments