Step 1: Apply Fabric Token

Every Telebirr API call requires a short-lived bearer token. You get it by POSTing your appSecret to the token endpoint. The token is valid for about 60 minutes.

With the PHP or JS/TS library, you never call this manually. createCheckoutUrl() fetches the token internally before every order. If you’re using a library, skip to Step 2 or the overview quickstart.

The library way

use Melaku\Telebirr\Config;
use Melaku\Telebirr\Telebirr;
 
$config = Config::forTest([/* your credentials */]);
$client = new Telebirr($config);
 
// Normally you don't call this yourself — createCheckoutUrl() does it.
// But if you need the token directly:
$tokenInfo = $client->applyFabricToken();
 
echo $tokenInfo['token'];          // "Bearer 94cc42bee41..."
echo $tokenInfo['expirationDate']; // "20221101142422"

Since v2.2.0 the library caches the token until expirationDate automatically — createCheckoutUrl() and getOrderStatus() reuse it instead of re-fetching. Opt out with new Telebirr($config, null, null, ['cacheFabricToken' => false]).

Raw API (all languages)

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => 'https://developerportal.ethiotelebirr.et:38443'
                              . '/apiaccess/payment/gateway/payment/v1/token',
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-APP-Key: ' . $fabricAppId,
    ],
    CURLOPT_POSTFIELDS     => json_encode(['appSecret' => $appSecret]),
]);
 
$response = json_decode(curl_exec($ch), true);
$token    = $response['token'];  // "Bearer ..."

const BASE_URL = 'https://developerportal.ethiotelebirr.et:38443/apiaccess/payment/gateway'
 
async function applyFabricToken(fabricAppId: string, appSecret: string): Promise<string> {
  const res = await fetch(`${BASE_URL}/payment/v1/token`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-APP-Key': fabricAppId,
    },
    body: JSON.stringify({ appSecret }),
  })
 
  const data = await res.json()
 
  if (!data.token) {
    throw new Error(`Token request failed: ${JSON.stringify(data)}`)
  }
 
  return data.token // "Bearer 94cc42bee41..."
}

import requests
 
BASE_URL = "https://developerportal.ethiotelebirr.et:38443/apiaccess/payment/gateway"
 
def apply_fabric_token(fabric_app_id: str, app_secret: str) -> str:
    resp = requests.post(
        f"{BASE_URL}/payment/v1/token",
        headers={
            "Content-Type": "application/json",
            "X-APP-Key": fabric_app_id,
        },
        json={"appSecret": app_secret},
        verify=False,  # test env has a self-signed cert
    )
    resp.raise_for_status()
    data = resp.json()
 
    if "token" not in data:
        raise ValueError(f"Token missing in response: {data}")
 
    return data["token"]  # "Bearer 94cc42bee41..."

Endpoint reference

POST /payment/v1/token

Request headers

Header	Value
`Content-Type`	`application/json`
`X-APP-Key`	Your Fabric App ID (from the developer portal)

Request body

Field	Type	Required	Description
`appSecret`	string	✅	App Secret from the Fabric portal

Response

Field	Type	Description
`token`	string	Bearer token — prefix `Authorization` header with this value as-is
`effectiveDate`	string	Token start time (`YYYYMMddHHmmss`)
`expirationDate`	string	Token expiry time (`YYYYMMddHHmmss`) — cache until this

Example response

{
  "effectiveDate": "20221101132422",
  "expirationDate": "20221101142422",
  "token": "Bearer 94cc42bee412696d754508c06ca1db20"
}

⚠️

Token expiry gotcha: tokens expire after 60 minutes. If you hard-code a fresh token fetch before every order (like the official samples do), you’ll burn your rate limit. Cache the token with its expirationDate and re-fetch only when it expires.

Introduction Step 2: Create Order