Development Preparation

Same credentials as the H5 C2B flow — one set of API keys works for both integration types.

Register with Telebirr

Apply for merchant access through the Telebirr Developer Portal. You’ll need:

Organization name
Contact person and phone number
Business scope and address

After approval, you’ll receive credentials by email.

Get your credentials

Credential	What it is	Where it goes
`Merchant App ID`	Your app identifier	`merchantAppId` in `Config`
`Merchant Short Code`	6-digit merchant code	`merchantCode` in `Config`
`App Secret`	Used to fetch fabric tokens	`appSecret` in `Config`
`Fabric App ID`	Sent as `X-APP-Key` header	`fabricAppId` in `Config`

Generate RSA keys

Generate a separate key pair for test and production:

# Private key (keep this secret)
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private-key.pem
 
# Public key (share this with Telebirr)
openssl pkey -in private-key.pem -out public-key.pem -pubout

⚠️

Never commit your private key to version control. Load it from an environment variable or secrets manager. The library accepts a PEM string — read it from the filesystem at startup.

Send your public-key.pem content to Telebirr. They register it and use it to verify your signed requests.

Configure the PHP library

use Melaku\Telebirr\Config;
 
// Test environment
$config = Config::forTest([
    'appSecret'     => $_ENV['TELEBIRR_APP_SECRET'],
    'fabricAppId'   => $_ENV['TELEBIRR_FABRIC_APP_ID'],
    'merchantAppId' => $_ENV['TELEBIRR_MERCHANT_APP_ID'],
    'merchantCode'  => $_ENV['TELEBIRR_MERCHANT_CODE'],
    'notifyUrl'     => 'https://your-site.com/pay/notify',
    'privateKey'    => file_get_contents('/path/to/private-key.pem'),
]);
 
// Production — same keys, different URL
$config = Config::forProduction([/* same options */]);

Or from environment variables directly:

// Reads from TELEBIRR_* env vars automatically
$config = Config::fromEnvironment([
    'notifyUrl' => 'https://your-site.com/pay/notify',
    'privateKey' => file_get_contents('/path/to/private-key.pem'),
]);

Download the mobile SDK

Platform	File	Environment
iOS	`EthiopiaPaySDK.framework`	Test / Production (separate downloads)
Android	`EthiopiaPaySdkModule-uat-release.aar`	Test
Android	`EthiopiaPaySdkModule-prod-release.aar`	Production

See iOS Integration or Android Integration for setup.

Overview