Service Process

The InApp SDK payment flow has two sides: your server and the mobile app (iOS/Android).

Flow overview

Mobile App          Your Server         Telebirr API
    |                    |                    |
    |—— initiate ———————>|                    |
    |                    |—— applyFabricToken >|
    |                    |<—— { token } ——————|
    |                    |                    |
    |                    |—— createInAppOrder >|
    |                    |<—— { receiveCode } -|
    |                    |                    |
    |<—— { receiveCode } |                    |
    |                    |                    |
    |—— SDK.pay(receiveCode) ————————————————>|
    |   [Telebirr payment UI appears]         |
    |<—— SDK callback (success/fail) —————————|
    |                    |                    |
    |                    |<—— POST /notify_url |
    |                    |   (verify sig)      |
    |                    |—— fulfill order     |
    |<—— update UI ——————|                    |

Step by step

1. Mobile app requests payment

Your app makes an API call to your own server (not Telebirr directly). Pass the order details: item name, amount.

2. Server gets a fabric token

Your server calls applyFabricToken() to get a short-lived bearer token. With the PHP library this is done automatically inside createInAppOrder() — you don’t need to call it separately unless you want to cache the token manually.

3. Server creates the in-app order

$order = $client->createInAppOrder($fabricToken, 'Item name', '50.00');
$receiveCode = $order['biz_content']['receiveCode'];

4. App invokes the SDK

Your app receives the receiveCode from your server and passes it to the native Telebirr SDK. The SDK shows the payment UI inside your app.

5. SDK callback

After the customer pays (or cancels), the SDK fires a callback in your app. This gives you a local result. Do not trust this alone — always wait for the server-side notification.

6. Server receives notification

Telebirr POSTs a signed JSON notification to your notify_url. Verify the signature with NotificationHandler::verify() and then fulfill the order.

7. App gets confirmation

Once your server has processed the notification, update your app’s UI to show payment success.

Server responsibilities

  • Get token + create order → return receiveCode to app
  • Verify incoming notification signature
  • Update order status and fulfill

App responsibilities

  • Pass receiveCode to the SDK
  • Listen for SDK callback
  • Show payment result to user
  • (optionally) poll your server for order status
Overview