payfast_flutter 0.0.2

Flutter SDK for PayFast payment gateway integration with WebView support.

0.1.0 Major SDK Improvement

✨ New Features

• Professional SDK API: Completely redesigned with clean, Stripe-like PayFast.startPayment() API
• PayFastConfig Class: Comprehensive configuration object with all customizable payment parameters:
  • Required: merchantId, securedKey, basketId, amount, successUrl, failureUrl, checkoutUrl
  • Optional: currency, txnDesc, customerEmail, customerMobile, environment, additionalDescription
• Enhanced PayFastResult: Added copyWith() method and toString() for better debugging
• Improved Error Handling: Better error messages and user feedback with loading dialogs
• Loading Dialog: Shows progress while requesting access token
• HTML Payment Form: Better-structured HTML with proper metadata and loading indicator
• API Endpoint Methods: getApiEndpoint() and toMap() helper methods in PayFastConfig
• Null Safety: Improved null safety throughout the SDK
• Backward Compatibility: Old PayFastService.getToken() still works (deprecated)

🔧 Improvements

• Code Documentation: Comprehensive docstrings for all public APIs
• Example App: Complete rewrite with multiple payment buttons and result display
• WebView Enhancements:
  • Better HTML structure with DOCTYPE and proper charset
  • Loading spinner and status messages
  • Improved error handling and logging
  • Better CSS styling
• Service Layer: Enhanced PayFastService with config-based approach
• Signature Generation: Added documentation to PayFastSignature
• Navigation: Improved context mounting checks and navigation safety

📚 Documentation

• README.md: Completely rewritten with:
  • Quick start guide (3 steps)
  • Comprehensive API reference
  • Advanced usage examples
  • Troubleshooting guide
  • FAQ section
• New DOCUMENTATION.md: Complete API documentation with:
  • Table of contents
  • Installation guide
  • Quick start
  • Full API reference for all classes
  • Advanced usage patterns
  • Error handling strategies
  • Best practices
  • Troubleshooting guide
  • FAQ section

🎯 API Changes

New Main Entry Point

// Old API
await PayFastService.getToken(...);
Navigator.push(..., PayFastWebView(...));

// New API
PayFast.startPayment(
  context: context,
  config: config,
  onResult: (result) { ... }
);

New Configuration Object

final config = PayFastConfig(
  merchantId: "241665",
  securedKey: "XXXX",
  basketId: "ORDER123",
  amount: "100",
  successUrl: "https://example.com/success",
  failureUrl: "https://example.com/failure",
  checkoutUrl: "https://example.com/ipn",
  // Optional parameters...
);

🔒 Security

• Improved token request validation
• Better error isolation
• Secure credential handling
• HTTPS-only API calls

⚠️ Breaking Changes

• PayFastWebView constructor signature changed to use PayFastConfig
  • Old: PayFastWebView(token, merchantId, basketId, amount, onPaymentResult)
  • New: PayFastWebView(token, config, onPaymentResult)
  • Old parameters still accepted for backward compatibility

🗑️ Deprecated

• PayFastService.getToken() is now deprecated
  • Use PayFastService.getAccessToken(config: config) instead
  • Old method still works for backward compatibility

📦 Dependencies

No new dependencies added. Still using:

• http: ^1.2.0
• webview_flutter: ^4.7.0
• crypto: ^3.0.3

🧪 Quality Improvements

• All code paths tested and validated
• No compilation errors or warnings
• Null-safe throughout
• Production-ready

---

0.0.1 Initial Release

• Initial release of PayFast Flutter package
• Integrated PayFast payment gateway using WebView
• Token-based authentication with PayFast API
• Auto-submit payment form in WebView
• Support for PKR currency
• Simple API with PayFastService.startPayment() method
• Automatic basket ID generation using timestamp
• Error handling for failed token generation