telebirr_inapp 0.1.0

Flutter plugin for telebirr InApp SDK payments on Android and iOS, with an explicit Gradle switch between the testbed and production SDK.

telebirr_inapp

Flutter plugin for telebirr InApp SDK payments on Android and iOS.

It opens the telebirr app with the receiveCode your backend created and returns the SDK's result to Dart. You choose the testbed or production Android SDK with one Gradle property, and the plugin refuses to run if the build and your code disagree.

Unofficial: not affiliated with Ethio telecom. See NOTICE for the bundled SDK binaries.

How it fits together

1. Your app asks your backend to create an order.
2. Your backend calls telebirr's applyFabricToken and createOrder (trade_type: "Cross-App") and returns biz_content.receiveCode. With "InApp" the telebirr app refuses the order ("The trade type is not filled in, or it is incorrect").
3. Your app calls Telebirr.pay(receiveCode: ...), which opens telebirr.
4. telebirr calls your backend's notify_url. Treat that, or queryOrder, as the proof of payment. The result returned in the app is only a hint.

The app secret and private key belong on the backend. This plugin never asks for them.

Install

dependencies:
  telebirr_inapp: ^0.1.0

Android

The telebirr SDK needs a FragmentActivity. Change MainActivity:

import io.flutter.embedding.android.FlutterFragmentActivity

class MainActivity : FlutterFragmentActivity()

Then pick the SDK in android/gradle.properties:

telebirrEnv=uat

Value	SDK linked into the app
uat	Testbed, in every build type
prod	Production, in every build type
auto	Default. Testbed for debug, production for everything else

You can also set it per build without editing the file:

flutter build apk --release --android-project-arg=telebirrEnv=prod

or export TELEBIRR_ENV. The Gradle property wins over the environment variable.

Why a build switch and not a runtime one: the testbed and production SDKs are two binaries that define the same classes, so only one fits in an app. The testbed SDK opens the telebirr UAT app, the production SDK opens the telebirr app from the store. Testers need the UAT app installed.

Nothing else is needed: the manifest entries, the INTERNET permission and the ProGuard rule come with the plugin.

iOS

Add to ios/Runner/Info.plist:

<key>LSApplicationQueriesSchemes</key>
<array>
  <string>telebirrcustomerApp</string>
</array>
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>yourappscheme</string>
    </array>
  </dict>
</array>

telebirr returns to your app through that URL scheme. The plugin uses the first scheme in CFBundleURLTypes unless you pass iosReturnScheme.

One SDK binary serves both environments on iOS, so there is no switch.

Use

import 'package:telebirr_inapp/telebirr_inapp.dart';

await Telebirr.initialize(
  appId: 'YOUR_MERCHANT_APP_ID',
  shortCode: 'YOUR_SHORT_CODE',
  environment: TelebirrEnvironment.test, // or TelebirrEnvironment.live
);

final result = await Telebirr.pay(receiveCode: receiveCodeFromBackend);

switch (result.status) {
  case TelebirrPaymentStatus.success:
    // Ask your backend whether the notify callback arrived.
    break;
  case TelebirrPaymentStatus.cancelled:
    break;
  case TelebirrPaymentStatus.appNotInstalled:
    // Ask the customer to install telebirr.
    break;
  default:
    print('telebirr: ${result.code} ${result.message}');
}

If the Android build links the other SDK, initialize throws a TelebirrEnvironmentMismatchException whose message names the Gradle value to set. Telebirr.nativeEnvironment() tells you what the build contains (null on iOS).

TelebirrEnvironment.gatewayBaseUrl gives the gateway URL for each environment, for sending to or configuring your backend.

Result codes

Code	Status
0	success
-1	unknownError
-2	parameterError
-3	cancelled
-10	appNotInstalled
-11	appVersionNotSupported
-100	noResult

Codes are passed through from the telebirr SDK as it reports them, except -100: the plugin reports noResult when the customer comes back from telebirr and it said nothing (for example its session had expired and it showed a login screen). The payment may or may not have happened, so ask your backend.

Telebirr's screens open inside your app's own task. If the customer swipes your app away during a payment, your app is closed too and the result is lost, so re-check any unfinished order with your backend when your app starts.

Example

example/ is a checkout screen that posts {title, amount, environment} to your backend URL and pays with the receiveCode it returns, as plain text or as JSON. You can also paste a receiveCode directly.

cd example
flutter run