chargily_pay 0.0.1

A production-ready Flutter SDK for integrating Chargily Pay V2 (EDAHABIA & CIB). Secure, typed, and easy to use.

Chargily Pay Flutter SDK 🇩🇿

A production-ready Flutter SDK for integrating Chargily Pay V2, the leading payment gateway in Algeria.

This package provides a seamless way to accept EDAHABIA and CIB payments in your Flutter app. It handles the API complexity and provides a secure, drop-in UI for the payment flow.

---

⚠️ Security Warning

NEVER ship your Chargily Secret Key inside your mobile app code.

• Production: Your mobile app should call your own backend, which then communicates with Chargily using the Secret Key.
• Development: You may use the Secret Key temporarily for testing, but remove it before release.

---

✨ Features

• 🔌 Easy Integration: Simple ChargilyClient wrapper for V2 API.
• 📱 Drop-in UI: ChargilyCheckoutView handles the payment webview and redirects automatically.
• 🛡️ Type-Safe: Fully typed Request & Response models (No more Map<String, dynamic>).
• 🇩🇿 Localization: Supports ar, en, fr locales.
• 🧪 Test Mode: Built-in support for Chargily's Test API.

---

📦 Installation

Add this to your pubspec.yaml:

dependencies:
  chargily_pay: ^0.0.1

Or run:

flutter pub add chargily_pay

---

🚀 Getting Started

1. Initialize the Client

You can initialize the client in Test or Live mode.

import 'package:chargily_pay/chargily_pay.dart';

// 🧪 FOR TESTING ONLY
final client = ChargilyClient(ChargilyConfig.test(
  apiKey: 'test_pk_YOUR_API_KEY', 
));

// 🚀 FOR PRODUCTION (Recommended)
// In production, you typically don't need the API key in the Flutter app 
// if you create checkouts on your backend.
final client = ChargilyClient(ChargilyConfig.live());

2. Create a Checkout

Ideally, fetch this from your backend. If you are prototyping, you can create it directly:

final request = CreateCheckoutRequest(
  amount: 2000, // 2000 DZD
  currency: 'dzd',
  successUrl: 'https://myapp.com/success', // Deep link to your app
  failureUrl: 'https://myapp.com/failure',
  locale: 'ar', // Arabic checkout interface
  description: 'Payment for Premium Subscription',
);

final checkout = await client.createCheckout(request);

3. Show the Payment Screen

Use the ChargilyCheckoutView widget to show the payment page. It automatically detects when the user finishes payment (success) or cancels (failure) based on the redirect URLs.

import 'package:chargily_pay/chargily_pay.dart';

// ... inside your button's onPressed:

Navigator.of(context).push(
  MaterialPageRoute(
    builder: (context) => ChargilyCheckoutView(
      checkout: checkout,
      onPaymentSuccess: () {
        // Handle success (e.g., show success dialog)
        Navigator.pop(context);
        print("✅ Payment Successful!");
      },
      onPaymentFailure: () {
        // Handle failure
        Navigator.pop(context);
        print("❌ Payment Failed.");
      },
      onPaymentCancel: () {
        // User closed the modal
        Navigator.pop(context);
      },
    ),
  ),
);

---

🏗️ Architecture

This package is designed with a Backend-First mindset:

1. Mobile App: Requests a checkout from Your Backend.
2. Your Backend: Calls Chargily API (POST /checkouts) using the Secret Key.
3. Your Backend: Returns the checkout_url to the Mobile App.
4. Mobile App: Opens ChargilyCheckoutView with the URL.
5. User: Pays via EDAHABIA/CIB.
6. Chargily: Sends a Webhook to your backend to confirm payment.

---

🧪 Error Handling

The SDK throws specific exceptions to help you handle errors gracefully:

try {
  final checkout = await client.createCheckout(request);
} on ChargilyNetworkException {
  // Internet connection lost
} on ChargilyApiException catch (e) {
  // API returned an error (e.g. 401 Unauthorized, 422 Validation)
  print(e.message); 
  print(e.statusCode);
} catch (e) {
  // Other errors
}

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📄 License

Distributed under the MIT License. See LICENSE for more information.