Android Integration

Integrate EthiopiaPaySdkModule.aar into your Android app to enable in-app Telebirr payments.

The SDK is distributed as a local AAR dependency — it’s not available on Maven Central yet.

Download the AAR

Environment	File
Test	`EthiopiaPaySdkModule-uat-release.aar`
Production	`EthiopiaPaySdkModule-prod-release.aar`

Download from the Telebirr Developer Portal.

Add the AAR to your project

Create a libs folder inside your app module (e.g. app/libs/) and copy the .aar file into it.

app/
  libs/
    EthiopiaPaySdkModule-uat-release.aar

Register the libs repository

In your project-level build.gradle:

allprojects {
    repositories {
        // ...existing repos...
        flatDir { dirs 'libs' }
    }
}

Or in settings.gradle (newer project structure):

dependencyResolutionManagement {
    repositories {
        // ...existing repos...
        flatDir { dirs("app/libs") }
    }
}

Add the dependency

In your app-level build.gradle:

dependencies {
    implementation files('libs/EthiopiaPaySdkModule-uat-release.aar')
    // or for production:
    // implementation files('libs/EthiopiaPaySdkModule-prod-release.aar')
}

Add the INTERNET permission

In AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

Create the in-app order on your server

Your server needs to call createInAppOrder() and return the receiveCode to your app. A minimal PHP backend:

// POST /api/create-payment
$order = $client->createInAppOrder($fabricToken, $_POST['title'], $_POST['amount']);
echo json_encode(['receiveCode' => $order['biz_content']['receiveCode']]);

Your Android app calls this endpoint and gets back the receiveCode.

Invoke the SDK

// Kotlin
import com.ethiopia.pay.sdk.EthiopiaPaySdk
import com.ethiopia.pay.sdk.PayCallback
 
class PaymentActivity : AppCompatActivity() {
 
    private fun startPayment(receiveCode: String) {
        EthiopiaPaySdk.pay(
            context = this,
            receiveCode = receiveCode,
            callback = object : PayCallback {
                override fun onResult(code: Int, message: String) {
                    when (code) {
                        0    -> onPaymentSucceeded()
                        -3   -> onPaymentCancelled()
                        -10  -> showInstallTelebirrPrompt()
                        else -> onPaymentError(code, message)
                    }
                }
            }
        )
    }
 
    private fun onPaymentSucceeded() {
        // SDK says success — still poll your server to confirm
        // before showing "payment complete" to user
        pollServerForOrderStatus()
    }
}

// Java
EthiopiaPaySdk.pay(
    this,
    receiveCode,
    (code, message) -> {
        if (code == 0) {
            pollServerForOrderStatus();
        } else if (code == -3) {
            showCancelledMessage();
        } else {
            showError(message);
        }
    }
);

Error codes

Code	Meaning
`0`	Payment succeeded (SDK local result)
`-1`	Unknown error
`-2`	Parameter error — check `receiveCode`
`-3`	User cancelled
`-10`	Telebirr app not installed
`-11`	Installed Telebirr version doesn’t support InApp

⚠️

SDK code 0 means the payment handoff completed in the Telebirr app. Wait for your server’s notify_url to receive the signed notification before marking the order as paid.

Common issues

Problem	Fix
`ClassNotFoundException` at runtime	Check that `flatDir` is registered in the right `build.gradle`
SDK not found after sync	Confirm `.aar` filename matches `implementation files(...)` exactly
Telebirr app opens but returns `-2`	`receiveCode` is malformed — check your server is returning the raw value from the API
Works in test, fails in production	Make sure you’re using the `-prod-release.aar`, not UAT

Overview