Step 3: Checkout URL

Take the prepay_id from Step 2, sign a second set of parameters, assemble a URL, and redirect the customer to it.

PHP and JS/TS libraries: createCheckoutUrl() returns a CheckoutResult with the URL ready. buildCheckoutUrl(prepayId) is also available if you’re calling steps individually.

The library way

// High-level — does Steps 1, 2, and 3 together
$result = (new Telebirr($config))->createCheckoutUrl('Order #42', '199.99');
header('Location: ' . $result->getCheckoutUrl());
 
// — OR — lower-level if you already have a prepay_id
$checkoutUrl = $client->buildCheckoutUrl($prepayId);
header('Location: ' . $checkoutUrl);

Raw API (all languages)

The checkout URL is not an API call — it’s a signed query string appended to the web base URL. You build it locally and redirect the browser.

function buildCheckoutUrl(string $prepayId, array $cfg): string {
    $map = [
        'appid'      => $cfg['merchantAppId'],
        'merch_code' => $cfg['merchantCode'],
        'nonce_str'  => bin2hex(random_bytes(16)),
        'prepay_id'  => $prepayId,
        'timestamp'  => (string) time(),
    ];
 
    // Sort keys by ASCII order, join as key=value&...
    ksort($map);
    $rawStr = http_build_query($map);
 
    // Sign with SHA256WithRSA PSS
    $sign = signString($rawStr, $cfg['privateKeyPem']);
 
    $params = http_build_query(array_merge($map, [
        'sign'       => $sign,
        'sign_type'  => 'SHA256WithRSA',
        'version'    => '1.0',
        'trade_type' => 'Checkout',
    ]));
 
    return $cfg['webBaseUrl'] . $params;
}
 
$url = buildCheckoutUrl($prepayId, $cfg);
header('Location: ' . $url);

import crypto from 'crypto'
 
function buildCheckoutUrl(prepayId: string, cfg: {
  merchantAppId: string
  merchantCode: string
  privateKeyPem: string
  webBaseUrl: string
}): string {
  const map: Record<string, string> = {
    appid:      cfg.merchantAppId,
    merch_code: cfg.merchantCode,
    nonce_str:  crypto.randomBytes(16).toString('hex'),
    prepay_id:  prepayId,
    timestamp:  String(Math.floor(Date.now() / 1000)),
  }
 
  // Sort by ASCII key order
  const rawStr = Object.keys(map).sort().map(k => `${k}=${map[k]}`).join('&')
 
  const sign = crypto.createSign('SHA256')
  sign.update(rawStr)
  const signature = sign.sign(
    { key: cfg.privateKeyPem, padding: crypto.constants.RSA_PKCS1_PSS_PADDING },
    'base64'
  )
 
  const params = new URLSearchParams({
    ...map,
    sign: signature,
    sign_type: 'SHA256WithRSA',
    version: '1.0',
    trade_type: 'Checkout',
  })
 
  return cfg.webBaseUrl + params.toString()
}
 
// In an Express handler:
res.redirect(buildCheckoutUrl(prepayId, cfg))

import time, base64, random, string
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.backends import default_backend
from urllib.parse import urlencode
 
def build_checkout_url(prepay_id: str, cfg: dict) -> str:
    params = {
        "appid":      cfg["merchant_app_id"],
        "merch_code": cfg["merchant_code"],
        "nonce_str":  "".join(random.choices(string.ascii_uppercase + string.digits, k=32)),
        "prepay_id":  prepay_id,
        "timestamp":  str(int(time.time())),
    }
 
    raw = "&".join(f"{k}={params[k]}" for k in sorted(params))
 
    private_key = serialization.load_pem_private_key(
        cfg["private_key_pem"].encode(), password=None, backend=default_backend()
    )
    signature = private_key.sign(
        raw.encode(),
        padding.PSS(mgf=padding.MGF1(hashes.SHA256()), salt_length=padding.PSS.MAX_LENGTH),
        hashes.SHA256(),
    )
    params["sign"]       = base64.b64encode(signature).decode()
    params["sign_type"]  = "SHA256WithRSA"
    params["version"]    = "1.0"
    params["trade_type"] = "Checkout"
 
    return cfg["web_base_url"] + urlencode(params)
 
# In a Flask view:
# return redirect(build_checkout_url(prepay_id, cfg))

URL structure

https://developerportal.ethiotelebirr.et:38443/payment/web/paygate?
  appid=930231098961202
  &merch_code=123456
  &nonce_str=XG9C5S6R0NLEYF1AGYW5BT237SMDYCUH
  &prepay_id=007a6bd3175cdb3c658545...
  &timestamp=1684481139
  &sign=BC4EE8D710BAC6A7E33DE...
  &sign_type=SHA256WithRSA
  &version=1.0
  &trade_type=Checkout

The customer lands on the Telebirr payment page, enters their phone and PIN, and the payment completes. Telebirr then:

POSTs a signed notification to your notify_url
Redirects the customer to your redirect_url

⚠️

Don’t trust the redirect URL parameters to confirm payment. They can be spoofed. Always wait for the server-side notification (Step 4) or call queryOrder() before fulfilling the order.

After the customer pays, head to Step 4 →

Step 2: Create Order Step 4: Notify / Callback