N-Genius Flutter SDK

N-Genius Flutter SDK provides an easy-to-use integration for handling payments using N-Genius APIs in Flutter applications.

📱 Platform Compatibility

• Android ✅

• iOS ✅ (Minimum deployment target: iOS 12.0)

⚙️ Android Configuration

Tested Environment

This plugin has been tested with:

• Flutter: 3.44.8 stable (Dart 3.12.2)
• Android Gradle Plugin (AGP): 9.0.1 settings.gradle
• Kotlin Version: 2.3.20 settings.gradle
• Gradle Distribution: 9.1.0 gradle-wrapper.properties
• N-Genius Android SDK: 4.0.5 android/build.gradle

The example no longer applies the kotlin-android plugin directly. Its gradle.properties currently retains Flutter's AGP 9 compatibility flags, so this branch should not yet be described as a complete built-in Kotlin migration.

Project-Level build.gradle Changes

Since the N-Genius SDK is hosted on JitPack, add the JitPack repository to the allprojects repositories block in your project-level android/build.gradle file.

For newer Flutter projects

Use: maven { url = uri("https://jitpack.io") }

For older Flutter projects

Use: maven { url 'https://jitpack.io' }

Your allprojects block should look like this:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") } // Add this line
    }
}

The example app already includes this repository and the android.permission.INTERNET permission.

🍏 iOS Configuration

No additional configuration is required for iOS.

🔄 N-Genius Response Model

The plugin returns a response object containing a message and a code. Below are the possible response scenarios:

🛑 Transaction Cancellation & Errors

Condition	Message	Code
User cancels the transaction	CANCELLED_BY_USER	401
Order expired or generic error	STATUS_GENERIC_ERROR	-1
Payment failed	STATUS_PAYMENT_FAILED	0

✅ Successful Payment Responses

🟢 Android

Payment Status	Message	Code
Payment authorized	PAYMENT_SUCCESSFUL	1
Payment captured	PAYMENT_SUCCESSFUL	2
Payment purchased	PAYMENT_SUCCESSFUL	3
Post authorization review	PAYMENT_SUCCESSFUL	4

🍏 iOS

The native iOS N-Genius SDK does not provide specific statuses like authorized, captured, or purchased. Instead, it returns a generic success response:

Condition	Message	Code
Transaction successful	PAYMENT_SUCCESSFUL	200

---

🚀 Get Started with N-Genius Flutter SDK

1. Install the plugin in your Flutter project.
2. Configure Android settings as mentioned above.
3. Create an order using the N-Genius APIs on your backend.
4. Pass the complete order response to the plugin to launch the payment flow.

Run the Example App

The example app can create sandbox orders directly for easier SDK testing. Open its Config tab and enter the API key value without the Basic prefix, the outlet reference, and optionally a different base URL. You can also launch it with:

cd example
flutter pub get
flutter run \
  --dart-define=NGENIUS_API_KEY=your_api_key \
  --dart-define=NGENIUS_OUTLET_REF=your_outlet_reference

The default base URL is https://api-gateway.sandbox.ngenius-payments.com. Override it with --dart-define=NGENIUS_BASE_URL=... when required.

Security: Direct access-token and order requests are included only to make the example easy to test. Never ship an N-Genius API key in a production mobile app. Create tokens and orders on a trusted backend and return the order object to the app.

---

Example Implementation (Normal Payment)

class NgeniusExample extends StatelessWidget {
  const NgeniusExample({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('N-Genius Example'),
      ),
      body: Center(
        child: ElevatedButton(
            onPressed: () async {
              final ngeniusFlutterSdk = NgeniusFlutterSdk();
              NGeniusResponseModel ngeniusResponse = await ngeniusFlutterSdk.launchCardPayment(orderJsonObject: {});
              if (context.mounted) {
                if (ngeniusResponse.message == "PAYMENT_SUCCESSFUL") {
                  ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text("Transaction Successful")));
                } else {
                  ScaffoldMessenger.of(context).showSnackBar(SnackBar(
                      content: Text(
                          "Transaction Failed :: code :: ${ngeniusResponse.code} :: message :: ${ngeniusResponse.message}")));
                }
              }
            },
            child: Text("Launch Card Payment")),
      ),
    );
  }
}

⚠️ IMPORTANT: The minimum supported card expiry date is 12/2030. Any expiry date before 12/2030 will be rejected.

---

Example Implementation (for using Saved Cards)

Note: The key difference when using a saved card is in the order creation step. You must pass a savedCard object (NGeniusSavedCardModel) in your createOrder request body. If recaptureCsc is set to true, the user will be prompted to enter their CVV — you can skip this by passing the cvv directly to launchSavedCardPayment.

First: Getting the Saved-Card Token

1- Ensure that Tokenization is enabled for your merchant account.

2- After a successful payment, retrieve the order details using the following endpoint: GET /transactions/outlets/{{outletId}}/orders/{{orderId}}

3- The saved card token is returned in the response at: _embedded.payment.savedCard.cardToken

You can use this token to perform future saved card payments without requiring the customer to re-enter their card details.

Second: Implementation Details

class NgeniusSavedCardExample extends StatelessWidget {
  const NgeniusSavedCardExample({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('N-Genius Saved Card Example'),
      ),
      body: Center(
        child: ElevatedButton(
            onPressed: () async {
              // 1. Build your saved card model from your stored card data
              final savedCard = NGeniusSavedCardModel(
                maskedPan: "400555******0001",
                expiry: "2030-12",
                cardholderName: "John Doe",
                scheme: "VISA",
                cardToken: "your-card-token",
                recaptureCsc: true, // true = user will be prompted for CVV
              );

              // 2. Call YOUR backend/API to create the order.
              // This is not part of the plugin — you are responsible for
              // implementing this API call following the N-Genius documentation:
              // https://docs.ngenius-payments.com/reference/two-stage-payments-orders
              // The savedCard object must be included in the request body.
              final Map<String, dynamic> orderJsonObject = await yourApiService.createOrder(
                amountValue: 10.50,
                currency: "AED",
                savedCard: savedCard,
              );

              // 3. Launch saved card payment
              // Pass cvv to skip the CVV page, or omit it to let the user enter it
              final ngeniusFlutterSdk = NgeniusFlutterSdk();
              NGeniusResponseModel ngeniusResponse = await ngeniusFlutterSdk.launchSavedCardPayment(
                orderJsonObject: orderJsonObject, 
                //cvv: "123" //If you want your UI to handle CVV
              );

              if (context.mounted) {
                if (ngeniusResponse.message == "PAYMENT_SUCCESSFUL") {
                  ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text("Transaction Successful")));
                } else {
                  ScaffoldMessenger.of(context).showSnackBar(SnackBar(
                      content: Text(
                          "Transaction Failed :: code :: ${ngeniusResponse.code} :: message :: ${ngeniusResponse.message}")));
                }
              }
            },
            child: Text("Launch Saved Card Payment")),
      ),
    );
  }
}

---

🔄 N-Genius SavedCard Model

Parameter	Example	DataType
maskedPan	400555******0001	String
expiry	"2030-12"	String
cardholderName	"John Doe"	String
scheme	"VISA"	String
cardToken	"your-card-token"	String
recaptureCsc	true = user will be prompted for CVV	boolean

---

Passing the Order JSON Object to launchCardPayment Method

To pass the orderJsonObject to the launchCardPayment method, you need to provide it against the orderJsonObject key. To get the orderJsonObject, you must first call two APIs. It is recommended to call these APIs on the server-side, not on the mobile side, for security and performance reasons.

Steps to Get the Order JSON Object

1- Get the Access Token
First, you need to obtain the access token by following the official N-Genius documentation:
Request an Access Token

2- Get the Order Object
Once you have the access token, use it to call the API to get the order object. For more information, refer to the N-Genius documentation:
Two-Stage Payments Orders

Sample Order JSON Object

After calling the APIs, you will receive the N-Genius order object. You can check the structure of the order object by referring to the official sample here:
Order Object in Full

---

Test Payment Using N-Genius Test Cards

You can test payment using test cards for N-Genius from the following link:
Sandbox Test Environment

⚠️ IMPORTANT: The minimum supported card expiry date is 12/2030. Any expiry date before 12/2030 will be rejected.

For detailed documentation, refer to the official N-Genius API documentation.

Contributors

Thanks to the people who have contributed to this package:

Ziad Hassan

License

This project is licensed under the MIT License.

---

📌 Note: If you encounter any issues, ensure all dependencies and configurations match the tested environment.

Happy coding! 🎉