Development

.gitignore

@@ -31,3 +31,5 @@ build/
 .gradle
 /example/ios/Podfile.lock
 /coverage/
+.flutter-plugins
+.flutter-plugins-dependencies

README.md

@@ -1,78 +1,171 @@
-
 # Chapa Flutter SDK
 
-Chapa Flutter sdk for Chapa payment API. It is not official and is not supported by Chapa. It is provided as-is. The main features of this library is it supports connectivity tests, auto reroutes, parameter checks for payment options.
+The official **Chapa Flutter SDK** enables Flutter developers to integrate Chapa's Payment API seamlessly into their applications. It supports both native and web checkout, providing a robust and flexible solution for initiating and validating payments.
 
+---
 
+## **Features**
 
-## API Reference
+- 🌟 **Initiate Payment:** Easily facilitate transactions via four supported wallets telebirr,cbebirr,mpesa and ebirr.
+- ✅ **Validate Payment Status:** Confirm payment completion and notify users instantly.
+- 🌐 **Web Checkout Support:** Enable users to use the web checkout for additional payment options.
 
-#### Create new transaction from mobile end point
+---
+## **Preview**
 
-Base end point
-https://api.chapa.co/v1
+<div style="display: flex; justify-content: space-between; align-items: center;">
+  <div style="text-align: center;">
+    <p>Payment Methods in Grid View</p>
+    <img src="doc/gridview.png" alt="Payment Methods in Grid View" style="width: 200px;" />
+  </div>
+  <div style="text-align: center;">
+    <p>Payment Methods in List View with Customized Button Color</p>
+    <img src="doc/listview.png" alt="Payment Methods in List View" style="width: 200px;" />
+  </div>
+  <div style="text-align: center;">
+    <p>Error</p>
+    <img src="doc/error.png" alt="Error" style="width: 200px;" />
+  </div>
+  <div style="text-align: center;">
+    <p>Successful Payment Receipt</p>
+    <img src="doc/success.png" alt="Successful Payment Receipt" style="width: 200px;" />
+  </div>
+</div>
 
-```http
-  POST /transaction/mobile-initialize
-```
 
-| Parameter | Type     | Description                |
-| :-------- | :------- | :------------------------- |
-| `key`      | `string` | **Required**. This will be your public key from Chapa. When on test mode use the test key, and when on live mode use the live key. |
-| `email`    | `string` | A customer’s email address. |
-| `amount`   | `string` | **Required**. The amount you will be charging your customer. |
-| `first_name` | `string` |  A customer’s first name. |
-| `last_name`      | `string` |  A customer's last name. |
-| `tx_ref`   | `string` | **Required**. A unique reference given to each transaction. |
-| `currency` | `string` | **Required**. The currency in which all the charges are made. i.e ETB, USD |
-| `phone`    | `digit` |  A customer’s phone number. |
-| `callback_url`| `string` |  The URL to redirect the customer to after payment is done.|
-| `customization[title]`| `string` |  The customizations field (optional) allows you to customize the look and feel of the payment modal.|
 
-#### SDK requires additional parameter for fallBack page which is named route which will help you reroute webview after payment completed, on internet disconnected and many more
+## **Getting Started**
 
+### **Installation**
 
+Add the following dependency to your `pubspec.yaml` file:
 
-| Parameter | Type     | Description                       |
-| :-------- | :------- | :-------------------------------- |
-| `namedRouteFallBack`      | `string` | **Required by the sdk**. This will accepted route name in String, After successful transaction the app will direct to this page with necessary information for flutter developers to update the backend or to regenerate new transaction reference. |
+```yaml
+dependencies:
+  chapasdk: ^latest_version
+```
 
+Then, run the command:  
 
+```bash
+flutter pub get
+```
 
+---
+
+## **Parameters**
+
+| Parameter                  | Type              | Required  | Description                                                                                                   |
+|----------------------------|-------------------|-----------|---------------------------------------------------------------------------------------------------------------|
+| `context`                 | `BuildContext`   | **Yes**   | Context of the current widget.                                                                                |
+| `publicKey`               | `String`         | **Yes**   | Your Chapa public key (use test key for testing and live key for production).                                 |
+| `currency`                | `String`         | **Yes**   | Transaction currency (ETB for native checkout, ETB or USD for web checkout NB=> You can not use USD for Naive checkout is it is only available for Web checkout.).                                  |
+| `amount`                  | `String`         | **Yes**   | The amount to be charged.                                                                                     |
+| `email`                   | `String`         | **Yes**   | Customer’s email address.                                                                                     |
+| `phone`                   | `String`         | **Yes**   | Customer’s phone number.                                                                                      |
+| `firstName`               | `String`         | **Yes**   | Customer’s first name.                                                                                        |
+| `lastName`                | `String`         | **Yes**   | Customer’s last name.                                                                                         |
+| `txRef`                   | `String`         | **Yes**   | Unique reference for the transaction.                                                                         |
+| `title`                   | `String`         | **Yes**   | Title of the payment modal.                                                                                   |
+| `desc`                    | `String`         | **Yes**   | Description of the payment.                                                                                   |
+| `namedRouteFallBack`      | `String`         | **Yes**   | Named route to redirect users to after payment events (success, failure, or cancellation).                    |
+| `nativeCheckout`          | `bool`           | No        | Whether to use native checkout (`true`) or web checkout (`false`). Default is `true`.                         |
+| `showPaymentMethodsOnGridView` | `bool`       | No        | Display payment methods in grid (`true`) or horizontal view (`false`). Default is `true`.                     |
+| `availablePaymentMethods` | `List<String>`   | No        | List of allowed payment methods (`mpesa`, `cbebirr`, `telebirr`, `ebirr`). Defaults to all methods.           |
+| `buttonColor`             | `Color`          | No        | Button color for native checkout. Defaults to the app’s primary theme color.                                  |
+
+---
+
+## **Usage**
+
+```dart
+import 'package:chapasdk/chapasdk.dart';
 
-## Installation
+Chapa.paymentParameters(
+  context: context,
+  publicKey: 'CHAPUBK-@@@@',
+  currency: 'ETB',
+  amount: '1',
+  email: 'fetanchapa.co',
+  phone: '0911223344',
+  firstName: 'Israel',
+  lastName: 'Goytom',
+  txRef: 'txn_12345',
+  title: 'Order Payment',
+  desc: 'Payment for order #12345',
+  nativeCheckout: true,
+  namedRouteFallBack: '/',
+  showPaymentMethodsOnGridView: true,
+  availablePaymentMethods: ['mpesa', 'cbebirr', 'telebirr', 'ebirr'],
+);
+```
 
-Installation instructions coming soon its better if you install it from pub dev
+---
 
+## **Payment Responses from**
 
+### For Native Checkout:
 
-## Usage/Example
+Transaction Reference Number in Native Checkout context is Chapa's Reference number for the Payment.
+```json
+{
+  "message": "Any Descriptive message regarding the payment status",
+  "transactionReference": "CHHhvtn7xLEkZ", 
+  "paidAmount": "1.00"
+}
+```
 
-```flutter
-import 'package:chapasdk/chapasdk.dart';
+### For Web Checkout:
 
+Transaction Reference Number in Web Checkout context is The transaction reference number you generated for the payment.
 
-Chapa.paymentParameters(
-        context: context, // context 
-        publicKey: 'CHASECK_TEST--------------',
-        currency: 'ETB',
-        amount: '200',
-        email: 'xyz@gmail.com',
-        phone: '911223344',
-        firstName: 'fullName',
-        lastName: 'lastName',
-        txRef: '34TXTHHgb',
-        title: 'title',
-        desc:'desc',
-        namedRouteFallBack: '/second', // fall back route name
-       );
+Important Note:
+If the web checkout is initiated from the native checkout page, the Transaction Reference for the web checkout will be generated by the app itself. This is because a single transaction reference cannot be used for both native and web checkout processes. Therefore, the app will generate a separate transaction reference for the web checkout.
+
+#### Payment Canceled:
+```json
+{
+  "message": "paymentCancelled",
+  "transactionReference": "txn_12345",
+  "paidAmount": "1.00"
+}
+```
+#### Payment Successful:
+```json
+{
+  "message": "paymentSuccessful",
+  "transactionReference": "txn_12345" ,
+  "paidAmount": "1.00"
+}
 ```
+#### Payment Failed:
+```json
+{
+  "message": "paymentFailed",
+  "transactionReference": "txn_12345",
+  "paidAmount": "0.00"
+}
+```
+
+---
+
+## **FAQ**
 
+### **1. Is the fallback route mandatory?**
+Yes, `namedRouteFallBack` is required to handle post-payment events such as success, failure, or cancellation.  
 
-## FAQ
+### **2. What currencies are supported?**
+- Native Checkout: ONLY **ETB**  
+- Web Checkout: **ETB**, **USD**  
 
-#### Should my fallBack route should be named route?
+---
 
-Answer Yes, the fallBackRoute comes with an information such as payment is successful, user cancelled payment and connectivity issue messages. Those information will help you to update your backend, to generate new transaction reference.
+## **Support**  
 
+For any questions or issues:  
+- **Email:** [info@chapa.co](mailto:infot@chapa.co)  
+- **Call Center:** [+251960724272](tel:+251960724272)  
+- **Short Code:**  [8911](tel:8911) 
+- **Documentation:** [Chapa Developer Docs](https://developer.chapa.co/)  
 
+Start building seamless payment experiences today with the **Chapa Flutter SDK**! 🚀

example/.metadata

@@ -1,10 +1,30 @@
 # This file tracks properties of this Flutter project.
 # Used by Flutter tool to assess capabilities and perform upgrades etc.
 #
-# This file should be version controlled and should not be manually edited.
+# This file should be version controlled.
 
 version:
-  revision: 7e9793dee1b85a243edd0e06cb1658e98b077561
+  revision: f468f3366c26a5092eb964a230ce7892fda8f2f8
   channel: stable
 
 project_type: app
+
+# Tracks metadata for the flutter migrate command
+migration:
+  platforms:
+    - platform: root
+      create_revision: f468f3366c26a5092eb964a230ce7892fda8f2f8
+      base_revision: f468f3366c26a5092eb964a230ce7892fda8f2f8
+    - platform: android
+      create_revision: f468f3366c26a5092eb964a230ce7892fda8f2f8
+      base_revision: f468f3366c26a5092eb964a230ce7892fda8f2f8
+
+  # User provided section
+
+  # List of Local paths (relative to this file) that should be
+  # ignored by the migrate tool.
+  #
+  # Files that are not part of the templates will be ignored by default.
+  unmanaged_files:
+    - 'lib/main.dart'
+    - 'ios/Runner.xcodeproj/project.pbxproj'

example/android/build.gradle

@@ -6,7 +6,7 @@ buildscript {
     }
 
     dependencies {
-        classpath 'com.android.tools.build:gradle:4.1.0'
+        classpath 'com.android.tools.build:gradle:8.4.0'
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
     }
 }
@@ -26,6 +26,6 @@ subprojects {
     project.evaluationDependsOn(':app')
 }
 
-task clean(type: Delete) {
+tasks.register("clean", Delete) {
     delete rootProject.buildDir
 }

example/android/gradle/wrapper/gradle-wrapper.properties

@@ -3,4 +3,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-6.7-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.8.0-all.zip

example/ios/Flutter/AppFrameworkInfo.plist

@@ -21,6 +21,6 @@
   <key>CFBundleVersion</key>
   <string>1.0</string>
   <key>MinimumOSVersion</key>
-  <string>9.0</string>
+  <string>12.0</string>
 </dict>
 </plist>

example/ios/Podfile

@@ -1,5 +1,5 @@
 # Uncomment this line to define a global platform for your project
-# platform :ios, '9.0'
+platform :ios, '12.0'
 
 # CocoaPods analytics sends network stats synchronously affecting flutter build latency.
 ENV['COCOAPODS_DISABLE_STATS'] = 'true'