Bas flutter SDK

A Flutter plugin that integrates the Bas Pay native payment experience (Android / iOS) into your Flutter app using a simple Dart API.

Overview

Features

Requirements

Installation

Quick Start

InitBasSdkModel Reference

Environments (prod vs dev)

Calling the Payment Flow

Handling Results (ResultModel)

10.

Platform Setup (Android / iOS / Web / Windows)

11.

Internationalization (language)

12.

Error Handling & Troubleshooting

13.

Security Considerations

14.

FAQ

15.

Versioning & Changelog

16.

Contributing

17.

License

18.

Support / Contact

See ٍSource Code in github.

1. Overview

bas_pay_flutter exposes a single high‑level method BasPayFlutter().callBasPay(...) that launches the native Bas Pay UI and returns structured result data. You supply a transaction token (trxToken) plus optional user info and preferences; the plugin handles bridging data to Android/iOS and parsing results back into Dart.

2. Features

Simple one-call payment initiation

Environment selection (prod / dev) via dedicated constructors

Optional user metadata (identifier, full name, product)

Language override (e.g. ar, en) with fallback

Strongly typed result wrapper (ResultModel) with flexible parsing of varied backend field types

Supports Android (Jetpack Compose + AAR), iOS (vendored xcframework), Web (stub), Windows (stub)

3. Requirements

Platform	Minimum	Notes
Dart SDK	^3.7.2 (as in `pubspec.yaml`)	Align with your Flutter SDK constraints
Flutter	>=3.3.0	Tested up to latest stable (update when validated)
Android	minSdk 24 / compileSdk 36	Kotlin 2.1.0, Gradle plugin 8.7.0
iOS	iOS 13.0+	xcframework auto-fetched in pod install
Windows	Supported plugin target	Basic stub, payment flow may not be implemented
Web	Supported plugin target	Basic stub, payment flow may not be implemented

If you target earlier Android/iOS versions you must raise them to meet Bas Pay SDK requirements.

4. Installation

Add to your pubspec.yaml:

Then run:

Import where needed:

5. Quick Start

6. InitBasSdkModel Reference

Two constructors define the environment implicitly:

InitBasSdkModel.prod(...) => environment = "prod"

InitBasSdkModel.dev(...) => environment = "dev"

Field	Type	Required	Default	Source	Description
`trxToken`	`String`	Yes	N/A	You / backend	Unique transaction token provided by your server / Bas Pay API
`userIdentifier`	`String?`	No	`null`	You	E.g. phone number or user id for tracking / personalization
`fullName`	`String?`	No	`null`	You	Display / identification purposes
`language`	`String?`	No	Fallback to `ar` (SDK)	You	UI language override (currently supports `ar`, `en`)
`platform`	`String`	Internal	`"Flutter"`	Plugin	Set automatically, do not modify
`product`	`String?`	No	`null`	You	Optional product / channel identifier
`environment`	`String?`	Internal	`"prod"` or `"dev"`	Constructor	Set automatically based on constructor used

If language is omitted the underlying SDK defaults to Arabic (ar). Confirm behavior with latest backend if multi-language expansion occurs.

7. Environments (prod vs dev)

Use .prod during production & .dev for testing against Bas Pay's development endpoints. Never mix tokens across environments. Keep dev tokens out of production builds.

8. Calling the Payment Flow

Construct InitBasSdkModel with proper environment.

Call BasPayFlutter().callBasPay(model: ...).

Await the returned tuple: ({bool resultStatus, ResultModel? resultModel}).

resultStatus indicates the MethodChannel invocation & native flow returned something parseable.

resultModel (may be null if parse failed) holds business outcome.

Inspect resultModel.status to determine payment success.

9. Handling Results (`ResultModel`)

ResultModel wraps dynamic response content and normalizes common field types (bool/string/int/double). It exposes:

status (bool): Success indicator; gracefully parses bool, string, int (1), double (1.0). Missing -> false.

message (String): Human-readable summary. Missing -> empty string.

result (dynamic): Raw payload / data structure (map, list, value) from Bas Pay backend. Missing -> null.

code (int): Business/HTTP-like status code; missing or unparseable -> internal fallback 699.

Example pattern:

Custom codes and result schema may evolve. Add shape guards or adapters in your app for resilience.

10. Platform Setup

Android

BasActivity is declared in the plugin manifest; you do not need to add it manually.

minSdk 24 required.

Ensure Internet access (add <uses-permission android:name="android.permission.INTERNET"/> in your app manifest if not already present).

If push notifications or other capabilities become necessary, update docs (TODO: confirm exact requirements if Banky Lite notifications rely on additional services).

iOS

iOS 13.0 minimum.

The xcframework (bas_pay.xcframework) is downloaded automatically during pod install via the podspec prepare_command.

Run cd ios && pod install after first plugin add or when updating.

Ensure you have use_frameworks! only if required elsewhere (not strictly needed here).

If notifications/push tokens are required in future, include appropriate entitlement & user permission flow (TODO: confirm).

Windows & Web

Stubs exist so your multi-platform project compiles. Payment flow may be unsupported (returns errors or unimplemented). Guard usage by platform check:

11. Internationalization (language)

Pass language: 'en' for English; omit or pass 'ar' for Arabic (default). Unsupported/unknown values may fallback to Arabic. Validate user preference before sending.

12. Error Handling & Troubleshooting

Scenario	Symptom	Action
Missing / invalid `trxToken`	Native screen fails / backend rejects	Ensure backend generated valid token before calling
`resultStatus == false`	Transport / channel failure	Retry once; log full arguments; verify platform compatibility
`resultModel == null`	Parse exception	Log raw string from channel; check backend response shape
`status == false` with meaningful `message`	Business/payment failure	Show message to user; allow retry
iOS root VC error	FlutterError: Could not get rootViewController	Ensure app has visible window & not during early startup
Activity theming issues (Android)	UI style unexpected	Override theme if BasActivity requires specific attributes (TODO)

Enable verbose logging around the call when diagnosing issues.

13. Security Considerations

Never hardcode production trxToken values; always request them from a secure backend per transaction.

Treat tokens as short-lived; revoke / expire server-side when consumed.

Avoid logging full tokens in production; mask except last 4–6 chars.

Use HTTPS everywhere between your app & backend issuing the token.

14. FAQ

Q: Can I reuse the same trxToken?
A: Typically no; each payment intent should have a unique token. Confirm with Bas Pay docs.

Q: How do I switch to sandbox?
A: Use InitBasSdkModel.dev(...) and supply a dev environment token.

Q: What languages are supported?
A: Currently Arabic (ar) and English (en). Others fallback to Arabic.

Q: What if I need to cancel mid-flow?
A: User can dismiss provided native UI; handle returned failure/status accordingly.

15. Versioning & Changelog

Versioning follows semantic intent. See CHANGELOG.md for release notes. Update the dependency to the latest published version and review changes before deployment.

16. Contributing

Fork the repository.

Create a feature branch: git checkout -b feature/my-improvement.

Add tests / example updates where relevant.

Run static analysis & format code: dart analyze / dart format ..

Submit a pull request describing changes & rationale.

Please open issues for bugs, enhancement ideas, or questions.

17. License

Distributed under the terms of the project License (see LICENSE).

18. Support / Contact

For support or integration questions reach out:

Email: (placeholder) support@example.com

Maintainer email (from podspec): osama.mtm77@gmail.com

Replace placeholder contact with official support channel before publishing.

Roadmap / TODOs

Confirm additional Android permissions (if any) beyond INTERNET.

Validate push/notification requirements for iOS (BankyLiteNotificationManager registration currently invoked).

Document result payload schema examples once finalized.

Expand Web/Windows implementation or clarify unsupported status.

Example Logging Pattern

If you discover inaccuracies or need clarifications please open an issue so we can refine this documentation.

Flutter SDK

Bas flutter SDK#

Table of Contents#

See ٍSource Code in github.#

1. Overview#

2. Features#

3. Requirements#

4. Installation#

5. Quick Start#

6. InitBasSdkModel Reference#

7. Environments (prod vs dev)#

8. Calling the Payment Flow#

9. Handling Results (ResultModel)#

10. Platform Setup#

Android#

iOS#

Windows & Web#

11. Internationalization (language)#

12. Error Handling & Troubleshooting#

13. Security Considerations#

14. FAQ#

15. Versioning & Changelog#

16. Contributing#

17. License#

18. Support / Contact#

Roadmap / TODOs#

Example Logging Pattern#