iOS Integration

Integrate EthiopiaPaySDK.framework into your Xcode project to enable in-app Telebirr payments.

The SDK uses a local framework dependency — it’s not available via CocoaPods or Swift Package Manager yet.

Download the framework

Get the framework from the Telebirr Developer Portal. There are separate builds for test and production environments.

Add the framework to Xcode

Copy EthiopiaPaySDK.framework into your Xcode project directory, then:

In Xcode: Target → General → Frameworks, Libraries, and Embedded Content
Add the framework and set it to Embed & Sign

Configure URL schemes

Step 3a — Queried URL Schemes

In Target → Info → LSApplicationQueriesSchemes, add:

telebirrcustomerApp

This lets your app check if the Telebirr app is installed (needed for SDK error code -10).

Step 3b — URL Types (your app’s scheme)

In Target → Info → URL Types, add a URL scheme for your app (e.g. myapp). The SDK uses this to return focus to your app after payment.

Handle SDK return in AppDelegate

In AppDelegate.m (or AppDelegate.swift), implement application:openURL:options::

// Objective-C
- (BOOL)application:(UIApplication *)app
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
    return [EthiopiaPaySDK handleOpenURL:url];
}

// Swift
func application(_ app: UIApplication, open url: URL,
                 options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    return EthiopiaPaySDK.handleOpen(url)
}

Import the SDK header

// In your payment view controller
#import <EthiopiaPaySDK/EthiopiaPaySDK.h>

// Swift — no explicit import needed after framework is linked

Invoke the SDK

Pass the receiveCode from your server and the URL scheme you registered in step 3b:

// Objective-C
[EthiopiaPaySDK payWithReceiveCode:receiveCode
                         returnApp:@"myapp"
                          delegate:self];

// Swift
EthiopiaPaySDK.pay(withReceiveCode: receiveCode, returnApp: "myapp", delegate: self)

Handle the payment result

Implement the SDK delegate:

// Objective-C
- (void)onPayResult:(int)resultCode message:(NSString *)message {
    switch (resultCode) {
        case 0:
            // Payment succeeded locally — still wait for server notification
            [self pollOrderStatus];
            break;
        case -3:
            [self showCancelledMessage];
            break;
        default:
            [self showError:message];
    }
}

// Swift
func onPayResult(_ resultCode: Int32, message: String) {
    switch resultCode {
    case 0:     pollOrderStatus()
    case -3:    showCancelledMessage()
    default:    showError(message)
    }
}

Error codes

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

⚠️

SDK code 0 means the app-to-app handoff succeeded. It does not guarantee the payment completed. Always verify the server-side notification (Step 4) before fulfilling the order.

Overview