telebirr_inapp_purchase_plus 0.0.1

A cleaner Flutter bridge for Telebirr InApp Purchase SDK payments on Android and iOS.

telebirr_inapp_purchase_plus

Clean Flutter payments for the official Telebirr InApp Purchase SDK.

This package does one job: it starts the native Telebirr payment screen with the receiveCode your backend already created, then returns the SDK callback to Flutter.

What You Build

Your backend:

• Gets a Fabric Token.
• Creates a Telebirr order.
• Signs requests with your private key.
• Receives notify_url.
• Verifies payment with queryOrder when needed.

Your Flutter app:

• Asks your backend to create an order.
• Receives receiveCode.
• Calls TelebirrInAppPurchasePlus.startPay(...).
• Displays the SDK callback.

No app secret, private key, signing, token, create-order, query-order, or notify-url code belongs in Flutter.

Install

dependencies:
  telebirr_inapp_purchase_plus: ^0.0.1

Then run:

flutter pub get

Native SDK Files

Telebirr currently provides the native SDK as local files. Because those files may be proprietary, this public package does not publish merchant credentials or private keys, and you should only redistribute Telebirr SDK binaries if your Telebirr agreement allows it.

Place the official files here in this package or your local checkout:

android/libs/EthiopiaPaySdkModule-uat-release.aar
android/libs/EthiopiaPaySdkModule-prod-release.aar
ios/Frameworks/EthiopiaPaySDK.framework

For local development, you can copy files from a Telebirr SDK folder:

./scripts/install_telebirr_sdks.sh /path/to/TelebirrSDKFolder

Flutter Usage

final request = TelebirrPaymentRequest(
  appId: 'YOUR_MERCHANT_APP_ID',
  shortCode: 'YOUR_SHORT_CODE',
  receiveCode: receiveCodeFromBackend,
  returnApp: 'yourappscheme',
  environment: TelebirrEnvironment.test,
);

final result = await TelebirrInAppPurchasePlus.startPay(request);

if (result.isSuccess) {
  print('Payment successful');
} else if (result.isCancelled) {
  print('Payment cancelled');
} else if (result.isAppNotInstalled) {
  print('Telebirr app is not installed');
} else {
  print('Payment failed: ${result.message}');
}

Stream callback:

final sub = TelebirrInAppPurchasePlus.paymentResultStream.listen((result) {
  print('Telebirr callback: ${result.code} - ${result.message}');
});

Backend Response

Your app can call any backend route you choose. The example app expects this:

{
  "success": true,
  "merchantOrderId": "1705460512562",
  "receiveCode": "TELEBIRR$BUYGOODS$100100306$12.00$080075a4e3213924de2b3b84ad3cac0a6a6001$120m"
}

See doc/backend.md for a small Laravel-style example.

Android Setup

1. Add the Telebirr AAR files:

   android/libs/EthiopiaPaySdkModule-uat-release.aar
   android/libs/EthiopiaPaySdkModule-prod-release.aar
   

2. Use FlutterFragmentActivity in the host app:

   import io.flutter.embedding.android.FlutterFragmentActivity
   
   class MainActivity : FlutterFragmentActivity()
   

3. Keep this ProGuard rule if you customize shrinking:

   -keep class com.huawei.ethiopia.pay.sdk.api.core.** { *; }
   

The plugin already declares INTERNET permission and package visibility for the Telebirr payment app.

iOS Setup

1. Add the official framework:

   ios/Frameworks/EthiopiaPaySDK.framework
   

2. Run:

   cd example/ios
   pod install
   

3. Add this to the host app Info.plist:

   <key>LSApplicationQueriesSchemes</key>
   <array>
     <string>telebirrcustomerApp</string>
   </array>
   

4. Add a URL Type for your return scheme, for example yourappscheme, and pass the same value as returnApp.

The plugin registers an application delegate and forwards openURL to the SDK. If your app has custom AppDelegate or SceneDelegate URL routing, make sure it does not swallow the Telebirr return URL before plugins receive it.

Test And Production

• Test uses the UAT/testbed Telebirr app and UAT AAR/framework.
• Production uses the production Telebirr app and production SDK.
• Do not mix test receiveCode values with production credentials.
• Your backend base URL, Fabric App ID, App Secret, private key, short code, notify URL, and merchant app ID must all belong to the same environment.

Error Codes

Code	Meaning
0	Payment success
-1	Unknown error
-2	Parameter error
-3	Payment cancelled
-10	Telebirr payment app is not installed
-11	Current Telebirr app version does not support this function

Example App

cd example
flutter pub get
flutter run

Fill in:

• Backend create-order URL.
• Merchant App ID.
• Short code.
• Return app scheme.
• Amount and title.

Tap Create Order From Backend, then Pay With Telebirr.

Troubleshooting

• receiveCode must start with TELEBIRR$: return the exact receiveCode from your backend.
• Telebirr app is not installed: install the UAT or production Telebirr app.
• NO_ACTIVITY: Android host app must use FlutterFragmentActivity.
• SDK_NOT_AVAILABLE on iOS: copy EthiopiaPaySDK.framework and run pod install.
• Create order succeeds but payment fails: confirm app ID, short code, receive code, return scheme, and Telebirr app environment match.
• Backend callback missing: make notify_url public and verify with queryOrder.

Publishing Checklist

• No merchant credentials in examples.
• No private keys in the repo.
• Confirm Telebirr SDK redistribution rights before committing binaries.
• Run flutter analyze.
• Run flutter test.
• Run dart pub publish --dry-run.
• Create a GitHub release/tag only after testbed device payment is verified.