emvqr 0.0.22

SDKflutter
Platformandroidios

A plugin by Fawry for scanning EMV QR Codes.

Fawry EMVQR SDK Integration Guide

Welcome to the comprehensive Fawry EMVQR SDK Integration Guide. This guide will walk you through the seamless integration of Fawry's native Android and iOS SDKs into your Flutter projects for effortless EMVQR scanning.

Table of Contents


Getting Started

Adding Fawry EMVQR SDK Pub

To begin, add the Fawry EMVQR SDK plugin to your Flutter project's dependencies. Open the terminal in the root project and install the pub using following command

flutter pub add emvqr

Android Setup

  1. To integrate with Android, Update the minimum SDK version to 21 or higher in your build.gradle file:
android {
    compileSdkVersion flutter.compileSdkVersion
    minSdkVersion 21
    // ...
}
  1. Set your compile sdk version to 34
  compileSdkVersion 34
  1. In your build.gradle add the following code to the "buildscript" and "allprojects" blocks
repositories {
    google()
    mavenCentral()
    maven { url 'https://nexus.mobile.fawry.io/repository/maven-public/' }
}

iOS Setup

For iOS integration, follow these steps:

  1. Set the minimum iOS version under "Deployment info" to 12.1 or higher in your Runner project in Xcode.

  2. Enhance pod distribution by adding the following code at the end of the pod file (Podfile):

post_install do |installer|
    installer.pods_project.targets.each do |target|
        target.build_configurations.each do |config|
            config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
        end
    end
end

Fawry EMVQR SDK Imports

Before you proceed, make sure to import the necessary Fawry SDK packages at the beginning of your Dart file:

import 'package:emvqr/model/scan_result.dart';
import 'package:emvqr/emvqr.dart';
import 'package:emvqr/model/qr_model.dart';

Streaming Result Data

  late StreamSubscription? _fawryCallbackResultStream;
  QrModel? qrModel;
  List<ScanResult> qrResponses = [];

  @override
  void initState() {
    super.initState();
    setupCallback();
  }

  @override
  void dispose() {
    _fawryCallbackResultStream?.cancel();
    super.dispose();
  }

  Future<void> setupCallback() async {
    try {
      _fawryCallbackResultStream =
          Emvqr.instance.callbackResultStream().listen((event) {
        setState(() {
          Map<Object?, Object?> eventData = event;
          ScanResult response = ScanResult.fromJson(eventData);
          qrResponses.add(response);
          QrModel? model = response.extractQrModel();

          qrModel = model ?? qrModel;
          if (qrModel != null) {
            debugPrint(qrModel.toString());
          }
        });
      });
    } catch (ex) {
      debugPrint("Error in setupCallback: $ex");
    }
  }

  Future<void> startScanning() async {
    await Emvqr.instance.scanQR();
  }

Models Explained :

ScanResult

PARAMETER NAMEPARAMETER TYPEDESCRIPTION
statusStringThe status of the scan operation. This can be a success or an error message.
dataString?The optional data obtained from the scan operation. This may be null if no data was retrieved.
extractQrModel()QrModel?Method to return a [QrModel] object from [ScanResult].

QrModel

PARAMETER NAMETYPEDESCRIPTION
merchantIDStringThe merchant ID associated with the QR code.
mccString?Merchant Category Code (MCC) - an optional field.
currencyString?The currency used for the transaction - an optional field.
amountStringThe amount of the transaction.
feesAmountString?Fees associated with the transaction - an optional field.
countryCodeString?The country code associated with the QR code - an optional field.
merchantNameString?The name of the merchant - an optional field.
merchantCityString?The city where the merchant is located - an optional field.
postalCodeString?The postal code of the merchant's location - an optional field.
ref1String?Additional reference information (Reference 1) - an optional field.
ref2String?Additional reference information (Reference 2) - an optional field.
additionalInfoAdditionalInfo?Additional information associated with the QR code - an optional field.
terminalIdString?The terminal ID associated with the QR code - an optional field.
qrTimeStampString?Timestamp associated with the QR code - an optional field.
unreservedTemplateMap<String, Map<String, String>>Unreserved Template - a map containing String keys and values, where each key is associated with an inner map of type Map<String, String>.

AdditionalInfo

PARAMETER NAMEPARAMETER TYPEDESCRIPTION
storeIdString?Store Id information.
billNumberString?Bill number information.
mobileNumberString?Mobile number information.
loyaltyNumberString?Loyalty number information.
referenceLabelString?Reference label information.
customerLabelString?Customer label information.

Conclusion

You've successfully integrated the Fawry EMVQR SDK into your Flutter project. Follow the streamlined steps for Android and iOS platforms outlined in this guide.

Utilize the startScanning function to initiate QR code scanning and the setupCallback method for result streaming. Extract relevant information using the ScanResult, QrModel, and AdditionalInfo models.

For any queries or assistance, consult the documentation or contact Fawry's support.

Thank you for choosing Fawry. Happy coding!