Step 2: Create In-App Order

Call createInAppOrder() on your server. You get back a receiveCode — pass it to the mobile SDK to start the payment UI.

The key difference from the web flow: trade_type is "InApp" and the endpoint returns a receiveCode instead of a prepay_id for URL assembly.


The library way

use Melaku\Telebirr\Telebirr;
use Melaku\Telebirr\Exceptions\ApiException;
use Melaku\Telebirr\Exceptions\InvalidParameterException;
 
$client = new Telebirr($config);
 
try {
    $tokenInfo   = $client->applyFabricToken();
    $fabricToken = $tokenInfo['token'];
 
    $order       = $client->createInAppOrder($fabricToken, 'Diamond Pack', '50.00');
    $receiveCode = $order['biz_content']['receiveCode'];
    $prepayId    = $order['biz_content']['prepay_id'];
    $merchOrderId = $order['biz_content']['merch_order_id'];
 
    // Return receiveCode to your mobile app
    echo json_encode(['receiveCode' => $receiveCode]);
 
} catch (InvalidParameterException $e) {
    http_response_code(400);
    echo json_encode(['error' => $e->getMessage()]);
} catch (ApiException $e) {
    http_response_code(500);
    echo json_encode(['error' => $e->getMessage()]);
}
⚠️

Merchant order ID rules: alphanumeric only — ^[A-Za-z0-9]+$. No underscores, hyphens, or special characters. Pass null to let the library generate a valid one.

Store merch_order_id in your database against the order record. Telebirr echoes it back in the notification — it’s your lookup key.


Raw API (all languages)

The endpoint is /payment/v1/inapp/createOrder with trade_type: "InApp".

$timestamp    = (string) time();
$nonceStr     = bin2hex(random_bytes(16));
$merchOrderId = (string) time(); // alphanumeric only
 
$biz = [
    'notify_url'      => 'https://your-site.com/pay/notify',
    'trade_type'      => 'InApp',                 // <— key difference
    'appid'           => $merchantAppId,
    'merch_code'      => $merchantCode,
    'merch_order_id'  => $merchOrderId,
    'title'           => 'Diamond Pack',
    'total_amount'    => '50.00',
    'trans_currency'  => 'ETB',
    'timeout_express' => '120m',
];
 
$req = [
    'timestamp'   => $timestamp,
    'nonce_str'   => $nonceStr,
    'method'      => 'payment.preorder',
    'version'     => '1.0',
    'biz_content' => $biz,
];
 
$req['sign']      = signRequestObject($req);
$req['sign_type'] = 'SHA256WithRSA';
 
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => $baseUrl . '/payment/v1/inapp/createOrder',
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-APP-Key: ' . $fabricAppId,
        'Authorization: ' . $fabricToken,
    ],
    CURLOPT_POSTFIELDS => json_encode($req),
]);
 
$response    = json_decode(curl_exec($ch), true);
$receiveCode = $response['biz_content']['receiveCode'];

Response

{
  "result": "SUCCESS",
  "code": "0",
  "msg": "success",
  "biz_content": {
    "merch_order_id": "1705460512562",
    "prepay_id": "080075a4e3213924de2b3b84ad3cac0a6a6001",
    "receiveCode": "TELEBIRR$BUYGOODS$100100306$50.00$080075a4e3213924de2b3b84ad3cac0a6a6001$120m"
  }
}

Pass receiveCode to the mobile SDK. Store merch_order_id and prepay_id against your order.

Next: Step 3 — CheckOut →