fluentcart-developer 1.1.0

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 (66) hide show
  1. package/.gitattributes +2 -0
  2. package/CLAUDE.md +22 -0
  3. package/CONTRIBUTING.md +73 -0
  4. package/LICENSE +21 -0
  5. package/README.md +127 -0
  6. package/SKILL.md +127 -0
  7. package/bin/index.js +281 -0
  8. package/copy-skills.js +43 -0
  9. package/package.json +38 -0
  10. package/skills/fluentcart-developer/SKILL.md +172 -0
  11. package/skills/fluentcart-developer/examples/README.md +25 -0
  12. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -0
  13. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -0
  14. package/skills/fluentcart-developer/examples/sample-custom-addon/fluentcart-custom-addon.php +114 -0
  15. package/skills/fluentcart-developer/examples/sample-custom-payment-gateway/fluentcart-custom-gateway-example.php +149 -0
  16. package/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -0
  17. package/skills/fluentcart-developer/examples/sample-shipping-carrier/fluentcart-custom-shipping-carrier.php +62 -0
  18. package/skills/fluentcart-developer/references/action-hooks-admin-templates.md +787 -0
  19. package/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -0
  20. package/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -0
  21. package/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -0
  22. package/skills/fluentcart-developer/references/action-hooks-orders.md +631 -0
  23. package/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -0
  24. package/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -0
  25. package/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -0
  26. package/skills/fluentcart-developer/references/database-models-query-builder.md +194 -0
  27. package/skills/fluentcart-developer/references/database-models-reference.md +604 -0
  28. package/skills/fluentcart-developer/references/database-schema-reference.md +940 -0
  29. package/skills/fluentcart-developer/references/engineering-notes.md +154 -0
  30. package/skills/fluentcart-developer/references/fee-system-guide.md +449 -0
  31. package/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -0
  32. package/skills/fluentcart-developer/references/filter-hooks-customers-subscriptions.md +902 -0
  33. package/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -0
  34. package/skills/fluentcart-developer/references/filter-hooks-orders-payments.md +1319 -0
  35. package/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -0
  36. package/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -0
  37. package/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -0
  38. package/skills/fluentcart-developer/references/ghost-product-selling.md +458 -0
  39. package/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -0
  40. package/skills/fluentcart-developer/references/paddle-gateway-case-study.md +1925 -0
  41. package/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -0
  42. package/skills/fluentcart-developer/references/rest-api-checkout.md +286 -0
  43. package/skills/fluentcart-developer/references/rest-api-coupons.md +794 -0
  44. package/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -0
  45. package/skills/fluentcart-developer/references/rest-api-customers.md +1121 -0
  46. package/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -0
  47. package/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -0
  48. package/skills/fluentcart-developer/references/rest-api-files.md +290 -0
  49. package/skills/fluentcart-developer/references/rest-api-integrations.md +324 -0
  50. package/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -0
  51. package/skills/fluentcart-developer/references/rest-api-licensing.md +171 -0
  52. package/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -0
  53. package/skills/fluentcart-developer/references/rest-api-orders.md +1241 -0
  54. package/skills/fluentcart-developer/references/rest-api-overview.md +131 -0
  55. package/skills/fluentcart-developer/references/rest-api-products.md +2563 -0
  56. package/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -0
  57. package/skills/fluentcart-developer/references/rest-api-reference.md +552 -0
  58. package/skills/fluentcart-developer/references/rest-api-reports.md +377 -0
  59. package/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -0
  60. package/skills/fluentcart-developer/references/rest-api-settings.md +528 -0
  61. package/skills/fluentcart-developer/references/rest-api-shipping.md +800 -0
  62. package/skills/fluentcart-developer/references/rest-api-subscriptions.md +606 -0
  63. package/skills/fluentcart-developer/references/rest-api-tax.md +356 -0
  64. package/skills/fluentcart-developer/references/subscription-customization.md +197 -0
  65. package/skills/fluentcart-developer/scripts/cli.js +1 -0
  66. package/skills.sh.json +13 -0
@@ -0,0 +1,761 @@
1
+ # Payment Methods Module
2
+
3
+ The Payment Methods module is FluentCart's core payment processing system. It provides a flexible architecture for integrating various payment gateways while maintaining a consistent interface for order processing.
4
+
5
+ ---
6
+
7
+ ## Architecture Overview
8
+
9
+ ### Core Components
10
+
11
+ #### 1. GatewayManager
12
+
13
+ The central manager for all payment gateways using the Singleton pattern.
14
+
15
+ ```php
16
+ use FluentCart\App\Modules\PaymentMethods\Core\GatewayManager;
17
+
18
+ // Get manager instance
19
+ $manager = GatewayManager::getInstance();
20
+
21
+ // Get specific gateway
22
+ $stripe = GatewayManager::gateway('stripe');
23
+
24
+ // Check if gateway exists
25
+ $exists = GatewayManager::has('stripe');
26
+ ```
27
+
28
+ #### 2. PaymentGatewayInterface
29
+
30
+ The interface that all payment gateways must implement.
31
+
32
+ ```php
33
+ interface PaymentGatewayInterface
34
+ {
35
+ public function has(string $feature): bool;
36
+ public function meta(): array;
37
+ public function makePaymentFromPaymentInstance(PaymentInstance $paymentInstance);
38
+ public function handleIPN();
39
+ public function getOrderInfo(array $data);
40
+ public function fields();
41
+ }
42
+ ```
43
+
44
+ #### 3. AbstractPaymentGateway
45
+
46
+ Base class providing common functionality for all gateways.
47
+
48
+ ```php
49
+ abstract class AbstractPaymentGateway implements PaymentGatewayInterface
50
+ {
51
+ public array $supportedFeatures = [];
52
+ public StoreSettings $storeSettings;
53
+ public ?AbstractSubscriptionModule $subscriptions;
54
+ public BaseGatewaySettings $settings;
55
+ }
56
+ ```
57
+
58
+ ---
59
+
60
+ ## Supported Payment Gateways
61
+
62
+ ### Built-in Gateways
63
+
64
+ | Gateway | Features | Supported Methods | Location |
65
+ |---------|----------|-------------------|----------|
66
+ | **Stripe** | Payment, Refund, Webhook, Custom Payment, Card Update, Dispute Handler | Credit Cards, Debit Cards, Digital Wallets | `app/Modules/PaymentMethods/StripeGateway/` |
67
+ | **PayPal** | Payment, Refund, Webhook, Subscriptions | PayPal, Credit Cards via PayPal | `app/Modules/PaymentMethods/PayPalGateway/` |
68
+ | **Mollie** | Payment, Refund, Webhook | Credit Cards, SEPA, iDEAL, Bancontact | `app/Modules/PaymentMethods/MollieGateway/` |
69
+ | **Square** | Payment, Refund, Webhook | Credit Cards, Digital Wallets | `app/Modules/PaymentMethods/SquareGateway/` |
70
+ | **Razorpay** | Payment, Refund, Webhook | Credit Cards, UPI, Net Banking, Wallets | `app/Modules/PaymentMethods/RazorpayGateway/` |
71
+ | **Paystack** | Payment, Refund, Webhook | Credit Cards, Bank Transfer, Mobile Money | `app/Modules/PaymentMethods/PaystackGateway/` |
72
+ | **Authorize.Net** | Payment, Refund, Webhook | Credit Cards, ACH | `app/Modules/PaymentMethods/AuthorizeNetGateway/` |
73
+ | **Airwallex** | Payment, Refund, Webhook | Credit Cards, Local Payment Methods | `app/Modules/PaymentMethods/AirwallexGateway/` |
74
+ | **Cash on Delivery (COD)** | Payment, Refund | Cash on Delivery | `app/Modules/PaymentMethods/Cod/` |
75
+
76
+ ---
77
+
78
+ ## Gateway Development
79
+
80
+ ### Creating a Custom Payment Gateway
81
+
82
+ #### 1. Create Gateway Directory Structure
83
+
84
+ ```
85
+ app/Modules/PaymentMethods/YourGateway/
86
+ ├── YourGateway.php # Main gateway class
87
+ ├── Settings/
88
+ │ └── YourGatewaySettings.php # Gateway settings
89
+ ├── API/
90
+ │ └── YourGatewayAPI.php # API communication
91
+ ├── Webhook/
92
+ │ └── WebhookHandler.php # Webhook processing
93
+ ├── Views/
94
+ │ └── payment-form.php # Payment form template
95
+ └── Assets/
96
+ ├── css/
97
+ ├── js/
98
+ └── images/
99
+ ```
100
+
101
+ #### 2. Create Main Gateway Class
102
+
103
+ ```php
104
+ <?php
105
+ namespace FluentCart\App\Modules\PaymentMethods\YourGateway;
106
+
107
+ use FluentCart\App\Modules\PaymentMethods\Core\AbstractPaymentGateway;
108
+ use FluentCart\App\Services\Payments\PaymentInstance;
109
+ use FluentCart\App\Vite;
110
+
111
+ class YourGateway extends AbstractPaymentGateway
112
+ {
113
+ // Define features this gateway supports
114
+ public array $supportedFeatures = [
115
+ 'payment',
116
+ 'refund',
117
+ 'webhook'
118
+ ];
119
+
120
+ public function __construct()
121
+ {
122
+ // Initialize with gateway-specific settings
123
+ parent::__construct(new YourGatewaySettings());
124
+ }
125
+
126
+ public function meta(): array
127
+ {
128
+ // Return gateway metadata for admin UI and checkout display
129
+ return [
130
+ 'title' => __('Your Gateway', 'fluent-cart'),
131
+ 'route' => 'your_gateway',
132
+ 'slug' => 'your_gateway',
133
+ 'description' => __('Accept payments with Your Gateway', 'fluent-cart'),
134
+ 'logo' => Vite::getAssetUrl('images/payment-methods/your-gateway-logo.svg'),
135
+ 'icon' => Vite::getAssetUrl('images/payment-methods/your-gateway-icon.svg'),
136
+ 'brand_color' => '#your-brand-color',
137
+ 'status' => $this->settings->get('is_active') === 'yes',
138
+ 'upcoming' => false,
139
+ 'supported_features' => $this->supportedFeatures
140
+ ];
141
+ }
142
+
143
+ public function boot()
144
+ {
145
+ // Initialize webhook handler for incoming payment notifications
146
+ add_action('wp_ajax_your_gateway_webhook', [$this, 'handleWebhook']);
147
+ add_action('wp_ajax_nopriv_your_gateway_webhook', [$this, 'handleWebhook']);
148
+
149
+ // Register settings filter for admin configuration
150
+ add_filter('fluent_cart/payment_methods/your_gateway_settings', [$this, 'getSettings'], 10, 2);
151
+ }
152
+
153
+ public function makePaymentFromPaymentInstance(PaymentInstance $paymentInstance)
154
+ {
155
+ // Extract order and transaction from payment instance
156
+ $order = $paymentInstance->order;
157
+ $transaction = $paymentInstance->transaction;
158
+
159
+ // Prepare payment data for gateway API
160
+ $paymentData = [
161
+ 'amount' => $transaction->total,
162
+ 'currency' => $transaction->currency,
163
+ 'order_id' => $order->uuid,
164
+ 'customer_email' => $order->email,
165
+ 'return_url' => $this->getReturnUrl($transaction),
166
+ 'cancel_url' => $this->getCancelUrl($transaction)
167
+ ];
168
+
169
+ // Process payment with gateway API
170
+ $result = $this->processPayment($paymentData);
171
+
172
+ if ($result['success']) {
173
+ return [
174
+ 'success' => true,
175
+ 'redirect_url' => $result['redirect_url'],
176
+ 'payment_id' => $result['payment_id']
177
+ ];
178
+ }
179
+
180
+ return [
181
+ 'success' => false,
182
+ 'message' => $result['error_message']
183
+ ];
184
+ }
185
+
186
+ public function handleIPN()
187
+ {
188
+ // Read and verify incoming webhook data
189
+ $webhookData = $this->getWebhookData();
190
+
191
+ if (!$this->verifyWebhookSignature($webhookData)) {
192
+ http_response_code(400);
193
+ exit('Invalid signature');
194
+ }
195
+
196
+ // Process the verified webhook event
197
+ $this->processWebhook($webhookData);
198
+
199
+ http_response_code(200);
200
+ exit('OK');
201
+ }
202
+
203
+ public function getOrderInfo(array $data)
204
+ {
205
+ // Retrieve order details by UUID
206
+ $orderId = $data['order_id'] ?? '';
207
+ $order = Order::where('uuid', $orderId)->first();
208
+
209
+ if (!$order) {
210
+ return new \WP_Error('order_not_found', 'Order not found');
211
+ }
212
+
213
+ return [
214
+ 'order' => $order,
215
+ 'total' => $order->total,
216
+ 'currency' => $order->currency,
217
+ 'status' => $order->status
218
+ ];
219
+ }
220
+
221
+ public function fields()
222
+ {
223
+ // Return settings fields for admin configuration page
224
+ return $this->settings->getFields();
225
+ }
226
+
227
+ private function processPayment($paymentData)
228
+ {
229
+ // Implement your gateway's payment processing logic
230
+ $api = new YourGatewayAPI($this->settings);
231
+ return $api->createPayment($paymentData);
232
+ }
233
+
234
+ private function processWebhook($webhookData)
235
+ {
236
+ // Route webhook event to appropriate handler
237
+ $orderId = $webhookData['order_id'];
238
+ $status = $webhookData['status'];
239
+
240
+ $order = Order::where('uuid', $orderId)->first();
241
+
242
+ if ($order) {
243
+ $this->updateOrderStatus($order, $status);
244
+ }
245
+ }
246
+ }
247
+ ```
248
+
249
+ #### 3. Create Gateway Settings
250
+
251
+ ```php
252
+ <?php
253
+ namespace FluentCart\App\Modules\PaymentMethods\YourGateway\Settings;
254
+
255
+ use FluentCart\App\Modules\PaymentMethods\Core\BaseGatewaySettings;
256
+
257
+ class YourGatewaySettings extends BaseGatewaySettings
258
+ {
259
+ public function getFields(): array
260
+ {
261
+ // Define admin settings fields for the gateway configuration page
262
+ return [
263
+ 'is_active' => [
264
+ 'type' => 'yes_no',
265
+ 'label' => __('Enable Your Gateway', 'fluent-cart'),
266
+ 'default' => 'no',
267
+ 'description' => __('Enable this payment method', 'fluent-cart')
268
+ ],
269
+ 'api_key' => [
270
+ 'type' => 'text',
271
+ 'label' => __('API Key', 'fluent-cart'),
272
+ 'required' => true,
273
+ 'description' => __('Your gateway API key', 'fluent-cart')
274
+ ],
275
+ 'secret_key' => [
276
+ 'type' => 'password',
277
+ 'label' => __('Secret Key', 'fluent-cart'),
278
+ 'required' => true,
279
+ 'description' => __('Your gateway secret key', 'fluent-cart')
280
+ ],
281
+ 'webhook_secret' => [
282
+ 'type' => 'password',
283
+ 'label' => __('Webhook Secret', 'fluent-cart'),
284
+ 'description' => __('Webhook secret for signature verification', 'fluent-cart')
285
+ ],
286
+ 'test_mode' => [
287
+ 'type' => 'yes_no',
288
+ 'label' => __('Test Mode', 'fluent-cart'),
289
+ 'default' => 'yes',
290
+ 'description' => __('Enable test mode for development', 'fluent-cart')
291
+ ],
292
+ 'debug_mode' => [
293
+ 'type' => 'yes_no',
294
+ 'label' => __('Debug Mode', 'fluent-cart'),
295
+ 'default' => 'no',
296
+ 'description' => __('Enable debug logging', 'fluent-cart')
297
+ ]
298
+ ];
299
+ }
300
+
301
+ public function getDefaultSettings(): array
302
+ {
303
+ // Default values for all settings fields
304
+ return [
305
+ 'is_active' => 'no',
306
+ 'api_key' => '',
307
+ 'secret_key' => '',
308
+ 'webhook_secret' => '',
309
+ 'test_mode' => 'yes',
310
+ 'debug_mode' => 'no'
311
+ ];
312
+ }
313
+ }
314
+ ```
315
+
316
+ #### 4. Create API Communication Class
317
+
318
+ ```php
319
+ <?php
320
+ namespace FluentCart\App\Modules\PaymentMethods\YourGateway\API;
321
+
322
+ use FluentCart\App\Modules\PaymentMethods\YourGateway\Settings\YourGatewaySettings;
323
+
324
+ class YourGatewayAPI
325
+ {
326
+ private $settings;
327
+ private $baseUrl;
328
+ private $headers;
329
+
330
+ public function __construct(YourGatewaySettings $settings)
331
+ {
332
+ $this->settings = $settings;
333
+
334
+ // Switch between test and live API endpoints
335
+ $this->baseUrl = $settings->get('test_mode') === 'yes'
336
+ ? 'https://api-test.yourgateway.com'
337
+ : 'https://api.yourgateway.com';
338
+
339
+ // Set authorization and content type headers
340
+ $this->headers = [
341
+ 'Authorization' => 'Bearer ' . $settings->get('api_key'),
342
+ 'Content-Type' => 'application/json',
343
+ 'Accept' => 'application/json'
344
+ ];
345
+ }
346
+
347
+ public function createPayment($paymentData)
348
+ {
349
+ // Send payment creation request to gateway API
350
+ $response = wp_remote_post($this->baseUrl . '/payments', [
351
+ 'headers' => $this->headers,
352
+ 'body' => json_encode($paymentData),
353
+ 'timeout' => 30
354
+ ]);
355
+
356
+ // Handle WordPress HTTP errors
357
+ if (is_wp_error($response)) {
358
+ return [
359
+ 'success' => false,
360
+ 'error_message' => $response->get_error_message()
361
+ ];
362
+ }
363
+
364
+ // Parse and return gateway response
365
+ $body = wp_remote_retrieve_body($response);
366
+ $data = json_decode($body, true);
367
+
368
+ if ($data['status'] === 'success') {
369
+ return [
370
+ 'success' => true,
371
+ 'payment_id' => $data['payment_id'],
372
+ 'redirect_url' => $data['redirect_url']
373
+ ];
374
+ }
375
+
376
+ return [
377
+ 'success' => false,
378
+ 'error_message' => $data['error_message']
379
+ ];
380
+ }
381
+
382
+ public function getPaymentStatus($paymentId)
383
+ {
384
+ // Query the gateway for current payment status
385
+ $response = wp_remote_get($this->baseUrl . '/payments/' . $paymentId, [
386
+ 'headers' => $this->headers,
387
+ 'timeout' => 30
388
+ ]);
389
+
390
+ if (is_wp_error($response)) {
391
+ return false;
392
+ }
393
+
394
+ $body = wp_remote_retrieve_body($response);
395
+ return json_decode($body, true);
396
+ }
397
+
398
+ public function refundPayment($paymentId, $amount, $reason = '')
399
+ {
400
+ // Send refund request to gateway API
401
+ $refundData = [
402
+ 'amount' => $amount,
403
+ 'reason' => $reason
404
+ ];
405
+
406
+ $response = wp_remote_post($this->baseUrl . '/payments/' . $paymentId . '/refund', [
407
+ 'headers' => $this->headers,
408
+ 'body' => json_encode($refundData),
409
+ 'timeout' => 30
410
+ ]);
411
+
412
+ if (is_wp_error($response)) {
413
+ return false;
414
+ }
415
+
416
+ $body = wp_remote_retrieve_body($response);
417
+ return json_decode($body, true);
418
+ }
419
+ }
420
+ ```
421
+
422
+ #### 5. Create Webhook Handler
423
+
424
+ ```php
425
+ <?php
426
+ namespace FluentCart\App\Modules\PaymentMethods\YourGateway\Webhook;
427
+
428
+ use FluentCart\App\Models\Order;
429
+ use FluentCart\App\Models\OrderTransaction;
430
+ use FluentCart\App\Services\PaymentHelper;
431
+
432
+ class WebhookHandler
433
+ {
434
+ private $settings;
435
+
436
+ public function __construct($settings)
437
+ {
438
+ $this->settings = $settings;
439
+ }
440
+
441
+ public function handleWebhook()
442
+ {
443
+ // Read incoming webhook payload
444
+ $webhookData = $this->getWebhookData();
445
+
446
+ // Verify signature before processing
447
+ if (!$this->verifyWebhookSignature($webhookData)) {
448
+ http_response_code(400);
449
+ exit('Invalid signature');
450
+ }
451
+
452
+ // Process the verified webhook event
453
+ $this->processWebhook($webhookData);
454
+
455
+ http_response_code(200);
456
+ exit('OK');
457
+ }
458
+
459
+ private function getWebhookData()
460
+ {
461
+ // Read raw POST body from gateway
462
+ $input = file_get_contents('php://input');
463
+ return json_decode($input, true);
464
+ }
465
+
466
+ private function verifyWebhookSignature($webhookData)
467
+ {
468
+ // Compare HMAC signature from header with computed signature
469
+ $signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
470
+ $secret = $this->settings->get('webhook_secret');
471
+
472
+ $expectedSignature = hash_hmac('sha256', json_encode($webhookData), $secret);
473
+
474
+ return hash_equals($expectedSignature, $signature);
475
+ }
476
+
477
+ private function processWebhook($webhookData)
478
+ {
479
+ // Route event to appropriate handler based on event type
480
+ $eventType = $webhookData['event_type'];
481
+ $paymentId = $webhookData['payment_id'];
482
+ $orderId = $webhookData['order_id'];
483
+
484
+ $order = Order::where('uuid', $orderId)->first();
485
+
486
+ if (!$order) {
487
+ return;
488
+ }
489
+
490
+ switch ($eventType) {
491
+ case 'payment.completed':
492
+ $this->handlePaymentCompleted($order, $webhookData);
493
+ break;
494
+
495
+ case 'payment.failed':
496
+ $this->handlePaymentFailed($order, $webhookData);
497
+ break;
498
+
499
+ case 'payment.refunded':
500
+ $this->handlePaymentRefunded($order, $webhookData);
501
+ break;
502
+ }
503
+ }
504
+
505
+ private function handlePaymentCompleted($order, $webhookData)
506
+ {
507
+ // Mark order as completed and paid
508
+ $order->update([
509
+ 'status' => 'completed',
510
+ 'payment_status' => 'paid'
511
+ ]);
512
+
513
+ // Create transaction record for audit trail
514
+ OrderTransaction::create([
515
+ 'order_id' => $order->id,
516
+ 'transaction_id' => $webhookData['payment_id'],
517
+ 'type' => 'payment',
518
+ 'status' => 'completed',
519
+ 'amount' => $webhookData['amount'],
520
+ 'currency' => $webhookData['currency'],
521
+ 'gateway' => 'your_gateway',
522
+ 'gateway_response' => json_encode($webhookData)
523
+ ]);
524
+
525
+ // Trigger payment success action for other listeners
526
+ do_action('fluent_cart/payment_success', [
527
+ 'order' => $order,
528
+ 'gateway' => 'your_gateway',
529
+ 'transaction_id' => $webhookData['payment_id']
530
+ ]);
531
+ }
532
+
533
+ private function handlePaymentFailed($order, $webhookData)
534
+ {
535
+ // Mark order and payment as failed
536
+ $order->update([
537
+ 'status' => 'failed',
538
+ 'payment_status' => 'failed'
539
+ ]);
540
+
541
+ // Trigger payment failed action for error handling listeners
542
+ do_action('fluent_cart/payment_failed', [
543
+ 'order' => $order,
544
+ 'gateway' => 'your_gateway',
545
+ 'error_message' => $webhookData['error_message']
546
+ ]);
547
+ }
548
+
549
+ private function handlePaymentRefunded($order, $webhookData)
550
+ {
551
+ // Create refund transaction record
552
+ OrderTransaction::create([
553
+ 'order_id' => $order->id,
554
+ 'transaction_id' => $webhookData['refund_id'],
555
+ 'type' => 'refund',
556
+ 'status' => 'completed',
557
+ 'amount' => $webhookData['refund_amount'],
558
+ 'currency' => $webhookData['currency'],
559
+ 'gateway' => 'your_gateway',
560
+ 'gateway_response' => json_encode($webhookData)
561
+ ]);
562
+
563
+ // Trigger refund action for post-refund processing
564
+ do_action('fluent_cart/payment_refunded', [
565
+ 'order' => $order,
566
+ 'gateway' => 'your_gateway',
567
+ 'refund_id' => $webhookData['refund_id'],
568
+ 'refund_amount' => $webhookData['refund_amount']
569
+ ]);
570
+ }
571
+ }
572
+ ```
573
+
574
+ ---
575
+
576
+ ## Gateway Registration
577
+
578
+ ### Register Your Gateway
579
+
580
+ ```php
581
+ // In your plugin's main file or module initialization
582
+ add_action('fluentcart_loaded', function($app) {
583
+ // Register gateway with the central GatewayManager
584
+ $gatewayManager = \FluentCart\App\Modules\PaymentMethods\Core\GatewayManager::getInstance();
585
+ $gatewayManager->register('your_gateway', new \FluentCart\App\Modules\PaymentMethods\YourGateway\YourGateway());
586
+ });
587
+ ```
588
+
589
+ ### Gateway Configuration
590
+
591
+ ```php
592
+ // Get gateway settings
593
+ $gateway = GatewayManager::gateway('your_gateway');
594
+ $settings = $gateway->settings;
595
+
596
+ // Check if gateway is enabled
597
+ $isEnabled = $gateway->settings->get('is_active') === 'yes';
598
+
599
+ // Get gateway meta information
600
+ $meta = $gateway->meta();
601
+ ```
602
+
603
+ ---
604
+
605
+ ## Payment Processing Flow
606
+
607
+ ### 1. Payment Initiation
608
+
609
+ ```php
610
+ // Create payment instance with order and transaction data
611
+ $paymentInstance = new PaymentInstance([
612
+ 'order' => $order,
613
+ 'transaction' => $transaction,
614
+ 'gateway' => 'your_gateway'
615
+ ]);
616
+
617
+ // Process payment through the gateway
618
+ $gateway = GatewayManager::gateway('your_gateway');
619
+ $result = $gateway->makePaymentFromPaymentInstance($paymentInstance);
620
+ ```
621
+
622
+ ### 2. Payment Response Handling
623
+
624
+ ```php
625
+ if ($result['success']) {
626
+ // Redirect customer to payment page
627
+ wp_redirect($result['redirect_url']);
628
+ exit;
629
+ } else {
630
+ // Handle payment error and display to customer
631
+ wc_add_notice($result['message'], 'error');
632
+ }
633
+ ```
634
+
635
+ ### 3. Webhook Processing
636
+
637
+ ```php
638
+ // Webhook endpoint: /wp-ajax/your_gateway_webhook
639
+ public function handleWebhook()
640
+ {
641
+ $webhookHandler = new WebhookHandler($this->settings);
642
+ $webhookHandler->handleWebhook();
643
+ }
644
+ ```
645
+
646
+ ---
647
+
648
+ ## Gateway Features
649
+
650
+ ### Supported Features
651
+
652
+ | Category | Features |
653
+ |----------|----------|
654
+ | **Payment Processing** | One-time payments, Recurring payments (subscriptions), Payment method storage, Payment method updates |
655
+ | **Refund Management** | Full refunds, Partial refunds, Refund status tracking, Refund notifications |
656
+ | **Webhook Handling** | Real-time payment notifications, Signature verification, Event processing, Error handling |
657
+ | **Security Features** | API key management, Webhook signature verification, Test mode support, Debug logging |
658
+
659
+ ### Feature Implementation
660
+
661
+ #### Subscription Support
662
+
663
+ ```php
664
+ class YourGateway extends AbstractPaymentGateway
665
+ {
666
+ public function __construct()
667
+ {
668
+ // Pass subscription module to enable recurring payment support
669
+ parent::__construct(
670
+ new YourGatewaySettings(),
671
+ new YourGatewaySubscriptions() // Add subscription support
672
+ );
673
+ }
674
+
675
+ public array $supportedFeatures = [
676
+ 'payment',
677
+ 'refund',
678
+ 'webhook',
679
+ 'subscriptions' // Enable subscription feature
680
+ ];
681
+ }
682
+ ```
683
+
684
+ #### Refund Support
685
+
686
+ ```php
687
+ public function processRefund($transaction, $amount, $args = [])
688
+ {
689
+ // Send refund request to gateway API
690
+ $api = new YourGatewayAPI($this->settings);
691
+ $result = $api->refundPayment($transaction->transaction_id, $amount);
692
+
693
+ if ($result['success']) {
694
+ return [
695
+ 'success' => true,
696
+ 'refund_id' => $result['refund_id']
697
+ ];
698
+ }
699
+
700
+ return new \WP_Error('refund_failed', $result['error_message']);
701
+ }
702
+ ```
703
+
704
+ ---
705
+
706
+ ## Testing and Debugging
707
+
708
+ ### Test Mode Configuration
709
+
710
+ ```php
711
+ // Enable test mode in settings
712
+ $settings = [
713
+ 'test_mode' => 'yes',
714
+ 'debug_mode' => 'yes'
715
+ ];
716
+ ```
717
+
718
+ ### Debug Logging
719
+
720
+ ```php
721
+ public function logDebug($message, $data = [])
722
+ {
723
+ // Only log when debug mode is enabled
724
+ if ($this->settings->get('debug_mode') === 'yes') {
725
+ error_log('YourGateway: ' . $message . ' - ' . json_encode($data));
726
+ }
727
+ }
728
+ ```
729
+
730
+ ### Testing Webhooks
731
+
732
+ ```php
733
+ // Test webhook locally using ngrok or similar
734
+ $webhookUrl = 'https://your-ngrok-url.ngrok.io/wp-ajax/your_gateway_webhook';
735
+
736
+ // Send test webhook payload
737
+ $testData = [
738
+ 'event_type' => 'payment.completed',
739
+ 'payment_id' => 'test_payment_123',
740
+ 'order_id' => 'test_order_456',
741
+ 'amount' => 1000,
742
+ 'currency' => 'USD'
743
+ ];
744
+
745
+ wp_remote_post($webhookUrl, [
746
+ 'body' => json_encode($testData),
747
+ 'headers' => [
748
+ 'Content-Type' => 'application/json',
749
+ 'X-Webhook-Signature' => $this->generateSignature($testData)
750
+ ]
751
+ ]);
752
+ ```
753
+
754
+ ---
755
+
756
+ ## Related Documentation
757
+
758
+ - [Shipping Module](shipping-storage-licensing.md) - Shipping method development
759
+ - [Modules Overview](modules-and-extensions-reference.md) - Back to modules overview
760
+ - [Database Models](database-models-reference.md) - Data model documentation
761
+ - [REST API](rest-api-reference.md) - API endpoints reference