Skip to content

Commit e8024e8

Browse files
author
Lalit Swain
committed
docs: Improve Flow Integration Details section for better readability
- Add step-by-step payment flow explanation - Expand key features with detailed explanations - Add payment flow diagram - Add technical architecture overview - Make content more accessible and understandable
1 parent 92d8241 commit e8024e8

File tree

1 file changed

+174
-18
lines changed

1 file changed

+174
-18
lines changed

‎README.md‎

Lines changed: 174 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -52,24 +52,180 @@ Checkout.com Payment Gateway plugin for WooCommerce with Flow integration suppor
5252

5353
## Flow Integration Details
5454

55-
### How It Works
56-
57-
1. **Order Creation**: Order is created via AJAX before payment processing
58-
2. **Payment Session**: Payment session is created with Checkout.com
59-
3. **Flow Component**: Flow Web Component is mounted and validated
60-
4. **Payment Processing**: Payment is processed through Flow
61-
5. **Webhook Handling**: Payment status updates are received via webhooks
62-
6. **Order Update**: Order status is automatically updated based on payment result
63-
64-
### Key Features
65-
66-
- **Early Order Creation**: Orders are created before payment to ensure webhook matching
67-
- **Client-Side Validation**: Flow component validation before submission
68-
- **Server-Side Validation**: Comprehensive validation on the server
69-
- **Duplicate Prevention**: Prevents duplicate order creation
70-
- **Webhook Queue**: Handles webhooks even if order isn't immediately found
71-
- **3DS Support**: Full 3D Secure authentication flow
72-
- **Saved Cards**: Secure tokenization and card saving
55+
### Overview
56+
57+
The Flow integration provides a modern, secure payment experience using Checkout.com's Flow Web Components. This integration ensures reliable payment processing with comprehensive validation, webhook handling, and order management.
58+
59+
### How Flow Integration Works
60+
61+
The payment flow follows these steps:
62+
63+
#### Step 1: Checkout Page Load
64+
- Customer fills out billing and shipping information
65+
- Flow payment method is selected
66+
- Flow Web Component is initialized and mounted
67+
68+
#### Step 2: Order Creation (Before Payment)
69+
- **Why Early?** Orders are created via AJAX before payment processing begins
70+
- This ensures the order exists in the database for webhook matching
71+
- Order status: `Pending payment`
72+
- Payment session ID is stored with the order
73+
74+
#### Step 3: Payment Session Creation
75+
- Payment session is created with Checkout.com API
76+
- Session includes order details, customer information, and amount
77+
- Payment session ID is returned and stored
78+
79+
#### Step 4: Flow Component Validation
80+
- **Client-Side Validation**: Flow component validates card details in real-time
81+
- Card number, expiry, CVV are validated before submission
82+
- Invalid cards are rejected before payment attempt
83+
84+
#### Step 5: Payment Processing
85+
- Customer submits payment through Flow component
86+
- Payment is processed securely through Checkout.com
87+
- For 3D Secure: Customer is redirected for authentication
88+
- Payment result is returned
89+
90+
#### Step 6: Webhook Processing
91+
- Checkout.com sends webhook with payment status
92+
- Webhook is matched to order using:
93+
1. Order ID from metadata (primary)
94+
2. Payment Session ID + Payment ID (secondary)
95+
3. Payment ID alone (fallback)
96+
- If order not found immediately, webhook is queued for later processing
97+
98+
#### Step 7: Order Status Update
99+
- Order status is automatically updated based on payment result:
100+
- ✅ **Payment Approved** → Order status: `Processing`
101+
- ✅ **Payment Captured** → Order status: `Processing` (if not already)
102+
- ❌ **Payment Declined** → Order status: `Failed`
103+
- ⏸️ **Payment Cancelled** → Order status: `Cancelled`
104+
105+
### Key Features Explained
106+
107+
#### 🔒 Early Order Creation
108+
**What it does:** Creates the WooCommerce order before payment processing begins.
109+
110+
**Why it's important:**
111+
- Ensures webhooks can always find the order
112+
- Prevents webhook matching failures
113+
- Allows order tracking throughout the payment process
114+
115+
**How it works:**
116+
- Order is created via AJAX when customer clicks "Place Order"
117+
- Order is saved with `Pending payment` status
118+
- Payment session ID is stored for webhook matching
119+
120+
#### ✅ Dual Validation System
121+
**Client-Side Validation:**
122+
- Flow component validates card details in real-time
123+
- Prevents invalid cards from being submitted
124+
- Provides instant feedback to customers
125+
126+
**Server-Side Validation:**
127+
- Comprehensive validation of all checkout fields
128+
- Validates billing/shipping addresses
129+
- Ensures data integrity before order creation
130+
- Blocks order creation if validation fails
131+
132+
#### 🚫 Duplicate Prevention
133+
**Problem:** Multiple clicks or slow networks can cause duplicate orders.
134+
135+
**Solution:**
136+
- Client-side lock prevents multiple simultaneous requests
137+
- Server-side check prevents duplicate orders with same payment session ID
138+
- If duplicate detected, existing order is returned instead of creating new one
139+
140+
#### 📬 Webhook Queue System
141+
**Problem:** Webhooks might arrive before order is fully saved to database.
142+
143+
**Solution:**
144+
- Webhook queue temporarily stores webhooks if order not found
145+
- Queue is processed when order becomes available
146+
- Ensures no webhooks are lost
147+
- Automatic retry mechanism
148+
149+
#### 🔐 3D Secure (3DS) Support
150+
**How it works:**
151+
1. Payment requires 3DS authentication
152+
2. Customer is redirected to bank's 3DS page
153+
3. Customer completes authentication
154+
4. Customer is redirected back to store
155+
5. Payment status is confirmed via webhook
156+
6. Order status is updated accordingly
157+
158+
**Features:**
159+
- Automatic 3DS detection
160+
- Seamless redirect flow
161+
- Webhook handling after 3DS return
162+
- Prevents duplicate status updates
163+
164+
#### 💳 Saved Cards
165+
**How it works:**
166+
1. Customer opts to save card during checkout
167+
2. Card is tokenized securely by Checkout.com
168+
3. Token is stored in customer's account
169+
4. Saved cards appear on future checkouts
170+
5. Customer can select saved card for quick checkout
171+
172+
**Security:**
173+
- Cards are never stored on your server
174+
- Only secure tokens are stored
175+
- PCI compliance handled by Checkout.com
176+
- Cards can be deleted by customer
177+
178+
### Payment Flow Diagram
179+
180+
```
181+
Customer Checkout
182+
↓
183+
Fill Billing/Shipping Info
184+
↓
185+
Select Flow Payment Method
186+
↓
187+
Click "Place Order"
188+
↓
189+
[VALIDATION] Client-Side + Server-Side
190+
↓
191+
[ORDER CREATED] Status: Pending payment
192+
↓
193+
Create Payment Session with Checkout.com
194+
↓
195+
[FLOW COMPONENT] Card Details Entered
196+
↓
197+
[VALIDATION] Flow Component Validates Card
198+
↓
199+
Submit Payment
200+
↓
201+
[3DS?] If Required → Redirect → Authenticate → Return
202+
↓
203+
Payment Processed
204+
↓
205+
[WEBHOOK] Payment Status Received
206+
↓
207+
Match Webhook to Order
208+
↓
209+
Update Order Status
210+
↓
211+
[COMPLETE] Order Status: Processing/Failed
212+
```
213+
214+
### Technical Architecture
215+
216+
#### Frontend (JavaScript)
217+
- **payment-session.js**: Handles order creation, payment session, Flow component integration
218+
- **flow-container.js**: Manages Flow component container and initialization
219+
- **flow-customization.js**: Customizes Flow component appearance and behavior
220+
221+
#### Backend (PHP)
222+
- **class-wc-gateway-checkout-com-flow.php**: Main gateway class, handles payment processing
223+
- **Webhook Handler**: Processes incoming webhooks and updates orders
224+
- **Webhook Queue**: Manages webhook queuing system
225+
226+
#### Database
227+
- Order meta stores: Payment Session ID, Payment ID, Webhook IDs
228+
- Webhook queue table: Temporary storage for unmatched webhooks
73229

74230
## Webhook Configuration
75231

0 commit comments

Comments
 (0)