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.
- package/.gitattributes +2 -0
- package/CLAUDE.md +22 -0
- package/CONTRIBUTING.md +73 -0
- package/LICENSE +21 -0
- package/README.md +127 -0
- package/SKILL.md +127 -0
- package/bin/index.js +281 -0
- package/copy-skills.js +43 -0
- package/package.json +38 -0
- package/skills/fluentcart-developer/SKILL.md +172 -0
- package/skills/fluentcart-developer/examples/README.md +25 -0
- package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -0
- package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -0
- package/skills/fluentcart-developer/examples/sample-custom-addon/fluentcart-custom-addon.php +114 -0
- package/skills/fluentcart-developer/examples/sample-custom-payment-gateway/fluentcart-custom-gateway-example.php +149 -0
- package/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -0
- package/skills/fluentcart-developer/examples/sample-shipping-carrier/fluentcart-custom-shipping-carrier.php +62 -0
- package/skills/fluentcart-developer/references/action-hooks-admin-templates.md +787 -0
- package/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -0
- package/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -0
- package/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -0
- package/skills/fluentcart-developer/references/action-hooks-orders.md +631 -0
- package/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -0
- package/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -0
- package/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -0
- package/skills/fluentcart-developer/references/database-models-query-builder.md +194 -0
- package/skills/fluentcart-developer/references/database-models-reference.md +604 -0
- package/skills/fluentcart-developer/references/database-schema-reference.md +940 -0
- package/skills/fluentcart-developer/references/engineering-notes.md +154 -0
- package/skills/fluentcart-developer/references/fee-system-guide.md +449 -0
- package/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -0
- package/skills/fluentcart-developer/references/filter-hooks-customers-subscriptions.md +902 -0
- package/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -0
- package/skills/fluentcart-developer/references/filter-hooks-orders-payments.md +1319 -0
- package/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -0
- package/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -0
- package/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -0
- package/skills/fluentcart-developer/references/ghost-product-selling.md +458 -0
- package/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -0
- package/skills/fluentcart-developer/references/paddle-gateway-case-study.md +1925 -0
- package/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -0
- package/skills/fluentcart-developer/references/rest-api-checkout.md +286 -0
- package/skills/fluentcart-developer/references/rest-api-coupons.md +794 -0
- package/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -0
- package/skills/fluentcart-developer/references/rest-api-customers.md +1121 -0
- package/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -0
- package/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -0
- package/skills/fluentcart-developer/references/rest-api-files.md +290 -0
- package/skills/fluentcart-developer/references/rest-api-integrations.md +324 -0
- package/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -0
- package/skills/fluentcart-developer/references/rest-api-licensing.md +171 -0
- package/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -0
- package/skills/fluentcart-developer/references/rest-api-orders.md +1241 -0
- package/skills/fluentcart-developer/references/rest-api-overview.md +131 -0
- package/skills/fluentcart-developer/references/rest-api-products.md +2563 -0
- package/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -0
- package/skills/fluentcart-developer/references/rest-api-reference.md +552 -0
- package/skills/fluentcart-developer/references/rest-api-reports.md +377 -0
- package/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -0
- package/skills/fluentcart-developer/references/rest-api-settings.md +528 -0
- package/skills/fluentcart-developer/references/rest-api-shipping.md +800 -0
- package/skills/fluentcart-developer/references/rest-api-subscriptions.md +606 -0
- package/skills/fluentcart-developer/references/rest-api-tax.md +356 -0
- package/skills/fluentcart-developer/references/subscription-customization.md +197 -0
- package/skills/fluentcart-developer/scripts/cli.js +1 -0
- 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
|