WPKJ Payment Gateway for FluentCart with Alipay

WPKJ Payment Gateway for FluentCart with Alipay is a feature-rich, enterprise-grade payment gateway that seamlessly integrates Alipay with FluentCart. It intelligently detects user environments and automatically selects the optimal payment interface.

Key Features

• Multi-Platform Payment Support

  • PC Web Payment for desktop browsers
  • Mobile WAP Payment for mobile browsers
  • Face-to-Face Payment with QR codes
  • Alipay App Payment for native experience [Not yet completed]

• Advanced Subscription Management

  • Automatic Renewal via Alipay Recurring Agreement
  • Manual Renewal fallback mode
  • Trial period support (0-365 days)
  • Flexible billing intervals (daily, weekly, monthly, yearly)
  • Limited and unlimited billing cycles
  • Subscription cancellation sync with orders

• Comprehensive Refund System

  • Automatic refunds when orders are cancelled
  • Manual refund processing from admin
  • Full and partial refund support
  • Detailed activity logging

• Enterprise Security

  • RSA2 2048-bit encryption
  • Signature verification for all requests
  • HTTPS/SSL required for production
  • Webhook validation
  • Amount verification

• International & Multi-Currency

  • 14+ currencies supported
  • Full internationalization (i18n) ready
  • Translation template (POT) included
  • Built-in Chinese & English translations

Supported Currencies

CNY (Chinese Yuan), USD, EUR, GBP, HKD, JPY, KRW, SGD, AUD, CAD, CHF, NZD, THB, MYR

Requirements

• FluentCart 1.2.0 or higher
• WordPress 6.5 or higher
• PHP 8.2 or higher
• SSL Certificate (HTTPS) for production
• Alipay merchant account

Developer Friendly

• Clean PSR-4 autoloading architecture
• Comprehensive hooks and filters
• Debug logging support
• Sandbox/Test mode
• Extensive documentation

Support and Documentation

For comprehensive documentation, tutorials, and support:

• Official Website: https://www.wpdaxue.com
• Documentation: https://www.wpdaxue.com/wpkj-alipay-gateway-for-fluentcart.html
• Support Email: [email protected]
• GitHub: Report issues and contribute

Privacy and Data

This plugin does NOT:
– Collect any user data
– Send data to third parties (except Alipay for payment processing)
– Track users
– Store sensitive payment information

Payment data is transmitted securely via HTTPS directly to Alipay’s servers. The plugin only stores transaction IDs and order metadata necessary for order fulfillment.

External Services

This plugin relies on external services for payment processing. Below is documentation for each external service:

Alipay Payment Gateway (Production)

Service: Alipay Payment Gateway API
What it is: Official payment processing service operated by Alipay, a leading Chinese payment platform
What it’s used for: Process online payments from customers using Alipay accounts
Data sent: Order ID, order amount, customer email, payment description/subject, currency, and timeout configuration
When it’s sent: When a customer initiates a payment and selects Alipay as the payment method
Data sent to: Alipay servers (https://openapi.alipay.com/gateway.do for production)
Terms of Service: https://render.alipay.com/p/yuyan/180020010001196791/preview.html?agreementId=AG00000006
Privacy Policy: https://render.alipay.com/p/yuyan/180020010001196791/preview.html?agreementId=AG00000132
Additional Info: Communication is RSA2 2048-bit encrypted. Alipay returns trade status, transaction ID, and buyer information

Alipay Sandbox API (Testing)

Service: Alipay Sandbox API
What it is: Test environment provided by Alipay for merchants to test payment integration before going live
What it’s used for: Process test/sandbox payments when the plugin is in test mode
Data sent: Same as production (Order ID, amount, email, subject, currency, timeout)
When it’s sent: When plugin is configured in test mode and customer initiates a test payment
Data sent to: Alipay sandbox servers (https://openapi-sandbox.dl.alipaydev.com/gateway.do)
Terms of Service: https://render.alipay.com/p/yuyan/180020010001196791/preview.html?agreementId=AG00000006
Privacy Policy: https://render.alipay.com/p/yuyan/180020010001196791/preview.html?agreementId=AG00000132
Additional Info: Uses separate test credentials from production

User Consent

Users are informed about Alipay payment processing when they select Alipay as their payment method. They accept data transmission to Alipay’s services as part of the payment process. The Alipay terms and privacy policy are accessible via links above.

Credits

• Developed by: WPDAXUE.COM
• Contributors: WordPress community
• Framework: FluentCart Payment Gateway API
• Special Thanks: FluentCart team for excellent payment framework, and Alipay for their robust payment solution

Automatic Installation

1. Log in to your WordPress admin panel
2. Navigate to Plugins > Add New
3. Search for “WPKJ Payment Gateway for FluentCart with Alipay”
4. Click “Install Now” and then “Activate”
5. Go to FluentCart > Settings > Payment Methods
6. Configure your Alipay credentials

Manual Installation

1. Download the plugin ZIP file
2. Upload to /wp-content/plugins/wpkj-fluentcart-alipay-payment/
3. Activate through the ‘Plugins’ menu in WordPress
4. Navigate to FluentCart > Settings > Payment Methods
5. Configure Alipay gateway settings
6. Enable the payment method

Configuration Steps

1. Obtain Credentials from Alipay:

   • Register at Alipay Open Platform
   • Create a new application
   • Generate RSA2 key pair
   • Upload public key to Alipay
   • Get your 16-digit App ID
   • Copy Alipay’s public key

2. Configure Plugin Settings:

   • Enter App ID, Private Key, and Alipay Public Key
   • Configure Notify URL in Alipay dashboard
   • Enable auto-refund (optional)
   • Enable Face-to-Face payment (optional)
   • For subscriptions: Enter Personal Product Code

3. Test Your Setup:

   • Use sandbox mode for testing
   • Make a test purchase
   • Verify webhook notifications
   • Test refund functionality

1. 

   Alipay payment gateway in FluentCart payment list

2. 

   Alipay payment gateway settings page with all configuration options

3. 

   Payment method selection during checkout

4. 

   Desktop Face-to-Face QR code payment page

5. 

   Payment receipt

1.1.0

Release Date: November 29, 2025

• Update: Plugin name changed to “WPKJ Payment Gateway for FluentCart with Alipay”
• Update: Plugin author and copyright information updated to WPDAXUE.COM
• Update: All brand and link information adjusted in README and documentation
• Update: Version number synchronized to 1.1.0 with changelog
• Improvement: Plugin activation and dependency check prompt text corrected
• Improvement: Redundant code removed from text fields to simplify logic
• Update: Project name and author fields updated in language files

1.0.9

Release Date: November 12, 2025

• Security: Renamed nonce field to wpkj_alipay_f2f_nonce to prevent conflicts with other plugins
• Security: Updated nonce action name to wpkj_alipay_f2f_check_payment_status_nonce for better uniqueness
• Security: Removed external QR code generation via api.qrserver.com – now uses local QRCode.js library only
• Security: Renamed POST field from generic nonce to wpkj_alipay_f2f_nonce in Face-to-Face payment AJAX handler
• Security: Added phpcs annotations for webhook nonce verification exceptions (Alipay server requests don’t require WordPress nonce)
• Security: Changed wp_redirect() to wp_safe_redirect() in FaceToFacePageHandler to prevent malicious redirects
• Improvement: Optimized POST data processing in webhook handler – now only extracts required fields
• Improvement: Refined Alipay notification field handling for better security and reduced data exposure
• Improvement: Removed unused webhook fields (send_pay_date, gmt_create) – only processes necessary fields
• Improvement: Updated NotifyHandler to only handle essential Alipay notification fields
• Fixed: Corrected required fields list in webhook notification processing
• Fixed: Logger::debug() method call replaced with Logger::info() in OrderCancelListener and TransactionHelper
• Fixed: Plugin directory name updated to wpkj-alipay-gateway-for-fluentcart to match WordPress.org slug
• Refactoring: PaymentStatusChecker nonce verification now uses unique field and action names
• Refactoring: FaceToFacePageHandler nonce generation updated to match new naming convention
• Refactoring: JavaScript Face-to-Face payment handler uses new nonce field name
• Compliance: All changes comply with WordPress.org plugin directory standards and security guidelines
• Note: Nonce field renamed in multiple files: PaymentStatusChecker.php, FaceToFacePageHandler.php, face-to-face-payment.js
• Note: NotifyHandler.php updated with proper phpcs annotations for webhook data handling
• Note: No functional impact – only security and naming improvements

1.0.8

Release Date: October 23, 2025

• New: Added Custom Payment API for external system integration
• New: REST API endpoints for programmatically creating payment orders
• New: Support for one-time and subscription payments via API
• New: Payment status query API endpoint
• New: Comprehensive API documentation with usage examples
• Enhancement: Customizable permission checks for API access
• Enhancement: Detailed logging for custom payment operations
• Documentation: Added CUSTOM_PAYMENT_USAGE.md with complete API guide
• Documentation: All documentation moved to docs/ directory for better organization
• Documentation: README.md retained in root for GitHub, readme.txt for WordPress.org
• Security: All exception messages properly escaped with phpcs annotations
• Security: Example code properly annotated for demonstration purposes

1.0.7

Release Date: October 23, 2025

• Fixed: Critical issue where next_billing_date was not set for initial subscription payments
• Fixed: Subscription renewal not triggering due to missing next billing date
• Fixed: Next billing date not set after recurring agreement sign success
• Fixed: Critical issue where bill_count was not properly calculated for subscriptions
• Fixed: Initial subscription payment showing bill_count as 0 instead of 1
• Fixed: Manual bill_count increment replaced with FluentCart’s automatic calculation
• Fixed: Auto-cancel subscription feature not working – was using wrong field to find subscription
• Fixed: OrderCancelListener now correctly uses Subscription->parent_order_id instead of Order->subscription_id
• Security: Enhanced duplicate refund prevention mechanism in automatic refund feature
• Security: Now checks ALL existing refunds instead of just first one to prevent duplicates
• Security: Added comprehensive logging for refund duplicate prevention
• Security: Validates original transaction UUID match before blocking duplicate refunds
• Refactoring: Migrated to FluentCart standard Refund service for all refund operations
• Refactoring: Simplified AlipayGateway processRefund() method to only handle API calls (~80% code reduction)
• Refactoring: Simplified RefundProcessor to use FluentCart’s transaction/order management (~60% code reduction)
• Refactoring: Created centralized SubscriptionService class eliminating ~240 lines of duplicate code
• Refactoring: NotifyHandler and PaymentStatusChecker now use shared subscription service
• Refactoring: Architecture now consistent with WeChat payment plugin
• Improved: FluentCart now handles all transaction creation, order updates, and event triggering
• Improved: Better separation of concerns – Gateway handles payment API, FluentCart handles business logic
• Improved: Added source tracking (webhook/polling) for better debugging
• Improved: Code maintainability with DRY principle – single source of truth for subscription and refund logic
• Improved: Initial subscription payment now properly sets next_billing_date using FluentCart’s guessNextBillingDate()
• Improved: Now using SubscriptionService::syncSubscriptionStates() to auto-calculate bill_count from database
• Improved: Proper EOT (End of Term) detection based on actual transaction count
• Improved: Enhanced logging for subscription billing date and bill_count updates
• Improved: Better handling of trial periods in next billing date calculation
• Improved: Order cancellation flow now properly identifies and cancels associated subscriptions
• Improved: Automatic refund now includes detailed security check logs
• Note: This fix ensures FluentCart’s cron system can properly schedule subscription renewals
• Note: bill_count is now automatically calculated by querying OrderTransaction records
• Note: Total code reduced by ~35 lines, duplicate code eliminated completely
• Note: In FluentCart, subscriptions are linked via Subscription->parent_order_id, not Order->subscription_id
• Note: Duplicate refund prevention protects against concurrent order cancellation operations

1.0.6

Release Date: October 23, 2025

• Added: TransactionHelper utility class for idempotency protection
• Added: Automatic retry mechanism for failed subscription renewals
• Added: WordPress Cron-based renewal retry scheduling
• Added: Comprehensive error handling and logging for renewals
• Improved: Subscription renewal process with FluentCart standard methods
• Improved: Exception message security with esc_html() escaping
• Improved: Timezone safety using gmdate() instead of date()
• Fixed: WordPress coding standards compliance
• Fixed: Translator comments for all placeholder strings
• Security: Enhanced XSS protection for all output
• Performance: Optimized transaction lookup and duplicate detection

1.0.5

Release Date: October 22, 2025

• Added: Translator comments for all placeholder strings
• Added: Comprehensive POT translation template
• Improved: Subscription cancellation sync with order cancellation
• Improved: UTF-8 encoding handling for Chinese characters
• Improved: Face-to-Face payment amount formatting
• Fixed: Order number display in payment subject
• Fixed: Multiple placeholder string ordering for proper translation
• Updated: Documentation with detailed configuration guide
• Performance: Optimized webhook processing

1.0.4

Release Date: October 21, 2025

• Added: Automatic subscription cancellation when parent order is cancelled
• Added: Configurable subscription cancellation behavior
• Improved: Recurring agreement handling
• Improved: Error messages and logging
• Fixed: Subscription status synchronization issues

1.0.3

Release Date: October 20, 2025

• Added: Face-to-Face QR code payment support
• Added: Enhanced mobile device detection
• Fixed: UTF-8 encoding issues with Chinese characters
• Fixed: Subject line truncation for long product names
• Improved: Payment page rendering performance

1.0.2

Release Date: October 18, 2025

• Added: Automatic refund feature
• Added: Refund activity logging
• Improved: Webhook security validation
• Fixed: Amount mismatch detection
• Fixed: Timezone issues with Beijing time

1.0.1

Release Date: October 16, 2025

• Added: Full subscription payment support
• Added: Recurring agreement integration
• Added: Trial period handling
• Improved: Error handling and logging
• Fixed: Cart session cleanup for repeat purchases

1.0.0

Release Date: October 15, 2025

• Initial release
• Multi-platform payment support (PC, Mobile, App)
• Automatic client detection
• Basic refund functionality
• Multi-currency support
• Test mode/Sandbox support
• Webhook notification handling
• i18n/l10n ready