fluentcart-developer 2.0.2 → 2.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/README.md +59 -59
  2. package/dist/cards/fluentcart/tools.d.ts.map +1 -1
  3. package/dist/cards/fluentcart/tools.js +184 -18
  4. package/dist/cards/fluentcart/tools.js.map +1 -1
  5. package/dist/skills/fluentcart-developer/.claude-plugin/plugin.json +12 -12
  6. package/dist/skills/fluentcart-developer/.mcp.json +11 -11
  7. package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -32
  8. package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -40
  9. package/dist/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -38
  10. package/dist/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -1355
  11. package/dist/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -266
  12. package/dist/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -855
  13. package/dist/skills/fluentcart-developer/references/action-hooks-orders.md +631 -631
  14. package/dist/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -963
  15. package/dist/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -585
  16. package/dist/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -661
  17. package/dist/skills/fluentcart-developer/references/database-models-query-builder.md +194 -194
  18. package/dist/skills/fluentcart-developer/references/database-models-reference.md +604 -604
  19. package/dist/skills/fluentcart-developer/references/engineering-notes.md +154 -154
  20. package/dist/skills/fluentcart-developer/references/fee-system-guide.md +449 -449
  21. package/dist/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -1202
  22. package/dist/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -1598
  23. package/dist/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -628
  24. package/dist/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -1177
  25. package/dist/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -154
  26. package/dist/skills/fluentcart-developer/references/ghost-product-selling.md +458 -458
  27. package/dist/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -224
  28. package/dist/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -761
  29. package/dist/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -190
  30. package/dist/skills/fluentcart-developer/references/rest-api-customers.md +1121 -1121
  31. package/dist/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -219
  32. package/dist/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -619
  33. package/dist/skills/fluentcart-developer/references/rest-api-files.md +290 -290
  34. package/dist/skills/fluentcart-developer/references/rest-api-integrations.md +324 -324
  35. package/dist/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -321
  36. package/dist/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -200
  37. package/dist/skills/fluentcart-developer/references/rest-api-overview.md +131 -131
  38. package/dist/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -172
  39. package/dist/skills/fluentcart-developer/references/rest-api-reference.md +552 -552
  40. package/dist/skills/fluentcart-developer/references/rest-api-reports.md +377 -377
  41. package/dist/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -147
  42. package/dist/skills/fluentcart-developer/references/rest-api-settings.md +528 -528
  43. package/dist/skills/fluentcart-developer/references/rest-api-shipping.md +799 -799
  44. package/dist/skills/fluentcart-developer/references/rest-api-tax.md +356 -356
  45. package/dist/skills/fluentcart-developer/references/subscription-customization.md +197 -197
  46. package/dist/skills/fluentcart-developer/scripts/cli.js +1 -1
  47. package/dist/version.d.ts +1 -1
  48. package/dist/version.js +1 -1
  49. package/package.json +65 -65
  50. package/dist/skills/fluentcart-developer/references/client-integration-contract.md +0 -299
  51. package/dist/skills/fluentcart-developer/references/device-licensing-and-hardware-tracking.md +0 -241
  52. package/dist/skills/fluentcart-developer/references/trial-abuse-prevention.md +0 -304
@@ -1,963 +1,963 @@
1
- # Action Hooks: Payments & Integrations
2
-
3
- All hooks related to payment processing, payment gateway webhooks, third-party integrations, file storage drivers, and development logging. Many of these hooks provide Order, Customer, and OrderTransaction model instances.
4
-
5
- ---
6
-
7
- ## Payment Events
8
-
9
- ### `payment_{$paymentStatus}`
10
- `fluent_cart/payment_{$paymentStatus}` — Fires after order creation when a transaction succeeds
11
-
12
- * **When it runs:** This dynamic action fires during Order finalization, after the transaction has been recorded and the payment status is determined. It only fires when the transaction status is one of the recognized success statuses (e.g. `paid`, `pending`). The `{$paymentStatus}` portion is replaced with the order's actual payment status.
13
- * **Available dynamic variants:**
14
- - `fluent_cart/payment_paid` -- payment completed successfully
15
- - `fluent_cart/payment_pending` -- payment is pending confirmation
16
- * **Source:** `api/Resource/OrderResource.php`
17
-
18
- #### Parameters:
19
- `$data` *(array)*: Order, Customer, and OrderTransaction data
20
- ```php
21
- $data = [
22
- 'order' => $order, // \FluentCart\App\Models\Order instance
23
- 'customer' => $customer, // \FluentCart\App\Models\Customer (via $order->customer)
24
- 'transaction' => $transaction, // \FluentCart\App\Models\OrderTransaction (via $order->latest_transaction)
25
- ];
26
- ```
27
-
28
- #### Usage Example:
29
- ```php
30
- // Hook into successful payment for any order creation
31
- add_action('fluent_cart/payment_paid', function ($data) {
32
- // Extract order and customer models from event data
33
- $order = $data['order'];
34
- $customer = $data['customer'];
35
-
36
- // Grant access after successful payment
37
- update_user_meta($customer->user_id, 'has_premium_access', true);
38
-
39
- // Log successful payment event
40
- fluent_cart_add_log(
41
- 'Payment Received',
42
- 'Order #' . $order->id . ' paid successfully.',
43
- 'success'
44
- );
45
- }, 10, 1);
46
- ```
47
-
48
- ---
49
-
50
- ### `payment_{$transactionType}_{$paymentStatus}`
51
- `fluent_cart/payment_{$transactionType}_{$paymentStatus}` — Fires after order creation with both transaction type and payment status
52
-
53
- * **When it runs:** This dynamic action fires immediately after `fluent_cart/payment_{$paymentStatus}` during Order finalization. It provides more granular filtering by combining the transaction type (e.g. `one_time`, `subscription`) with the payment status (e.g. `paid`, `pending`).
54
- * **Available dynamic variants:**
55
- - `fluent_cart/payment_one_time_paid` -- one-time purchase paid
56
- - `fluent_cart/payment_subscription_paid` -- subscription payment paid
57
- - `fluent_cart/payment_one_time_pending` -- one-time purchase pending
58
- - `fluent_cart/payment_subscription_pending` -- subscription payment pending
59
- * **Source:** `api/Resource/OrderResource.php`
60
-
61
- #### Parameters:
62
- `$data` *(array)*: Order, customer, and transaction data
63
- ```php
64
- $data = [
65
- 'order' => $order, // \FluentCart\App\Models\Order instance
66
- 'customer' => $customer, // \FluentCart\App\Models\Customer (via $order->customer)
67
- 'transaction' => $transaction, // \FluentCart\App\Models\OrderTransaction (via $order->latest_transaction)
68
- ];
69
- ```
70
-
71
- #### Usage Example:
72
- ```php
73
- // Hook into paid subscription payment events
74
- add_action('fluent_cart/payment_subscription_paid', function ($data) {
75
- // Extract order and transaction models from event data
76
- $order = $data['order'];
77
- $transaction = $data['transaction'];
78
-
79
- // Handle subscription-specific logic after payment
80
- fluent_cart_add_log(
81
- 'Subscription Payment',
82
- 'Subscription payment received for Order #' . $order->id,
83
- 'success'
84
- );
85
- }, 10, 1);
86
- ```
87
-
88
- ---
89
-
90
- ### `after_payment_{$paymentStatus}`
91
- `fluent_cart/payments/after_payment_{$paymentStatus}` — Fires in abstract gateway after payment processing completes
92
-
93
- * **When it runs:** This dynamic action fires inside the abstract payment gateway base class after a payment has been processed, the `OrderTransaction` recorded, and the `Order` status updated. It runs after `changeOrderStatus()` and any automatic digital-product completion logic. The `{$paymentStatus}` is the resulting payment status (e.g. `paid`, `failed`).
94
- * **Source:** `app/Modules/PaymentMethods/Core/AbstractPaymentGateway.php`
95
-
96
- #### Parameters:
97
- `$data` *(array)*: The order that was just processed
98
- ```php
99
- $data = [
100
- 'order' => $order, // \FluentCart\App\Models\Order instance with updated status
101
- ];
102
- ```
103
-
104
- #### Usage Example:
105
- ```php
106
- // Hook after any payment gateway completes payment processing
107
- add_action('fluent_cart/payments/after_payment_paid', function ($data) {
108
- // Extract order model instance
109
- $order = $data['order'];
110
-
111
- // Trigger external fulfillment webhook after payment confirmation
112
- wp_remote_post('https://fulfillment.example.com/api/orders', [
113
- 'body' => wp_json_encode([
114
- 'order_id' => $order->id,
115
- 'total' => $order->total_amount,
116
- ]),
117
- ]);
118
- }, 10, 1);
119
- ```
120
-
121
- ---
122
-
123
- ### `payment_success`
124
- `fluent_cart/payment_success` — Fires when an Airwallex or Square payment succeeds
125
-
126
- * **When it runs:** This action fires inside the Airwallex and Square gateway handlers when a payment intent or payment object is confirmed as successful. The order status is updated to `processing` and payment status to `paid` before this hook runs.
127
- * **Source:** `app/Modules/PaymentMethods/AirwallexGateway/Airwallex.php`, `app/Modules/PaymentMethods/SquareGateway/Square.php`
128
-
129
- #### Parameters:
130
- `$data` *(array)*: The order and payment intent/payment data
131
- ```php
132
- $data = [
133
- 'order' => $order, // \FluentCart\App\Models\Order with updated status
134
- 'payment_intent' => $paymentIntent, // Gateway-specific payment intent or payment object (array)
135
- ];
136
- ```
137
-
138
- #### Usage Example:
139
- ```php
140
- // Hook when Airwallex or Square payment succeeds
141
- add_action('fluent_cart/payment_success', function ($data) {
142
- // Extract order and payment intent payload
143
- $order = $data['order'];
144
- $paymentIntent = $data['payment_intent'];
145
-
146
- // Log the gateway-specific payment reference ID
147
- fluent_cart_add_log(
148
- 'Gateway Payment Success',
149
- 'Payment intent ' . $paymentIntent['id'] . ' for Order #' . $order->id,
150
- 'success'
151
- );
152
- }, 10, 1);
153
- ```
154
-
155
- ---
156
-
157
- ### `payment_failed`
158
- `fluent_cart/payment_failed` — Fires when an Airwallex payment fails
159
-
160
- * **When it runs:** This action fires inside the Airwallex gateway handler when a payment intent is determined to have failed. The order status and payment status are both set to `failed` before this hook runs.
161
- * **Source:** `app/Modules/PaymentMethods/AirwallexGateway/Airwallex.php`
162
-
163
- #### Parameters:
164
- `$data` *(array)*: The order and failed payment intent data
165
- ```php
166
- $data = [
167
- 'order' => $order, // \FluentCart\App\Models\Order with failed status
168
- 'payment_intent' => $paymentIntent, // Airwallex payment intent object (array)
169
- ];
170
- ```
171
-
172
- #### Usage Example:
173
- ```php
174
- // Hook when an Airwallex payment fails
175
- add_action('fluent_cart/payment_failed', function ($data) {
176
- // Extract order and failed payment intent payload
177
- $order = $data['order'];
178
- $paymentIntent = $data['payment_intent'];
179
-
180
- // Notify admin via email about failed payment
181
- wp_mail(
182
- get_option('admin_email'),
183
- 'Payment Failed - Order #' . $order->id,
184
- 'Airwallex payment intent ' . $paymentIntent['id'] . ' failed.'
185
- );
186
- }, 10, 1);
187
- ```
188
-
189
- ---
190
-
191
- ## Payment Gateway Registration
192
-
193
- ### `register_payment_methods`
194
- `fluent_cart/register_payment_methods` — Register custom payment gateways
195
-
196
- * **When it runs:** This action fires during initialization after all built-in payment gateways (Stripe, PayPal, Razorpay, Paystack, COD, Square, Airwallex) have been registered. Use this hook to register your own custom payment gateway with the gateway manager.
197
- * **Source:** `app/Hooks/Handlers/GlobalPaymentHandler.php`
198
-
199
- #### Parameters:
200
- `$data` *(array)*: Contains the gateway manager instance
201
- ```php
202
- $data = [
203
- 'gatewayManager' => $gateway, // GatewayManager instance for registering gateways
204
- ];
205
- ```
206
-
207
- #### Usage Example:
208
- ```php
209
- // Hook to register custom payment gateways with gateway manager
210
- add_action('fluent_cart/register_payment_methods', function ($data) {
211
- // Extract gateway manager instance
212
- $gatewayManager = $data['gatewayManager'];
213
-
214
- // Register a custom payment gateway class
215
- $gatewayManager->register('my_gateway', new MyCustomPaymentGateway());
216
- }, 10, 1);
217
- ```
218
-
219
- ---
220
-
221
- ### `after_render_payment_method_{$route}`
222
- `fluent-cart/after_render_payment_method_{$route}` — Fires after a payment method UI renders on the checkout page
223
-
224
- * **When it runs:** This action fires after a payment method's frontend UI (logo or radio button) has been rendered on the checkout form. The `{$route}` is the gateway's route identifier. Note that this hook uses a hyphenated prefix (`fluent-cart/`) rather than the usual underscored prefix.
225
- * **Available dynamic variants:** `fluent-cart/after_render_payment_method_stripe`, `fluent-cart/after_render_payment_method_paypal`, `fluent-cart/after_render_payment_method_square`, `fluent-cart/after_render_payment_method_airwallex`, `fluent-cart/after_render_payment_method_offline_payment`, `fluent-cart/after_render_payment_method_razorpay`, `fluent-cart/after_render_payment_method_paystack`
226
- * **Source:** `app/Modules/PaymentMethods/Core/AbstractPaymentGateway.php`
227
-
228
- #### Parameters: None.
229
-
230
- #### Usage Example:
231
- ```php
232
- // Hook after Stripe payment method UI renders on checkout form
233
- add_action('fluent-cart/after_render_payment_method_stripe', function () {
234
- // Output custom security note below Stripe payment option
235
- echo '<p class="payment-note">Secure payments powered by Stripe.</p>';
236
- }, 10, 0);
237
- ```
238
-
239
- ---
240
-
241
- ## Stripe Webhooks
242
-
243
- ### `stripe/webhook_{$eventType}`
244
- `fluent_cart/payments/stripe/webhook_{$eventType}` — Fires for each Stripe webhook event
245
-
246
- * **When it runs:** This dynamic action fires during Stripe webhook (IPN) processing after the event has been verified and the associated Order has been found. The `{$eventType}` is the Stripe event type with dots replaced by underscores (e.g. `invoice.payment_succeeded` becomes `invoice_payment_succeeded`).
247
- * **Available dynamic variants:** `webhook_invoice_payment_succeeded`, `webhook_invoice_payment_failed`, `webhook_charge_refunded`, `webhook_customer_subscription_deleted`, `webhook_customer_subscription_updated`, `webhook_payment_intent_succeeded`, `webhook_payment_intent_payment_failed`
248
- * **Source:** `app/Modules/PaymentMethods/StripeGateway/Webhook/IPN.php`
249
-
250
- #### Parameters:
251
- `$data` *(array)*: The Stripe event object and associated order
252
- ```php
253
- $data = [
254
- 'event' => $event, // Stripe Event object (contains type, data, etc.)
255
- 'order' => $order, // \FluentCart\App\Models\Order instance (may be WP_Error if not found)
256
- ];
257
- ```
258
-
259
- #### Usage Example:
260
- ```php
261
- // Hook into Stripe charge refunded webhook event
262
- add_action('fluent_cart/payments/stripe/webhook_charge_refunded', function ($data) {
263
- // Extract Stripe event object and order model
264
- $event = $data['event'];
265
- $order = $data['order'];
266
-
267
- // Exit early if order lookup failed
268
- if (is_wp_error($order)) {
269
- return;
270
- }
271
-
272
- $charge = $event->data->object;
273
-
274
- // Log custom refund webhook event
275
- fluent_cart_add_log(
276
- 'Stripe Refund Webhook',
277
- 'Charge ' . $charge->id . ' refunded for Order #' . $order->id,
278
- 'info'
279
- );
280
- }, 10, 1);
281
- ```
282
-
283
- ---
284
-
285
- ## PayPal Webhooks
286
-
287
- ### `paypal_webhook_received`
288
- `fluent_cart/paypal_webhook_received` — Fires when raw PayPal webhook data is received before processing
289
-
290
- * **When it runs:** This action fires early in PayPal webhook processing, after the webhook type has been validated against the list of supported events but before any event-specific handling occurs. Use this to log or inspect all incoming PayPal webhook payloads.
291
- * **Source:** `app/Modules/PaymentMethods/PayPalGateway/IPN.php`
292
-
293
- #### Parameters:
294
- `$data` *(array)*: The parsed and raw webhook data
295
- ```php
296
- $data = [
297
- 'data' => $data, // Parsed webhook payload (array)
298
- 'raw' => $post_data, // Raw POST body string
299
- ];
300
- ```
301
-
302
- #### Usage Example:
303
- ```php
304
- // Hook when raw PayPal webhook data is received before processing
305
- add_action('fluent_cart/paypal_webhook_received', function ($data) {
306
- // Log all incoming raw PayPal webhooks for debugging
307
- error_log('PayPal webhook received: ' . wp_json_encode($data['data']));
308
- }, 10, 1);
309
- ```
310
-
311
- ---
312
-
313
- ### `paypal/webhook_subscription_payment_received`
314
- `fluent_cart/payments/paypal/webhook_subscription_payment_received` — Fires when a PayPal recurring subscription payment is received
315
-
316
- * **When it runs:** This action fires when a PayPal `PAYMENT.SALE.COMPLETED` webhook is received and the resource contains a `billing_agreement_id`, indicating it is a recurring subscription payment rather than a one-time purchase.
317
- * **Source:** `app/Modules/PaymentMethods/PayPalGateway/IPN.php`
318
-
319
- #### Parameters:
320
- `$data` *(array)*: The charge resource and billing agreement ID
321
- ```php
322
- $data = [
323
- 'charge' => $resource, // PayPal sale resource object (array)
324
- 'vendor_subscription_id' => $billingAgreementId, // PayPal billing agreement ID (string)
325
- ];
326
- ```
327
-
328
- #### Usage Example:
329
- ```php
330
- // Hook when a PayPal recurring subscription payment is received
331
- add_action('fluent_cart/payments/paypal/webhook_subscription_payment_received', function ($data) {
332
- // Extract PayPal charge resource and billing agreement ID
333
- $charge = $data['charge'];
334
- $billingAgreementId = $data['vendor_subscription_id'];
335
-
336
- // Log recurring payment event
337
- fluent_cart_add_log(
338
- 'PayPal Recurring Payment',
339
- 'Billing agreement ' . $billingAgreementId . ' payment received.',
340
- 'success'
341
- );
342
- }, 10, 1);
343
- ```
344
-
345
- ---
346
-
347
- ### `paypal/webhook_payment_capture_completed`
348
- `fluent_cart/payments/paypal/webhook_payment_capture_completed` — Fires when a PayPal one-time payment capture completes
349
-
350
- * **When it runs:** This action fires when a PayPal `PAYMENT.SALE.COMPLETED` webhook arrives without a billing agreement ID (one-time payment), or when a `PAYMENT.CAPTURE.COMPLETED` event is received. Both indicate a successful one-time payment capture.
351
- * **Source:** `app/Modules/PaymentMethods/PayPalGateway/IPN.php`
352
-
353
- #### Parameters:
354
- `$data` *(array)*: The charge resource from PayPal
355
- ```php
356
- $data = [
357
- 'charge' => $resource, // PayPal capture/sale resource object (array)
358
- ];
359
- ```
360
-
361
- #### Usage Example:
362
- ```php
363
- // Hook when a PayPal one-time payment capture completes
364
- add_action('fluent_cart/payments/paypal/webhook_payment_capture_completed', function ($data) {
365
- // Extract PayPal charge capture resource
366
- $charge = $data['charge'];
367
-
368
- // Handle one-time payment capture confirmation log
369
- fluent_cart_add_log(
370
- 'PayPal Capture Completed',
371
- 'Capture completed for resource: ' . wp_json_encode($charge),
372
- 'success'
373
- );
374
- }, 10, 1);
375
- ```
376
-
377
- ---
378
-
379
- ### `paypal/webhook_payment_sale_refunded`
380
- `fluent_cart/payments/paypal/webhook_payment_sale_refunded` — Fires when a PayPal recurring sale is refunded
381
-
382
- * **When it runs:** This action fires when a PayPal `PAYMENT.SALE.REFUNDED` webhook is received, indicating that a refund has been issued for a recurring/subscription payment sale.
383
- * **Source:** `app/Modules/PaymentMethods/PayPalGateway/IPN.php`
384
-
385
- #### Parameters:
386
- `$data` *(array)*: The refund resource from PayPal
387
- ```php
388
- $data = [
389
- 'refund' => $resource, // PayPal refund resource object (array)
390
- ];
391
- ```
392
-
393
- #### Usage Example:
394
- ```php
395
- // Hook when a PayPal recurring sale is refunded
396
- add_action('fluent_cart/payments/paypal/webhook_payment_sale_refunded', function ($data) {
397
- // Extract PayPal refund resource object
398
- $refund = $data['refund'];
399
-
400
- // Log recurring payment sale refund event
401
- fluent_cart_add_log(
402
- 'PayPal Sale Refund',
403
- 'Recurring payment sale refunded: ' . wp_json_encode($refund),
404
- 'info'
405
- );
406
- }, 10, 1);
407
- ```
408
-
409
- ---
410
-
411
- ### `paypal/webhook_payment_capture_refunded`
412
- `fluent_cart/payments/paypal/webhook_payment_capture_refunded` — Fires when a PayPal one-time payment capture is refunded
413
-
414
- * **When it runs:** This action fires when a PayPal `PAYMENT.CAPTURE.REFUNDED` webhook is received, indicating that a refund has been issued for a one-time payment capture.
415
- * **Source:** `app/Modules/PaymentMethods/PayPalGateway/IPN.php`
416
-
417
- #### Parameters:
418
- `$data` *(array)*: The refund resource from PayPal
419
- ```php
420
- $data = [
421
- 'refund' => $resource, // PayPal refund resource object (array)
422
- ];
423
- ```
424
-
425
- #### Usage Example:
426
- ```php
427
- // Hook when a PayPal one-time payment capture is refunded
428
- add_action('fluent_cart/payments/paypal/webhook_payment_capture_refunded', function ($data) {
429
- // Extract PayPal capture refund resource object
430
- $refund = $data['refund'];
431
-
432
- // Log one-time payment refund event
433
- fluent_cart_add_log(
434
- 'PayPal Capture Refund',
435
- 'One-time payment capture refunded: ' . wp_json_encode($refund),
436
- 'info'
437
- );
438
- }, 10, 1);
439
- ```
440
-
441
- ---
442
-
443
- ### `paypal/webhook_{$eventType}` (disputes)
444
- `fluent_cart/payments/paypal/webhook_{$eventType}` — Fires for PayPal customer dispute events
445
-
446
- * **When it runs:** This dynamic action fires when a PayPal dispute-related webhook is received. The `{$eventType}` is the PayPal event type converted to lowercase with dots replaced by underscores.
447
- * **Available dynamic variants:** `webhook_customer_dispute_created`, `webhook_customer_dispute_updated`, `webhook_customer_dispute_resolved`
448
- * **Source:** `app/Modules/PaymentMethods/PayPalGateway/IPN.php`
449
-
450
- #### Parameters:
451
- `$data` *(array)*: The dispute resource from PayPal
452
- ```php
453
- $data = [
454
- 'dispute' => $resource, // PayPal dispute resource object (array)
455
- ];
456
- ```
457
-
458
- #### Usage Example:
459
- ```php
460
- // Hook when a PayPal customer dispute is created
461
- add_action('fluent_cart/payments/paypal/webhook_customer_dispute_created', function ($data) {
462
- // Extract dispute payload
463
- $dispute = $data['dispute'];
464
-
465
- // Alert admin about a new PayPal customer dispute
466
- wp_mail(
467
- get_option('admin_email'),
468
- 'PayPal Dispute Created',
469
- 'A customer has opened a dispute. Details: ' . wp_json_encode($dispute)
470
- );
471
- }, 10, 1);
472
- ```
473
-
474
- ---
475
-
476
- ## Mollie Webhooks (Pro)
477
-
478
- ### `mollie/webhook_subscription_payment_{$status}` (Pro)
479
- `fluent_cart/payments/mollie/webhook_subscription_payment_{$status}` — Fires for each Mollie subscription payment status change
480
-
481
- * **When it runs:** This dynamic action fires during Mollie webhook (IPN) processing when a subscription payment status is determined. The `{$status}` is replaced with the Mollie payment status (`paid`, `failed`, `expired`, `canceled`).
482
- * **Available dynamic variants:** `webhook_subscription_payment_paid`, `webhook_subscription_payment_failed`, `webhook_subscription_payment_expired`, `webhook_subscription_payment_canceled`
483
- * **Source:** `fluent-cart-pro/app/Modules/PaymentMethods/MollieGateway/Webhook/MollieIPN.php`
484
-
485
- #### Parameters:
486
- * `$molliePayment` *(object)* — The Mollie Payment object from the API
487
- * `$order` *(\FluentCart\App\Models\Order)* — The Order model instance associated with this payment
488
-
489
- #### Usage Example:
490
- ```php
491
- // Hook for successful Mollie subscription payment (Pro)
492
- add_action('fluent_cart/payments/mollie/webhook_subscription_payment_paid', function ($molliePayment, $order) {
493
- // Handle successful Mollie subscription payment log
494
- fluent_cart_add_log(
495
- 'Mollie Subscription Payment',
496
- 'Subscription payment received for Order #' . $order->id . ' (Mollie ID: ' . $molliePayment->id . ')',
497
- 'success'
498
- );
499
- }, 10, 2);
500
- ```
501
-
502
- ---
503
-
504
- ### `mollie/webhook_payment_{$status}` (Pro)
505
- `fluent_cart/payments/mollie/webhook_payment_{$status}` — Fires for each Mollie one-time payment status change
506
-
507
- * **When it runs:** This dynamic action fires during Mollie webhook processing when a one-time (non-subscription) payment status is determined. The `{$status}` is replaced with the Mollie payment status.
508
- * **Available dynamic variants:** `webhook_payment_paid`, `webhook_payment_failed`, `webhook_payment_expired`, `webhook_payment_canceled`
509
- * **Source:** `fluent-cart-pro/app/Modules/PaymentMethods/MollieGateway/Webhook/MollieIPN.php`
510
-
511
- #### Parameters:
512
- * `$molliePayment` *(object)* — The Mollie Payment object from the API
513
- * `$order` *(\FluentCart\App\Models\Order)* — The Order model instance associated with this payment
514
-
515
- #### Usage Example:
516
- ```php
517
- // Hook for successful Mollie one-time payment (Pro)
518
- add_action('fluent_cart/payments/mollie/webhook_payment_paid', function ($molliePayment, $order) {
519
- // Trigger external fulfillment for Mollie order
520
- wp_remote_post('https://fulfillment.example.com/api/orders', [
521
- 'body' => wp_json_encode([
522
- 'order_id' => $order->id,
523
- 'mollie_id' => $molliePayment->id,
524
- 'amount' => $molliePayment->amount->value,
525
- 'currency' => $molliePayment->amount->currency,
526
- ]),
527
- ]);
528
- }, 10, 2);
529
- ```
530
-
531
- ---
532
-
533
- ### `payment_failed` (Mollie) (Pro)
534
- `fluent_cart/payment_failed` — Fires when a Mollie payment fails, is canceled, or expires
535
-
536
- * **When it runs:** This action fires inside the Mollie IPN handler when a payment is determined to have failed, been canceled, or expired. The order status and payment status are updated before this hook runs.
537
- * **Source:** `fluent-cart-pro/app/Modules/PaymentMethods/MollieGateway/Webhook/MollieIPN.php`
538
-
539
- #### Parameters:
540
- `$data` *(array)*: Payment failure data
541
- ```php
542
- $data = [
543
- 'order' => $order, // \FluentCart\App\Models\Order — with updated failed status
544
- 'transaction' => $transactionModel, // \FluentCart\App\Models\OrderTransaction
545
- 'old_payment_status' => $oldStatus, // string — previous payment status
546
- 'new_payment_status' => 'failed', // string — new payment status
547
- 'reason' => $reason, // string — 'failed', 'canceled', or 'expired'
548
- ];
549
- ```
550
-
551
- #### Usage Example:
552
- ```php
553
- // Hook when a Mollie payment fails, is canceled, or expires (Pro)
554
- add_action('fluent_cart/payment_failed', function ($data) {
555
- // Extract order, transaction, and failure reason
556
- $order = $data['order'];
557
- $transaction = $data['transaction'];
558
- $oldStatus = $data['old_payment_status'];
559
- $newStatus = $data['new_payment_status'];
560
- $reason = $data['reason'];
561
-
562
- // Only handle Mollie failures in this callback
563
- if ($order->payment_method !== 'mollie') {
564
- return;
565
- }
566
-
567
- // Send email alert to admin regarding Mollie failure
568
- wp_mail(
569
- get_option('admin_email'),
570
- 'Mollie Payment Failed - Order #' . $order->id,
571
- sprintf(
572
- "Payment for Order #%d has %s.\nPrevious status: %s\nNew status: %s\nTransaction ID: %s",
573
- $order->id,
574
- $reason,
575
- $oldStatus,
576
- $newStatus,
577
- $transaction->id
578
- )
579
- );
580
- }, 10, 1);
581
- ```
582
-
583
- ---
584
-
585
- ## Paddle Webhooks (Pro)
586
-
587
- ### `paddle_webhook_received` (Pro)
588
- `fluent_cart/paddle_webhook_received` — Fires when raw Paddle webhook data is received before processing
589
-
590
- * **When it runs:** This action fires early in Paddle webhook processing, after the event type has been extracted from the payload but before any event-specific handling occurs. Use this to log or inspect all incoming Paddle webhook payloads for debugging purposes.
591
- * **Source:** `fluent-cart-pro/app/Modules/PaymentMethods/PaddleGateway/Webhook/IPN.php`
592
-
593
- #### Parameters:
594
- * `$eventType` *(string)* — The Paddle event type (e.g. `transaction.paid`, `subscription.created`)
595
- * `$data` *(array)* — The parsed webhook payload
596
- * `$raw` *(string)* — The raw POST body string
597
- * `$order` *(\FluentCart\App\Models\Order|null)* — The associated Order model instance, or `null` if not resolved
598
-
599
- #### Usage Example:
600
- ```php
601
- // Hook when raw Paddle webhook data is received before processing (Pro)
602
- add_action('fluent_cart/paddle_webhook_received', function ($eventType, $data, $raw, $order) {
603
- // Log all incoming Paddle webhooks for debugging
604
- fluent_cart_add_log(
605
- 'Paddle Webhook Received',
606
- sprintf(
607
- 'Event: %s | Order: %s | Payload size: %d bytes',
608
- $eventType,
609
- $order ? '#' . $order->id : 'N/A',
610
- strlen($raw)
611
- ),
612
- 'info'
613
- );
614
- }, 10, 4);
615
- ```
616
-
617
- ---
618
-
619
- ### `paddle/webhook_{$eventType}` (Pro)
620
- `fluent_cart/payments/paddle/webhook_{$eventType}` — Fires for each Paddle webhook event
621
-
622
- * **When it runs:** This dynamic action fires during Paddle webhook (IPN) processing after the event has been received and the associated order has been resolved (if applicable). The `{$eventType}` is the Paddle event type with dots replaced by underscores.
623
- * **Available dynamic variants:** `webhook_transaction_paid`, `webhook_transaction_completed`, `webhook_transaction_payment_failed`, `webhook_transaction_refunded`, `webhook_adjustment_created`, `webhook_adjustment_updated`, `webhook_subscription_created`, `webhook_subscription_activated`, `webhook_subscription_updated`, `webhook_subscription_canceled`, `webhook_subscription_paused`, `webhook_subscription_resumed`, `webhook_subscription_past_due`
624
- * **Source:** `fluent-cart-pro/app/Modules/PaymentMethods/PaddleGateway/Webhook/IPN.php`
625
-
626
- #### Parameters:
627
- * `$eventType` *(string)* — The Paddle event type with dots replaced by underscores
628
- * `$data` *(array)* — The parsed webhook payload
629
- * `$raw` *(string)* — The raw POST body string
630
- * `$order` *(\FluentCart\App\Models\Order|null)* — The associated Order model instance, or `null` if not resolved
631
-
632
- #### Usage Example:
633
- ```php
634
- // Hook when a Paddle transaction payment succeeds (Pro)
635
- add_action('fluent_cart/payments/paddle/webhook_transaction_paid', function ($eventType, $data, $raw, $order) {
636
- if (!$order) {
637
- return;
638
- }
639
-
640
- // Handle successful Paddle transaction payment
641
- fluent_cart_add_log(
642
- 'Paddle Transaction Paid',
643
- 'Paddle payment completed for Order #' . $order->id,
644
- 'success'
645
- );
646
- }, 10, 4);
647
-
648
- // Hook when a Paddle subscription is canceled (Pro)
649
- add_action('fluent_cart/payments/paddle/webhook_subscription_canceled', function ($eventType, $data, $raw, $order) {
650
- if (!$order) {
651
- return;
652
- }
653
-
654
- // Alert admin about Paddle subscription cancellation via email
655
- wp_mail(
656
- get_option('admin_email'),
657
- 'Paddle Subscription Canceled - Order #' . $order->id,
658
- 'A Paddle subscription has been canceled. Event data: ' . wp_json_encode($data)
659
- );
660
- }, 10, 4);
661
-
662
- // Hook when a Paddle transaction is refunded (Pro)
663
- add_action('fluent_cart/payments/paddle/webhook_transaction_refunded', function ($eventType, $data, $raw, $order) {
664
- if (!$order) {
665
- return;
666
- }
667
-
668
- // Track Paddle refund event
669
- fluent_cart_add_log(
670
- 'Paddle Refund',
671
- 'Paddle transaction refunded for Order #' . $order->id,
672
- 'warning'
673
- );
674
- }, 10, 4);
675
- ```
676
-
677
- ---
678
-
679
- ## Integrations
680
-
681
- ### `register_integration_action`
682
- `fluent_cart/register_integration_action` — Register custom integration actions during initialization
683
-
684
- * **When it runs:** This action fires during WordPress `init` to allow registration of custom integration actions. Use this hook to register your integration provider so it appears in the FluentCart integration action settings.
685
- * **Source:** `app/Modules/IntegrationActions/GlobalIntegrationActionHandler.php`
686
-
687
- #### Parameters: None.
688
-
689
- #### Usage Example:
690
- ```php
691
- // Hook to register custom integration actions during initialization
692
- add_action('fluent_cart/register_integration_action', function () {
693
- // Register a custom integration action provider via filter
694
- add_filter('fluent_cart/integration/get_global_integration_actions', function ($actions) {
695
- $actions['my_crm'] = [
696
- 'title' => 'My CRM',
697
- 'logo' => plugin_dir_url(__FILE__) . 'logo.png',
698
- 'handler' => 'MyCrmIntegrationHandler',
699
- ];
700
- return $actions;
701
- });
702
- }, 10, 0);
703
- ```
704
-
705
- ---
706
-
707
- ### `authenticate_global_credentials_{$settingsKey}`
708
- `fluent_cart/integration/authenticate_global_credentials_{$settingsKey}` — Verify integration credentials for a specific provider
709
-
710
- * **When it runs:** This dynamic action fires when a user clicks the "Verify" or "Authenticate" button for an integration's global credentials in the FluentCart admin settings. The `{$settingsKey}` is the integration provider's settings key (e.g. `mailchimp`, `activecampaign`).
711
- * **Source:** `app/Modules/Integrations/GlobalIntegrationSettings.php`
712
-
713
- #### Parameters:
714
- `$data` *(array)*: The settings key and integration configuration
715
- ```php
716
- $data = [
717
- 'settings_key' => $settingsKey, // string — Integration provider key
718
- 'integration' => $integration, // array — Integration settings data (unslashed)
719
- ];
720
- ```
721
-
722
- #### Usage Example:
723
- ```php
724
- // Hook to verify integration credentials for a specific provider
725
- add_action('fluent_cart/integration/authenticate_global_credentials_my_crm', function ($data) {
726
- // Extract API key from integration settings payload
727
- $apiKey = $data['integration']['api_key'] ?? '';
728
-
729
- // Verify the API key with the external service endpoint
730
- $response = wp_remote_get('https://api.mycrm.com/verify', [
731
- 'headers' => ['Authorization' => 'Bearer ' . $apiKey],
732
- ]);
733
-
734
- if (is_wp_error($response) || wp_remote_retrieve_response_code($response) !== 200) {
735
- wp_send_json_error(['message' => 'Invalid API credentials.'], 400);
736
- }
737
-
738
- wp_send_json_success(['message' => 'Credentials verified successfully.']);
739
- }, 10, 1);
740
- ```
741
-
742
- ---
743
-
744
- ### `save_global_integration_settings_{$settingsKey}`
745
- `fluent_cart/integration/save_global_integration_settings_{$settingsKey}` — Save integration settings for a specific provider
746
-
747
- * **When it runs:** This dynamic action fires when a user saves the global integration settings for a specific provider. The `{$settingsKey}` is the integration provider's settings key. The handler is expected to persist the settings and send a JSON response.
748
- * **Source:** `app/Modules/Integrations/GlobalIntegrationSettings.php`
749
-
750
- #### Parameters:
751
- `$data` *(array)*: The settings key and integration configuration
752
- ```php
753
- $data = [
754
- 'settings_key' => $settingsKey, // string — Integration provider key
755
- 'integration' => $integration, // array — Integration settings data (unslashed)
756
- ];
757
- ```
758
-
759
- #### Usage Example:
760
- ```php
761
- // Hook to save integration settings for a specific provider
762
- add_action('fluent_cart/integration/save_global_integration_settings_my_crm', function ($data) {
763
- // Extract integration settings array
764
- $settings = $data['integration'];
765
-
766
- // Persist integration settings into FluentCart options
767
- fluent_cart_update_option('my_crm_settings', $settings);
768
-
769
- wp_send_json_success([
770
- 'message' => 'Settings saved successfully.',
771
- ]);
772
- }, 10, 1);
773
- ```
774
-
775
- ---
776
-
777
- ### `integration/chained_{$route}`
778
- `fluent_cart/integration/chained_{$route}` — Fires for chained data requests in cascading dropdowns
779
-
780
- * **When it runs:** This dynamic action fires when the integration settings UI requests chained/dependent data for cascading dropdown fields. For example, after selecting a mailing list, this hook loads the available tags or groups for that list. The `{$route}` is the integration's route identifier.
781
- * **Source:** `app/Modules/Integrations/GlobalIntegrationSettings.php`
782
-
783
- #### Parameters:
784
- `$data` *(array)*: The request data for the chained lookup
785
- ```php
786
- $data = [
787
- 'data' => $requestData, // array — Request data array (contains route, selected values, etc.)
788
- ];
789
- ```
790
-
791
- #### Usage Example:
792
- ```php
793
- // Hook for chained data requests in cascading dropdowns
794
- add_action('fluent_cart/integration/chained_my_crm', function ($data) {
795
- // Extract request data and list ID
796
- $requestData = $data['data'];
797
- $listId = $requestData['list_id'] ?? '';
798
-
799
- // Fetch tags for the selected mailing list
800
- $tags = my_crm_get_tags($listId);
801
-
802
- wp_send_json_success([
803
- 'tags' => $tags,
804
- ]);
805
- }, 10, 1);
806
- ```
807
-
808
- ---
809
-
810
- ### `integration/run/{$provider}`
811
- `fluent_cart/integration/run/{$provider}` — Execute a specific integration feed for a provider
812
-
813
- * **When it runs:** This dynamic action fires when an integration feed needs to be executed for a specific provider, both in real-time (synchronous) and async (via scheduled actions) processing. The `{$provider}` is the integration provider's slug (e.g. `mailchimp`, `activecampaign`).
814
- * **Source:** `app/Listeners/IntegrationEventListener.php`
815
-
816
- #### Parameters:
817
- `$integrationArray` *(array)*: The full integration feed configuration and context
818
- ```php
819
- $integrationArray = [
820
- 'provider' => 'mailchimp', // string — Integration provider slug
821
- 'order' => $order, // \FluentCart\App\Models\Order instance
822
- 'event_data' => $data, // array — Event trigger data (may include subscription)
823
- 'feed' => [], // array — Feed configuration array
824
- ];
825
- ```
826
-
827
- #### Usage Example:
828
- ```php
829
- // Hook to execute a specific integration feed for a provider
830
- add_action('fluent_cart/integration/run/my_crm', function ($integrationArray) {
831
- // Extract order, feed config, and customer model
832
- $order = $integrationArray['order'];
833
- $feed = $integrationArray['feed'] ?? [];
834
- $customer = $order->customer;
835
-
836
- // Push customer data to external CRM via HTTP request
837
- wp_remote_post('https://api.mycrm.com/contacts', [
838
- 'headers' => [
839
- 'Authorization' => 'Bearer ' . fluent_cart_get_option('my_crm_api_key'),
840
- 'Content-Type' => 'application/json',
841
- ],
842
- 'body' => wp_json_encode([
843
- 'email' => $customer->email,
844
- 'name' => $customer->full_name,
845
- 'tags' => $feed['tags'] ?? [],
846
- ]),
847
- ]);
848
- }, 10, 1);
849
- ```
850
-
851
- ---
852
-
853
- ### `global_notify_completed`
854
- `fluent_cart/integrations/global_notify_completed` — Fires after all synchronous global notification feeds have completed
855
-
856
- * **When it runs:** This action fires after all sync (non-async) global notification integration feeds have been processed for an order. It does not fire if there are async feeds still pending.
857
- * **Source:** `app/Modules/Integrations/GlobalNotificationHandler.php`
858
-
859
- #### Parameters:
860
- * `$order` *(\FluentCart\App\Models\Order)* — The Order model instance
861
- * `$feeds` *(array)* — Array of feed configurations that were processed
862
-
863
- #### Usage Example:
864
- ```php
865
- // Hook after all synchronous global notification feeds have completed
866
- add_action('fluent_cart/integrations/global_notify_completed', function ($order, $feeds) {
867
- // Log completion of synchronous integrations for order
868
- fluent_cart_add_log(
869
- 'Integrations Complete',
870
- count($feeds) . ' integration feeds processed for Order #' . $order->id,
871
- 'info'
872
- );
873
- }, 10, 2);
874
- ```
875
-
876
- ---
877
-
878
- ### `reindex_integration_feeds`
879
- `fluent_cart/reindex_integration_feeds` — Fires when integration feeds need to be re-indexed
880
-
881
- * **When it runs:** This action fires after integration feed configurations are saved or updated, both at the global level (via `IntegrationController`) and at the product level (via `ProductIntegrationsController`).
882
- * **Source:** `app/Http/Controllers/IntegrationController.php`, `app/Http/Controllers/ProductIntegrationsController.php`
883
-
884
- #### Parameters:
885
- `$data` *(array)*: Empty array `[]`
886
-
887
- #### Usage Example:
888
- ```php
889
- // Hook when integration feeds need to be re-indexed
890
- add_action('fluent_cart/reindex_integration_feeds', function ($data) {
891
- // Clear cached integration feed transient
892
- delete_transient('my_plugin_integration_cache');
893
- }, 10, 1);
894
- ```
895
-
896
- ---
897
-
898
- ## Storage Drivers
899
-
900
- ### `register_storage_drivers`
901
- `fluent_cart/register_storage_drivers` — Register custom file storage drivers
902
-
903
- * **When it runs:** This action fires during WordPress `init` at priority 9, after the built-in Local and S3 storage drivers have been initialized. Use this hook to register a custom file storage driver (e.g. Google Cloud Storage, Azure Blob Storage) for digital product file delivery.
904
- * **Source:** `app/Hooks/Handlers/GlobalStorageHandler.php`
905
-
906
- #### Parameters: None.
907
-
908
- #### Usage Example:
909
- ```php
910
- // Hook to register custom file storage drivers
911
- add_action('fluent_cart/register_storage_drivers', function () {
912
- // Register custom storage driver via filter
913
- add_filter('fluent_cart/storage_drivers', function ($drivers) {
914
- $drivers['gcs'] = [
915
- 'title' => 'Google Cloud Storage',
916
- 'handler' => new MyGcsStorageDriver(),
917
- ];
918
- return $drivers;
919
- });
920
- }, 10, 0);
921
- ```
922
-
923
- ---
924
-
925
- ## Development Logging
926
-
927
- ### `dev_log`
928
- `fluent_cart/dev_log` — Fires for development and debug logging (requires `FLUENT_CART_DEV_MODE`)
929
-
930
- * **When it runs:** This action fires at various points during payment gateway webhook processing (primarily in the PayPal IPN handler) when the `FLUENT_CART_DEV_MODE` constant is defined. It provides detailed diagnostic data for debugging webhook failures, signature verification issues, and missing transaction references.
931
- * **Source:** `app/Modules/PaymentMethods/PayPalGateway/IPN.php` (multiple call sites)
932
-
933
- #### Parameters:
934
- `$data` *(array)*: Logging context with raw data and metadata
935
- ```php
936
- $data = [
937
- 'raw_data' => $rawData, // mixed — Raw webhook payload or resource data
938
- 'status' => 'failed', // string — Log status: 'failed', 'received', etc.
939
- 'title' => 'Log title', // string — Human-readable log title
940
- 'log_type' => 'webhook', // string — Type of log entry
941
- 'module_type' => 'paypal_ipn', // string — Module identifier
942
- 'module_name' => 'PayPal', // string — Display name of the module
943
- ];
944
- ```
945
-
946
- #### Usage Example:
947
- ```php
948
- // Hook for development and debug logging (requires FLUENT_CART_DEV_MODE)
949
- add_action('fluent_cart/dev_log', function ($data) {
950
- // Format detailed diagnostic log entry string
951
- $logEntry = sprintf(
952
- "[%s] [%s] %s - %s\n%s\n\n",
953
- gmdate('Y-m-d H:i:s'),
954
- $data['status'] ?? 'unknown',
955
- $data['module_name'] ?? 'General',
956
- $data['title'] ?? 'No title',
957
- wp_json_encode($data['raw_data'] ?? [], JSON_PRETTY_PRINT)
958
- );
959
-
960
- // Write diagnostic entry to debug log file
961
- error_log($logEntry, 3, WP_CONTENT_DIR . '/fluent-cart-debug.log');
962
- }, 10, 1);
963
- ```
1
+ # Action Hooks: Payments & Integrations
2
+
3
+ All hooks related to payment processing, payment gateway webhooks, third-party integrations, file storage drivers, and development logging. Many of these hooks provide Order, Customer, and OrderTransaction model instances.
4
+
5
+ ---
6
+
7
+ ## Payment Events
8
+
9
+ ### `payment_{$paymentStatus}`
10
+ `fluent_cart/payment_{$paymentStatus}` — Fires after order creation when a transaction succeeds
11
+
12
+ * **When it runs:** This dynamic action fires during Order finalization, after the transaction has been recorded and the payment status is determined. It only fires when the transaction status is one of the recognized success statuses (e.g. `paid`, `pending`). The `{$paymentStatus}` portion is replaced with the order's actual payment status.
13
+ * **Available dynamic variants:**
14
+ - `fluent_cart/payment_paid` -- payment completed successfully
15
+ - `fluent_cart/payment_pending` -- payment is pending confirmation
16
+ * **Source:** `api/Resource/OrderResource.php`
17
+
18
+ #### Parameters:
19
+ `$data` *(array)*: Order, Customer, and OrderTransaction data
20
+ ```php
21
+ $data = [
22
+ 'order' => $order, // \FluentCart\App\Models\Order instance
23
+ 'customer' => $customer, // \FluentCart\App\Models\Customer (via $order->customer)
24
+ 'transaction' => $transaction, // \FluentCart\App\Models\OrderTransaction (via $order->latest_transaction)
25
+ ];
26
+ ```
27
+
28
+ #### Usage Example:
29
+ ```php
30
+ // Hook into successful payment for any order creation
31
+ add_action('fluent_cart/payment_paid', function ($data) {
32
+ // Extract order and customer models from event data
33
+ $order = $data['order'];
34
+ $customer = $data['customer'];
35
+
36
+ // Grant access after successful payment
37
+ update_user_meta($customer->user_id, 'has_premium_access', true);
38
+
39
+ // Log successful payment event
40
+ fluent_cart_add_log(
41
+ 'Payment Received',
42
+ 'Order #' . $order->id . ' paid successfully.',
43
+ 'success'
44
+ );
45
+ }, 10, 1);
46
+ ```
47
+
48
+ ---
49
+
50
+ ### `payment_{$transactionType}_{$paymentStatus}`
51
+ `fluent_cart/payment_{$transactionType}_{$paymentStatus}` — Fires after order creation with both transaction type and payment status
52
+
53
+ * **When it runs:** This dynamic action fires immediately after `fluent_cart/payment_{$paymentStatus}` during Order finalization. It provides more granular filtering by combining the transaction type (e.g. `one_time`, `subscription`) with the payment status (e.g. `paid`, `pending`).
54
+ * **Available dynamic variants:**
55
+ - `fluent_cart/payment_one_time_paid` -- one-time purchase paid
56
+ - `fluent_cart/payment_subscription_paid` -- subscription payment paid
57
+ - `fluent_cart/payment_one_time_pending` -- one-time purchase pending
58
+ - `fluent_cart/payment_subscription_pending` -- subscription payment pending
59
+ * **Source:** `api/Resource/OrderResource.php`
60
+
61
+ #### Parameters:
62
+ `$data` *(array)*: Order, customer, and transaction data
63
+ ```php
64
+ $data = [
65
+ 'order' => $order, // \FluentCart\App\Models\Order instance
66
+ 'customer' => $customer, // \FluentCart\App\Models\Customer (via $order->customer)
67
+ 'transaction' => $transaction, // \FluentCart\App\Models\OrderTransaction (via $order->latest_transaction)
68
+ ];
69
+ ```
70
+
71
+ #### Usage Example:
72
+ ```php
73
+ // Hook into paid subscription payment events
74
+ add_action('fluent_cart/payment_subscription_paid', function ($data) {
75
+ // Extract order and transaction models from event data
76
+ $order = $data['order'];
77
+ $transaction = $data['transaction'];
78
+
79
+ // Handle subscription-specific logic after payment
80
+ fluent_cart_add_log(
81
+ 'Subscription Payment',
82
+ 'Subscription payment received for Order #' . $order->id,
83
+ 'success'
84
+ );
85
+ }, 10, 1);
86
+ ```
87
+
88
+ ---
89
+
90
+ ### `after_payment_{$paymentStatus}`
91
+ `fluent_cart/payments/after_payment_{$paymentStatus}` — Fires in abstract gateway after payment processing completes
92
+
93
+ * **When it runs:** This dynamic action fires inside the abstract payment gateway base class after a payment has been processed, the `OrderTransaction` recorded, and the `Order` status updated. It runs after `changeOrderStatus()` and any automatic digital-product completion logic. The `{$paymentStatus}` is the resulting payment status (e.g. `paid`, `failed`).
94
+ * **Source:** `app/Modules/PaymentMethods/Core/AbstractPaymentGateway.php`
95
+
96
+ #### Parameters:
97
+ `$data` *(array)*: The order that was just processed
98
+ ```php
99
+ $data = [
100
+ 'order' => $order, // \FluentCart\App\Models\Order instance with updated status
101
+ ];
102
+ ```
103
+
104
+ #### Usage Example:
105
+ ```php
106
+ // Hook after any payment gateway completes payment processing
107
+ add_action('fluent_cart/payments/after_payment_paid', function ($data) {
108
+ // Extract order model instance
109
+ $order = $data['order'];
110
+
111
+ // Trigger external fulfillment webhook after payment confirmation
112
+ wp_remote_post('https://fulfillment.example.com/api/orders', [
113
+ 'body' => wp_json_encode([
114
+ 'order_id' => $order->id,
115
+ 'total' => $order->total_amount,
116
+ ]),
117
+ ]);
118
+ }, 10, 1);
119
+ ```
120
+
121
+ ---
122
+
123
+ ### `payment_success`
124
+ `fluent_cart/payment_success` — Fires when an Airwallex or Square payment succeeds
125
+
126
+ * **When it runs:** This action fires inside the Airwallex and Square gateway handlers when a payment intent or payment object is confirmed as successful. The order status is updated to `processing` and payment status to `paid` before this hook runs.
127
+ * **Source:** `app/Modules/PaymentMethods/AirwallexGateway/Airwallex.php`, `app/Modules/PaymentMethods/SquareGateway/Square.php`
128
+
129
+ #### Parameters:
130
+ `$data` *(array)*: The order and payment intent/payment data
131
+ ```php
132
+ $data = [
133
+ 'order' => $order, // \FluentCart\App\Models\Order with updated status
134
+ 'payment_intent' => $paymentIntent, // Gateway-specific payment intent or payment object (array)
135
+ ];
136
+ ```
137
+
138
+ #### Usage Example:
139
+ ```php
140
+ // Hook when Airwallex or Square payment succeeds
141
+ add_action('fluent_cart/payment_success', function ($data) {
142
+ // Extract order and payment intent payload
143
+ $order = $data['order'];
144
+ $paymentIntent = $data['payment_intent'];
145
+
146
+ // Log the gateway-specific payment reference ID
147
+ fluent_cart_add_log(
148
+ 'Gateway Payment Success',
149
+ 'Payment intent ' . $paymentIntent['id'] . ' for Order #' . $order->id,
150
+ 'success'
151
+ );
152
+ }, 10, 1);
153
+ ```
154
+
155
+ ---
156
+
157
+ ### `payment_failed`
158
+ `fluent_cart/payment_failed` — Fires when an Airwallex payment fails
159
+
160
+ * **When it runs:** This action fires inside the Airwallex gateway handler when a payment intent is determined to have failed. The order status and payment status are both set to `failed` before this hook runs.
161
+ * **Source:** `app/Modules/PaymentMethods/AirwallexGateway/Airwallex.php`
162
+
163
+ #### Parameters:
164
+ `$data` *(array)*: The order and failed payment intent data
165
+ ```php
166
+ $data = [
167
+ 'order' => $order, // \FluentCart\App\Models\Order with failed status
168
+ 'payment_intent' => $paymentIntent, // Airwallex payment intent object (array)
169
+ ];
170
+ ```
171
+
172
+ #### Usage Example:
173
+ ```php
174
+ // Hook when an Airwallex payment fails
175
+ add_action('fluent_cart/payment_failed', function ($data) {
176
+ // Extract order and failed payment intent payload
177
+ $order = $data['order'];
178
+ $paymentIntent = $data['payment_intent'];
179
+
180
+ // Notify admin via email about failed payment
181
+ wp_mail(
182
+ get_option('admin_email'),
183
+ 'Payment Failed - Order #' . $order->id,
184
+ 'Airwallex payment intent ' . $paymentIntent['id'] . ' failed.'
185
+ );
186
+ }, 10, 1);
187
+ ```
188
+
189
+ ---
190
+
191
+ ## Payment Gateway Registration
192
+
193
+ ### `register_payment_methods`
194
+ `fluent_cart/register_payment_methods` — Register custom payment gateways
195
+
196
+ * **When it runs:** This action fires during initialization after all built-in payment gateways (Stripe, PayPal, Razorpay, Paystack, COD, Square, Airwallex) have been registered. Use this hook to register your own custom payment gateway with the gateway manager.
197
+ * **Source:** `app/Hooks/Handlers/GlobalPaymentHandler.php`
198
+
199
+ #### Parameters:
200
+ `$data` *(array)*: Contains the gateway manager instance
201
+ ```php
202
+ $data = [
203
+ 'gatewayManager' => $gateway, // GatewayManager instance for registering gateways
204
+ ];
205
+ ```
206
+
207
+ #### Usage Example:
208
+ ```php
209
+ // Hook to register custom payment gateways with gateway manager
210
+ add_action('fluent_cart/register_payment_methods', function ($data) {
211
+ // Extract gateway manager instance
212
+ $gatewayManager = $data['gatewayManager'];
213
+
214
+ // Register a custom payment gateway class
215
+ $gatewayManager->register('my_gateway', new MyCustomPaymentGateway());
216
+ }, 10, 1);
217
+ ```
218
+
219
+ ---
220
+
221
+ ### `after_render_payment_method_{$route}`
222
+ `fluent-cart/after_render_payment_method_{$route}` — Fires after a payment method UI renders on the checkout page
223
+
224
+ * **When it runs:** This action fires after a payment method's frontend UI (logo or radio button) has been rendered on the checkout form. The `{$route}` is the gateway's route identifier. Note that this hook uses a hyphenated prefix (`fluent-cart/`) rather than the usual underscored prefix.
225
+ * **Available dynamic variants:** `fluent-cart/after_render_payment_method_stripe`, `fluent-cart/after_render_payment_method_paypal`, `fluent-cart/after_render_payment_method_square`, `fluent-cart/after_render_payment_method_airwallex`, `fluent-cart/after_render_payment_method_offline_payment`, `fluent-cart/after_render_payment_method_razorpay`, `fluent-cart/after_render_payment_method_paystack`
226
+ * **Source:** `app/Modules/PaymentMethods/Core/AbstractPaymentGateway.php`
227
+
228
+ #### Parameters: None.
229
+
230
+ #### Usage Example:
231
+ ```php
232
+ // Hook after Stripe payment method UI renders on checkout form
233
+ add_action('fluent-cart/after_render_payment_method_stripe', function () {
234
+ // Output custom security note below Stripe payment option
235
+ echo '<p class="payment-note">Secure payments powered by Stripe.</p>';
236
+ }, 10, 0);
237
+ ```
238
+
239
+ ---
240
+
241
+ ## Stripe Webhooks
242
+
243
+ ### `stripe/webhook_{$eventType}`
244
+ `fluent_cart/payments/stripe/webhook_{$eventType}` — Fires for each Stripe webhook event
245
+
246
+ * **When it runs:** This dynamic action fires during Stripe webhook (IPN) processing after the event has been verified and the associated Order has been found. The `{$eventType}` is the Stripe event type with dots replaced by underscores (e.g. `invoice.payment_succeeded` becomes `invoice_payment_succeeded`).
247
+ * **Available dynamic variants:** `webhook_invoice_payment_succeeded`, `webhook_invoice_payment_failed`, `webhook_charge_refunded`, `webhook_customer_subscription_deleted`, `webhook_customer_subscription_updated`, `webhook_payment_intent_succeeded`, `webhook_payment_intent_payment_failed`
248
+ * **Source:** `app/Modules/PaymentMethods/StripeGateway/Webhook/IPN.php`
249
+
250
+ #### Parameters:
251
+ `$data` *(array)*: The Stripe event object and associated order
252
+ ```php
253
+ $data = [
254
+ 'event' => $event, // Stripe Event object (contains type, data, etc.)
255
+ 'order' => $order, // \FluentCart\App\Models\Order instance (may be WP_Error if not found)
256
+ ];
257
+ ```
258
+
259
+ #### Usage Example:
260
+ ```php
261
+ // Hook into Stripe charge refunded webhook event
262
+ add_action('fluent_cart/payments/stripe/webhook_charge_refunded', function ($data) {
263
+ // Extract Stripe event object and order model
264
+ $event = $data['event'];
265
+ $order = $data['order'];
266
+
267
+ // Exit early if order lookup failed
268
+ if (is_wp_error($order)) {
269
+ return;
270
+ }
271
+
272
+ $charge = $event->data->object;
273
+
274
+ // Log custom refund webhook event
275
+ fluent_cart_add_log(
276
+ 'Stripe Refund Webhook',
277
+ 'Charge ' . $charge->id . ' refunded for Order #' . $order->id,
278
+ 'info'
279
+ );
280
+ }, 10, 1);
281
+ ```
282
+
283
+ ---
284
+
285
+ ## PayPal Webhooks
286
+
287
+ ### `paypal_webhook_received`
288
+ `fluent_cart/paypal_webhook_received` — Fires when raw PayPal webhook data is received before processing
289
+
290
+ * **When it runs:** This action fires early in PayPal webhook processing, after the webhook type has been validated against the list of supported events but before any event-specific handling occurs. Use this to log or inspect all incoming PayPal webhook payloads.
291
+ * **Source:** `app/Modules/PaymentMethods/PayPalGateway/IPN.php`
292
+
293
+ #### Parameters:
294
+ `$data` *(array)*: The parsed and raw webhook data
295
+ ```php
296
+ $data = [
297
+ 'data' => $data, // Parsed webhook payload (array)
298
+ 'raw' => $post_data, // Raw POST body string
299
+ ];
300
+ ```
301
+
302
+ #### Usage Example:
303
+ ```php
304
+ // Hook when raw PayPal webhook data is received before processing
305
+ add_action('fluent_cart/paypal_webhook_received', function ($data) {
306
+ // Log all incoming raw PayPal webhooks for debugging
307
+ error_log('PayPal webhook received: ' . wp_json_encode($data['data']));
308
+ }, 10, 1);
309
+ ```
310
+
311
+ ---
312
+
313
+ ### `paypal/webhook_subscription_payment_received`
314
+ `fluent_cart/payments/paypal/webhook_subscription_payment_received` — Fires when a PayPal recurring subscription payment is received
315
+
316
+ * **When it runs:** This action fires when a PayPal `PAYMENT.SALE.COMPLETED` webhook is received and the resource contains a `billing_agreement_id`, indicating it is a recurring subscription payment rather than a one-time purchase.
317
+ * **Source:** `app/Modules/PaymentMethods/PayPalGateway/IPN.php`
318
+
319
+ #### Parameters:
320
+ `$data` *(array)*: The charge resource and billing agreement ID
321
+ ```php
322
+ $data = [
323
+ 'charge' => $resource, // PayPal sale resource object (array)
324
+ 'vendor_subscription_id' => $billingAgreementId, // PayPal billing agreement ID (string)
325
+ ];
326
+ ```
327
+
328
+ #### Usage Example:
329
+ ```php
330
+ // Hook when a PayPal recurring subscription payment is received
331
+ add_action('fluent_cart/payments/paypal/webhook_subscription_payment_received', function ($data) {
332
+ // Extract PayPal charge resource and billing agreement ID
333
+ $charge = $data['charge'];
334
+ $billingAgreementId = $data['vendor_subscription_id'];
335
+
336
+ // Log recurring payment event
337
+ fluent_cart_add_log(
338
+ 'PayPal Recurring Payment',
339
+ 'Billing agreement ' . $billingAgreementId . ' payment received.',
340
+ 'success'
341
+ );
342
+ }, 10, 1);
343
+ ```
344
+
345
+ ---
346
+
347
+ ### `paypal/webhook_payment_capture_completed`
348
+ `fluent_cart/payments/paypal/webhook_payment_capture_completed` — Fires when a PayPal one-time payment capture completes
349
+
350
+ * **When it runs:** This action fires when a PayPal `PAYMENT.SALE.COMPLETED` webhook arrives without a billing agreement ID (one-time payment), or when a `PAYMENT.CAPTURE.COMPLETED` event is received. Both indicate a successful one-time payment capture.
351
+ * **Source:** `app/Modules/PaymentMethods/PayPalGateway/IPN.php`
352
+
353
+ #### Parameters:
354
+ `$data` *(array)*: The charge resource from PayPal
355
+ ```php
356
+ $data = [
357
+ 'charge' => $resource, // PayPal capture/sale resource object (array)
358
+ ];
359
+ ```
360
+
361
+ #### Usage Example:
362
+ ```php
363
+ // Hook when a PayPal one-time payment capture completes
364
+ add_action('fluent_cart/payments/paypal/webhook_payment_capture_completed', function ($data) {
365
+ // Extract PayPal charge capture resource
366
+ $charge = $data['charge'];
367
+
368
+ // Handle one-time payment capture confirmation log
369
+ fluent_cart_add_log(
370
+ 'PayPal Capture Completed',
371
+ 'Capture completed for resource: ' . wp_json_encode($charge),
372
+ 'success'
373
+ );
374
+ }, 10, 1);
375
+ ```
376
+
377
+ ---
378
+
379
+ ### `paypal/webhook_payment_sale_refunded`
380
+ `fluent_cart/payments/paypal/webhook_payment_sale_refunded` — Fires when a PayPal recurring sale is refunded
381
+
382
+ * **When it runs:** This action fires when a PayPal `PAYMENT.SALE.REFUNDED` webhook is received, indicating that a refund has been issued for a recurring/subscription payment sale.
383
+ * **Source:** `app/Modules/PaymentMethods/PayPalGateway/IPN.php`
384
+
385
+ #### Parameters:
386
+ `$data` *(array)*: The refund resource from PayPal
387
+ ```php
388
+ $data = [
389
+ 'refund' => $resource, // PayPal refund resource object (array)
390
+ ];
391
+ ```
392
+
393
+ #### Usage Example:
394
+ ```php
395
+ // Hook when a PayPal recurring sale is refunded
396
+ add_action('fluent_cart/payments/paypal/webhook_payment_sale_refunded', function ($data) {
397
+ // Extract PayPal refund resource object
398
+ $refund = $data['refund'];
399
+
400
+ // Log recurring payment sale refund event
401
+ fluent_cart_add_log(
402
+ 'PayPal Sale Refund',
403
+ 'Recurring payment sale refunded: ' . wp_json_encode($refund),
404
+ 'info'
405
+ );
406
+ }, 10, 1);
407
+ ```
408
+
409
+ ---
410
+
411
+ ### `paypal/webhook_payment_capture_refunded`
412
+ `fluent_cart/payments/paypal/webhook_payment_capture_refunded` — Fires when a PayPal one-time payment capture is refunded
413
+
414
+ * **When it runs:** This action fires when a PayPal `PAYMENT.CAPTURE.REFUNDED` webhook is received, indicating that a refund has been issued for a one-time payment capture.
415
+ * **Source:** `app/Modules/PaymentMethods/PayPalGateway/IPN.php`
416
+
417
+ #### Parameters:
418
+ `$data` *(array)*: The refund resource from PayPal
419
+ ```php
420
+ $data = [
421
+ 'refund' => $resource, // PayPal refund resource object (array)
422
+ ];
423
+ ```
424
+
425
+ #### Usage Example:
426
+ ```php
427
+ // Hook when a PayPal one-time payment capture is refunded
428
+ add_action('fluent_cart/payments/paypal/webhook_payment_capture_refunded', function ($data) {
429
+ // Extract PayPal capture refund resource object
430
+ $refund = $data['refund'];
431
+
432
+ // Log one-time payment refund event
433
+ fluent_cart_add_log(
434
+ 'PayPal Capture Refund',
435
+ 'One-time payment capture refunded: ' . wp_json_encode($refund),
436
+ 'info'
437
+ );
438
+ }, 10, 1);
439
+ ```
440
+
441
+ ---
442
+
443
+ ### `paypal/webhook_{$eventType}` (disputes)
444
+ `fluent_cart/payments/paypal/webhook_{$eventType}` — Fires for PayPal customer dispute events
445
+
446
+ * **When it runs:** This dynamic action fires when a PayPal dispute-related webhook is received. The `{$eventType}` is the PayPal event type converted to lowercase with dots replaced by underscores.
447
+ * **Available dynamic variants:** `webhook_customer_dispute_created`, `webhook_customer_dispute_updated`, `webhook_customer_dispute_resolved`
448
+ * **Source:** `app/Modules/PaymentMethods/PayPalGateway/IPN.php`
449
+
450
+ #### Parameters:
451
+ `$data` *(array)*: The dispute resource from PayPal
452
+ ```php
453
+ $data = [
454
+ 'dispute' => $resource, // PayPal dispute resource object (array)
455
+ ];
456
+ ```
457
+
458
+ #### Usage Example:
459
+ ```php
460
+ // Hook when a PayPal customer dispute is created
461
+ add_action('fluent_cart/payments/paypal/webhook_customer_dispute_created', function ($data) {
462
+ // Extract dispute payload
463
+ $dispute = $data['dispute'];
464
+
465
+ // Alert admin about a new PayPal customer dispute
466
+ wp_mail(
467
+ get_option('admin_email'),
468
+ 'PayPal Dispute Created',
469
+ 'A customer has opened a dispute. Details: ' . wp_json_encode($dispute)
470
+ );
471
+ }, 10, 1);
472
+ ```
473
+
474
+ ---
475
+
476
+ ## Mollie Webhooks (Pro)
477
+
478
+ ### `mollie/webhook_subscription_payment_{$status}` (Pro)
479
+ `fluent_cart/payments/mollie/webhook_subscription_payment_{$status}` — Fires for each Mollie subscription payment status change
480
+
481
+ * **When it runs:** This dynamic action fires during Mollie webhook (IPN) processing when a subscription payment status is determined. The `{$status}` is replaced with the Mollie payment status (`paid`, `failed`, `expired`, `canceled`).
482
+ * **Available dynamic variants:** `webhook_subscription_payment_paid`, `webhook_subscription_payment_failed`, `webhook_subscription_payment_expired`, `webhook_subscription_payment_canceled`
483
+ * **Source:** `fluent-cart-pro/app/Modules/PaymentMethods/MollieGateway/Webhook/MollieIPN.php`
484
+
485
+ #### Parameters:
486
+ * `$molliePayment` *(object)* — The Mollie Payment object from the API
487
+ * `$order` *(\FluentCart\App\Models\Order)* — The Order model instance associated with this payment
488
+
489
+ #### Usage Example:
490
+ ```php
491
+ // Hook for successful Mollie subscription payment (Pro)
492
+ add_action('fluent_cart/payments/mollie/webhook_subscription_payment_paid', function ($molliePayment, $order) {
493
+ // Handle successful Mollie subscription payment log
494
+ fluent_cart_add_log(
495
+ 'Mollie Subscription Payment',
496
+ 'Subscription payment received for Order #' . $order->id . ' (Mollie ID: ' . $molliePayment->id . ')',
497
+ 'success'
498
+ );
499
+ }, 10, 2);
500
+ ```
501
+
502
+ ---
503
+
504
+ ### `mollie/webhook_payment_{$status}` (Pro)
505
+ `fluent_cart/payments/mollie/webhook_payment_{$status}` — Fires for each Mollie one-time payment status change
506
+
507
+ * **When it runs:** This dynamic action fires during Mollie webhook processing when a one-time (non-subscription) payment status is determined. The `{$status}` is replaced with the Mollie payment status.
508
+ * **Available dynamic variants:** `webhook_payment_paid`, `webhook_payment_failed`, `webhook_payment_expired`, `webhook_payment_canceled`
509
+ * **Source:** `fluent-cart-pro/app/Modules/PaymentMethods/MollieGateway/Webhook/MollieIPN.php`
510
+
511
+ #### Parameters:
512
+ * `$molliePayment` *(object)* — The Mollie Payment object from the API
513
+ * `$order` *(\FluentCart\App\Models\Order)* — The Order model instance associated with this payment
514
+
515
+ #### Usage Example:
516
+ ```php
517
+ // Hook for successful Mollie one-time payment (Pro)
518
+ add_action('fluent_cart/payments/mollie/webhook_payment_paid', function ($molliePayment, $order) {
519
+ // Trigger external fulfillment for Mollie order
520
+ wp_remote_post('https://fulfillment.example.com/api/orders', [
521
+ 'body' => wp_json_encode([
522
+ 'order_id' => $order->id,
523
+ 'mollie_id' => $molliePayment->id,
524
+ 'amount' => $molliePayment->amount->value,
525
+ 'currency' => $molliePayment->amount->currency,
526
+ ]),
527
+ ]);
528
+ }, 10, 2);
529
+ ```
530
+
531
+ ---
532
+
533
+ ### `payment_failed` (Mollie) (Pro)
534
+ `fluent_cart/payment_failed` — Fires when a Mollie payment fails, is canceled, or expires
535
+
536
+ * **When it runs:** This action fires inside the Mollie IPN handler when a payment is determined to have failed, been canceled, or expired. The order status and payment status are updated before this hook runs.
537
+ * **Source:** `fluent-cart-pro/app/Modules/PaymentMethods/MollieGateway/Webhook/MollieIPN.php`
538
+
539
+ #### Parameters:
540
+ `$data` *(array)*: Payment failure data
541
+ ```php
542
+ $data = [
543
+ 'order' => $order, // \FluentCart\App\Models\Order — with updated failed status
544
+ 'transaction' => $transactionModel, // \FluentCart\App\Models\OrderTransaction
545
+ 'old_payment_status' => $oldStatus, // string — previous payment status
546
+ 'new_payment_status' => 'failed', // string — new payment status
547
+ 'reason' => $reason, // string — 'failed', 'canceled', or 'expired'
548
+ ];
549
+ ```
550
+
551
+ #### Usage Example:
552
+ ```php
553
+ // Hook when a Mollie payment fails, is canceled, or expires (Pro)
554
+ add_action('fluent_cart/payment_failed', function ($data) {
555
+ // Extract order, transaction, and failure reason
556
+ $order = $data['order'];
557
+ $transaction = $data['transaction'];
558
+ $oldStatus = $data['old_payment_status'];
559
+ $newStatus = $data['new_payment_status'];
560
+ $reason = $data['reason'];
561
+
562
+ // Only handle Mollie failures in this callback
563
+ if ($order->payment_method !== 'mollie') {
564
+ return;
565
+ }
566
+
567
+ // Send email alert to admin regarding Mollie failure
568
+ wp_mail(
569
+ get_option('admin_email'),
570
+ 'Mollie Payment Failed - Order #' . $order->id,
571
+ sprintf(
572
+ "Payment for Order #%d has %s.\nPrevious status: %s\nNew status: %s\nTransaction ID: %s",
573
+ $order->id,
574
+ $reason,
575
+ $oldStatus,
576
+ $newStatus,
577
+ $transaction->id
578
+ )
579
+ );
580
+ }, 10, 1);
581
+ ```
582
+
583
+ ---
584
+
585
+ ## Paddle Webhooks (Pro)
586
+
587
+ ### `paddle_webhook_received` (Pro)
588
+ `fluent_cart/paddle_webhook_received` — Fires when raw Paddle webhook data is received before processing
589
+
590
+ * **When it runs:** This action fires early in Paddle webhook processing, after the event type has been extracted from the payload but before any event-specific handling occurs. Use this to log or inspect all incoming Paddle webhook payloads for debugging purposes.
591
+ * **Source:** `fluent-cart-pro/app/Modules/PaymentMethods/PaddleGateway/Webhook/IPN.php`
592
+
593
+ #### Parameters:
594
+ * `$eventType` *(string)* — The Paddle event type (e.g. `transaction.paid`, `subscription.created`)
595
+ * `$data` *(array)* — The parsed webhook payload
596
+ * `$raw` *(string)* — The raw POST body string
597
+ * `$order` *(\FluentCart\App\Models\Order|null)* — The associated Order model instance, or `null` if not resolved
598
+
599
+ #### Usage Example:
600
+ ```php
601
+ // Hook when raw Paddle webhook data is received before processing (Pro)
602
+ add_action('fluent_cart/paddle_webhook_received', function ($eventType, $data, $raw, $order) {
603
+ // Log all incoming Paddle webhooks for debugging
604
+ fluent_cart_add_log(
605
+ 'Paddle Webhook Received',
606
+ sprintf(
607
+ 'Event: %s | Order: %s | Payload size: %d bytes',
608
+ $eventType,
609
+ $order ? '#' . $order->id : 'N/A',
610
+ strlen($raw)
611
+ ),
612
+ 'info'
613
+ );
614
+ }, 10, 4);
615
+ ```
616
+
617
+ ---
618
+
619
+ ### `paddle/webhook_{$eventType}` (Pro)
620
+ `fluent_cart/payments/paddle/webhook_{$eventType}` — Fires for each Paddle webhook event
621
+
622
+ * **When it runs:** This dynamic action fires during Paddle webhook (IPN) processing after the event has been received and the associated order has been resolved (if applicable). The `{$eventType}` is the Paddle event type with dots replaced by underscores.
623
+ * **Available dynamic variants:** `webhook_transaction_paid`, `webhook_transaction_completed`, `webhook_transaction_payment_failed`, `webhook_transaction_refunded`, `webhook_adjustment_created`, `webhook_adjustment_updated`, `webhook_subscription_created`, `webhook_subscription_activated`, `webhook_subscription_updated`, `webhook_subscription_canceled`, `webhook_subscription_paused`, `webhook_subscription_resumed`, `webhook_subscription_past_due`
624
+ * **Source:** `fluent-cart-pro/app/Modules/PaymentMethods/PaddleGateway/Webhook/IPN.php`
625
+
626
+ #### Parameters:
627
+ * `$eventType` *(string)* — The Paddle event type with dots replaced by underscores
628
+ * `$data` *(array)* — The parsed webhook payload
629
+ * `$raw` *(string)* — The raw POST body string
630
+ * `$order` *(\FluentCart\App\Models\Order|null)* — The associated Order model instance, or `null` if not resolved
631
+
632
+ #### Usage Example:
633
+ ```php
634
+ // Hook when a Paddle transaction payment succeeds (Pro)
635
+ add_action('fluent_cart/payments/paddle/webhook_transaction_paid', function ($eventType, $data, $raw, $order) {
636
+ if (!$order) {
637
+ return;
638
+ }
639
+
640
+ // Handle successful Paddle transaction payment
641
+ fluent_cart_add_log(
642
+ 'Paddle Transaction Paid',
643
+ 'Paddle payment completed for Order #' . $order->id,
644
+ 'success'
645
+ );
646
+ }, 10, 4);
647
+
648
+ // Hook when a Paddle subscription is canceled (Pro)
649
+ add_action('fluent_cart/payments/paddle/webhook_subscription_canceled', function ($eventType, $data, $raw, $order) {
650
+ if (!$order) {
651
+ return;
652
+ }
653
+
654
+ // Alert admin about Paddle subscription cancellation via email
655
+ wp_mail(
656
+ get_option('admin_email'),
657
+ 'Paddle Subscription Canceled - Order #' . $order->id,
658
+ 'A Paddle subscription has been canceled. Event data: ' . wp_json_encode($data)
659
+ );
660
+ }, 10, 4);
661
+
662
+ // Hook when a Paddle transaction is refunded (Pro)
663
+ add_action('fluent_cart/payments/paddle/webhook_transaction_refunded', function ($eventType, $data, $raw, $order) {
664
+ if (!$order) {
665
+ return;
666
+ }
667
+
668
+ // Track Paddle refund event
669
+ fluent_cart_add_log(
670
+ 'Paddle Refund',
671
+ 'Paddle transaction refunded for Order #' . $order->id,
672
+ 'warning'
673
+ );
674
+ }, 10, 4);
675
+ ```
676
+
677
+ ---
678
+
679
+ ## Integrations
680
+
681
+ ### `register_integration_action`
682
+ `fluent_cart/register_integration_action` — Register custom integration actions during initialization
683
+
684
+ * **When it runs:** This action fires during WordPress `init` to allow registration of custom integration actions. Use this hook to register your integration provider so it appears in the FluentCart integration action settings.
685
+ * **Source:** `app/Modules/IntegrationActions/GlobalIntegrationActionHandler.php`
686
+
687
+ #### Parameters: None.
688
+
689
+ #### Usage Example:
690
+ ```php
691
+ // Hook to register custom integration actions during initialization
692
+ add_action('fluent_cart/register_integration_action', function () {
693
+ // Register a custom integration action provider via filter
694
+ add_filter('fluent_cart/integration/get_global_integration_actions', function ($actions) {
695
+ $actions['my_crm'] = [
696
+ 'title' => 'My CRM',
697
+ 'logo' => plugin_dir_url(__FILE__) . 'logo.png',
698
+ 'handler' => 'MyCrmIntegrationHandler',
699
+ ];
700
+ return $actions;
701
+ });
702
+ }, 10, 0);
703
+ ```
704
+
705
+ ---
706
+
707
+ ### `authenticate_global_credentials_{$settingsKey}`
708
+ `fluent_cart/integration/authenticate_global_credentials_{$settingsKey}` — Verify integration credentials for a specific provider
709
+
710
+ * **When it runs:** This dynamic action fires when a user clicks the "Verify" or "Authenticate" button for an integration's global credentials in the FluentCart admin settings. The `{$settingsKey}` is the integration provider's settings key (e.g. `mailchimp`, `activecampaign`).
711
+ * **Source:** `app/Modules/Integrations/GlobalIntegrationSettings.php`
712
+
713
+ #### Parameters:
714
+ `$data` *(array)*: The settings key and integration configuration
715
+ ```php
716
+ $data = [
717
+ 'settings_key' => $settingsKey, // string — Integration provider key
718
+ 'integration' => $integration, // array — Integration settings data (unslashed)
719
+ ];
720
+ ```
721
+
722
+ #### Usage Example:
723
+ ```php
724
+ // Hook to verify integration credentials for a specific provider
725
+ add_action('fluent_cart/integration/authenticate_global_credentials_my_crm', function ($data) {
726
+ // Extract API key from integration settings payload
727
+ $apiKey = $data['integration']['api_key'] ?? '';
728
+
729
+ // Verify the API key with the external service endpoint
730
+ $response = wp_remote_get('https://api.mycrm.com/verify', [
731
+ 'headers' => ['Authorization' => 'Bearer ' . $apiKey],
732
+ ]);
733
+
734
+ if (is_wp_error($response) || wp_remote_retrieve_response_code($response) !== 200) {
735
+ wp_send_json_error(['message' => 'Invalid API credentials.'], 400);
736
+ }
737
+
738
+ wp_send_json_success(['message' => 'Credentials verified successfully.']);
739
+ }, 10, 1);
740
+ ```
741
+
742
+ ---
743
+
744
+ ### `save_global_integration_settings_{$settingsKey}`
745
+ `fluent_cart/integration/save_global_integration_settings_{$settingsKey}` — Save integration settings for a specific provider
746
+
747
+ * **When it runs:** This dynamic action fires when a user saves the global integration settings for a specific provider. The `{$settingsKey}` is the integration provider's settings key. The handler is expected to persist the settings and send a JSON response.
748
+ * **Source:** `app/Modules/Integrations/GlobalIntegrationSettings.php`
749
+
750
+ #### Parameters:
751
+ `$data` *(array)*: The settings key and integration configuration
752
+ ```php
753
+ $data = [
754
+ 'settings_key' => $settingsKey, // string — Integration provider key
755
+ 'integration' => $integration, // array — Integration settings data (unslashed)
756
+ ];
757
+ ```
758
+
759
+ #### Usage Example:
760
+ ```php
761
+ // Hook to save integration settings for a specific provider
762
+ add_action('fluent_cart/integration/save_global_integration_settings_my_crm', function ($data) {
763
+ // Extract integration settings array
764
+ $settings = $data['integration'];
765
+
766
+ // Persist integration settings into FluentCart options
767
+ fluent_cart_update_option('my_crm_settings', $settings);
768
+
769
+ wp_send_json_success([
770
+ 'message' => 'Settings saved successfully.',
771
+ ]);
772
+ }, 10, 1);
773
+ ```
774
+
775
+ ---
776
+
777
+ ### `integration/chained_{$route}`
778
+ `fluent_cart/integration/chained_{$route}` — Fires for chained data requests in cascading dropdowns
779
+
780
+ * **When it runs:** This dynamic action fires when the integration settings UI requests chained/dependent data for cascading dropdown fields. For example, after selecting a mailing list, this hook loads the available tags or groups for that list. The `{$route}` is the integration's route identifier.
781
+ * **Source:** `app/Modules/Integrations/GlobalIntegrationSettings.php`
782
+
783
+ #### Parameters:
784
+ `$data` *(array)*: The request data for the chained lookup
785
+ ```php
786
+ $data = [
787
+ 'data' => $requestData, // array — Request data array (contains route, selected values, etc.)
788
+ ];
789
+ ```
790
+
791
+ #### Usage Example:
792
+ ```php
793
+ // Hook for chained data requests in cascading dropdowns
794
+ add_action('fluent_cart/integration/chained_my_crm', function ($data) {
795
+ // Extract request data and list ID
796
+ $requestData = $data['data'];
797
+ $listId = $requestData['list_id'] ?? '';
798
+
799
+ // Fetch tags for the selected mailing list
800
+ $tags = my_crm_get_tags($listId);
801
+
802
+ wp_send_json_success([
803
+ 'tags' => $tags,
804
+ ]);
805
+ }, 10, 1);
806
+ ```
807
+
808
+ ---
809
+
810
+ ### `integration/run/{$provider}`
811
+ `fluent_cart/integration/run/{$provider}` — Execute a specific integration feed for a provider
812
+
813
+ * **When it runs:** This dynamic action fires when an integration feed needs to be executed for a specific provider, both in real-time (synchronous) and async (via scheduled actions) processing. The `{$provider}` is the integration provider's slug (e.g. `mailchimp`, `activecampaign`).
814
+ * **Source:** `app/Listeners/IntegrationEventListener.php`
815
+
816
+ #### Parameters:
817
+ `$integrationArray` *(array)*: The full integration feed configuration and context
818
+ ```php
819
+ $integrationArray = [
820
+ 'provider' => 'mailchimp', // string — Integration provider slug
821
+ 'order' => $order, // \FluentCart\App\Models\Order instance
822
+ 'event_data' => $data, // array — Event trigger data (may include subscription)
823
+ 'feed' => [], // array — Feed configuration array
824
+ ];
825
+ ```
826
+
827
+ #### Usage Example:
828
+ ```php
829
+ // Hook to execute a specific integration feed for a provider
830
+ add_action('fluent_cart/integration/run/my_crm', function ($integrationArray) {
831
+ // Extract order, feed config, and customer model
832
+ $order = $integrationArray['order'];
833
+ $feed = $integrationArray['feed'] ?? [];
834
+ $customer = $order->customer;
835
+
836
+ // Push customer data to external CRM via HTTP request
837
+ wp_remote_post('https://api.mycrm.com/contacts', [
838
+ 'headers' => [
839
+ 'Authorization' => 'Bearer ' . fluent_cart_get_option('my_crm_api_key'),
840
+ 'Content-Type' => 'application/json',
841
+ ],
842
+ 'body' => wp_json_encode([
843
+ 'email' => $customer->email,
844
+ 'name' => $customer->full_name,
845
+ 'tags' => $feed['tags'] ?? [],
846
+ ]),
847
+ ]);
848
+ }, 10, 1);
849
+ ```
850
+
851
+ ---
852
+
853
+ ### `global_notify_completed`
854
+ `fluent_cart/integrations/global_notify_completed` — Fires after all synchronous global notification feeds have completed
855
+
856
+ * **When it runs:** This action fires after all sync (non-async) global notification integration feeds have been processed for an order. It does not fire if there are async feeds still pending.
857
+ * **Source:** `app/Modules/Integrations/GlobalNotificationHandler.php`
858
+
859
+ #### Parameters:
860
+ * `$order` *(\FluentCart\App\Models\Order)* — The Order model instance
861
+ * `$feeds` *(array)* — Array of feed configurations that were processed
862
+
863
+ #### Usage Example:
864
+ ```php
865
+ // Hook after all synchronous global notification feeds have completed
866
+ add_action('fluent_cart/integrations/global_notify_completed', function ($order, $feeds) {
867
+ // Log completion of synchronous integrations for order
868
+ fluent_cart_add_log(
869
+ 'Integrations Complete',
870
+ count($feeds) . ' integration feeds processed for Order #' . $order->id,
871
+ 'info'
872
+ );
873
+ }, 10, 2);
874
+ ```
875
+
876
+ ---
877
+
878
+ ### `reindex_integration_feeds`
879
+ `fluent_cart/reindex_integration_feeds` — Fires when integration feeds need to be re-indexed
880
+
881
+ * **When it runs:** This action fires after integration feed configurations are saved or updated, both at the global level (via `IntegrationController`) and at the product level (via `ProductIntegrationsController`).
882
+ * **Source:** `app/Http/Controllers/IntegrationController.php`, `app/Http/Controllers/ProductIntegrationsController.php`
883
+
884
+ #### Parameters:
885
+ `$data` *(array)*: Empty array `[]`
886
+
887
+ #### Usage Example:
888
+ ```php
889
+ // Hook when integration feeds need to be re-indexed
890
+ add_action('fluent_cart/reindex_integration_feeds', function ($data) {
891
+ // Clear cached integration feed transient
892
+ delete_transient('my_plugin_integration_cache');
893
+ }, 10, 1);
894
+ ```
895
+
896
+ ---
897
+
898
+ ## Storage Drivers
899
+
900
+ ### `register_storage_drivers`
901
+ `fluent_cart/register_storage_drivers` — Register custom file storage drivers
902
+
903
+ * **When it runs:** This action fires during WordPress `init` at priority 9, after the built-in Local and S3 storage drivers have been initialized. Use this hook to register a custom file storage driver (e.g. Google Cloud Storage, Azure Blob Storage) for digital product file delivery.
904
+ * **Source:** `app/Hooks/Handlers/GlobalStorageHandler.php`
905
+
906
+ #### Parameters: None.
907
+
908
+ #### Usage Example:
909
+ ```php
910
+ // Hook to register custom file storage drivers
911
+ add_action('fluent_cart/register_storage_drivers', function () {
912
+ // Register custom storage driver via filter
913
+ add_filter('fluent_cart/storage_drivers', function ($drivers) {
914
+ $drivers['gcs'] = [
915
+ 'title' => 'Google Cloud Storage',
916
+ 'handler' => new MyGcsStorageDriver(),
917
+ ];
918
+ return $drivers;
919
+ });
920
+ }, 10, 0);
921
+ ```
922
+
923
+ ---
924
+
925
+ ## Development Logging
926
+
927
+ ### `dev_log`
928
+ `fluent_cart/dev_log` — Fires for development and debug logging (requires `FLUENT_CART_DEV_MODE`)
929
+
930
+ * **When it runs:** This action fires at various points during payment gateway webhook processing (primarily in the PayPal IPN handler) when the `FLUENT_CART_DEV_MODE` constant is defined. It provides detailed diagnostic data for debugging webhook failures, signature verification issues, and missing transaction references.
931
+ * **Source:** `app/Modules/PaymentMethods/PayPalGateway/IPN.php` (multiple call sites)
932
+
933
+ #### Parameters:
934
+ `$data` *(array)*: Logging context with raw data and metadata
935
+ ```php
936
+ $data = [
937
+ 'raw_data' => $rawData, // mixed — Raw webhook payload or resource data
938
+ 'status' => 'failed', // string — Log status: 'failed', 'received', etc.
939
+ 'title' => 'Log title', // string — Human-readable log title
940
+ 'log_type' => 'webhook', // string — Type of log entry
941
+ 'module_type' => 'paypal_ipn', // string — Module identifier
942
+ 'module_name' => 'PayPal', // string — Display name of the module
943
+ ];
944
+ ```
945
+
946
+ #### Usage Example:
947
+ ```php
948
+ // Hook for development and debug logging (requires FLUENT_CART_DEV_MODE)
949
+ add_action('fluent_cart/dev_log', function ($data) {
950
+ // Format detailed diagnostic log entry string
951
+ $logEntry = sprintf(
952
+ "[%s] [%s] %s - %s\n%s\n\n",
953
+ gmdate('Y-m-d H:i:s'),
954
+ $data['status'] ?? 'unknown',
955
+ $data['module_name'] ?? 'General',
956
+ $data['title'] ?? 'No title',
957
+ wp_json_encode($data['raw_data'] ?? [], JSON_PRETTY_PRINT)
958
+ );
959
+
960
+ // Write diagnostic entry to debug log file
961
+ error_log($logEntry, 3, WP_CONTENT_DIR . '/fluent-cart-debug.log');
962
+ }, 10, 1);
963
+ ```