telebirr wallet and finance data API

Ethio telecom SC · Payments

telebirr is Ethio telecom SC's mobile-money super-app for Ethiopia: customers sign in with an Ethio telecom MSISDN and PIN (or fingerprint), then send birr to a contact or merchant QR, buy airtime, pay ethio telecom bills and fuel, move money to a linked bank account, hold a USD wallet alongside the ETB balance, and open Mela micro-loans, Sanduq savings and Endekise overdraft from the finance tab. Chat pocket-money, request-money, scheduled transfers and a Visa PAN sit next to the home functions grid. It is the consumer counterpart of telebirr Partner, aimed at anyone with an Ethiopian mobile number, and it competes locally with CBE Birr, M-PESA Ethiopia and HelloCash as the telco's own wallet.

Wallet amount and multi-currency balances sit on the same customer ledger as Mela loanBalance and Sanduq availableBalance. Each row carries currency (ETB or USD), accountType and a balanceId; passbook lines add orderId, transType, oppositeName and transTime, while a receipt exposes tradeStatus and refundStatus.

P2P quotes issue a prepayId with feeAmount and actualAmount before PIN confirmation returns transId and orderStatus; bank payouts reuse bankShortCode and holderName. Credit partners read creditLimit, outstandingAmount and loanDueDate; savings partners read accruedInterest and maturityDate. CRM KYC (idNumber, woreda, kebele) and a rotating qrCode round out merchant and onboarding overlays. openData Studio turns those fields into callable open data.

Screenshots

API surface

The endpoints and request/response examples below are reconstructed from the app's interface — illustrative, not a live capture.

Sign in and load customer profile

POST /v1/mm/session/pin osint

Authenticates the subscriber and returns the session token plus the KYC profile used to render the home header (MSISDN, names, ID, customer level and receive-money QR).

Auth: MSISDN plus PIN (or biometric). No prior token. Response token and accessToken become X-Auth-Token on later calls; tokenRenewalEnable / tokenRenewalIntervalTime drive session renewal.

token
accessToken
encryptMsisdn
tokenRenewalEnable
tokenRenewalIntervalTime
customer.msisdn
customer.firstName
customer.idType
customer.idNumber
customer.customerLevel
qrCode

POST /v1/mm/session/pin HTTP/1.1
Content-Type: application/json

{"initiatorMsisdn":"2519xxxxxxx","initiatorPin":"******","pinVersion":"1"}

{
  "responseCode": "0",
  "responseDesc": "Success",
  "serverTimestamp": "2026-10-04T12:01:00Z",
  "token": "sess-8f21c4a0",
  "accessToken": "at-c91e2b77",
  "encryptMsisdn": "enc-msisdn",
  "supportPinLogin": "true",
  "tokenRenewalEnable": true,
  "tokenRenewalIntervalTime": 600000,
  "tokenRenewalLimit": 3,
  "qrCode": "000201...",
  "customer": {
    "msisdn": "251911223344",
    "firstName": "Abebe",
    "nickName": "Abebe",
    "idType": "NATIONAL_ID",
    "idNumber": "3124****",
    "idName": "Abebe Bekele",
    "customerLevel": "L2",
    "gender": "M",
    "birthday": "1990-03-12",
    "qrCode": "000201..."
  }
}

Read ETB wallet balance

GET /v1/mm/ledger/etb openbanking

Reads the primary telebirr ETB wallet balance shown on My Balance.

Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

amount
amountDisplay
currency
unit
unitType
responseCode

GET /v1/mm/ledger/etb HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Accept: application/json

{
  "responseCode": "0",
  "responseDesc": "Success",
  "amount": "1250.50",
  "amountDisplay": "1,250.50",
  "currency": "ETB",
  "unit": "ETB",
  "unitType": "FIAT"
}

List multi-currency wallet balances

GET /v1/mm/ledger/currencies openbanking

Returns the ETB main wallet, USD wallet and reward-balance rows that populate My Balance / My USD Balance.

Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

balances
balanceId
accountType
accountTypeAlias
accountTypeNameDisplay
amount
amountDisplay
currency
unit
unitType
forward

GET /v1/mm/ledger/currencies HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Accept: application/json

{
  "responseCode": "0",
  "balances": [
    {
      "balanceId": "BAL-ETB-1",
      "accountType": "MAIN",
      "accountTypeAlias": "telebirr",
      "accountTypeNameDisplay": "telebirr balance",
      "amount": "1250.50",
      "amountDisplay": "1,250.50",
      "currency": "ETB",
      "unit": "ETB",
      "unitType": "FIAT",
      "order": "1",
      "forward": "my_balance"
    },
    {
      "balanceId": "BAL-USD-1",
      "accountType": "USD",
      "accountTypeAlias": "usd_wallet",
      "accountTypeNameDisplay": "USD balance",
      "amount": "42.00",
      "amountDisplay": "42.00",
      "currency": "USD",
      "unit": "USD",
      "unitType": "FIAT",
      "order": "2",
      "forward": "my_usd_balance"
    }
  ]
}

Page wallet transaction history

GET /v1/mm/passbook openbanking

Pages the transaction-history screen: counterparty, type, amount and order id per wallet movement.

Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

transRecords
orderId
amount
amountDisplay
currency
transType
transTypeDisplay
oppositeName
executeOperatorName
transTime
startNum
count
filterTypes

GET /v1/mm/passbook?startNum=0&count=20&startTime=2026-09-01+00:00:00&endTime=2026-10-04+23:59:59 HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Accept: application/json

{
  "responseCode": "0",
  "transRecords": [
    {
      "orderId": "ORD-998877",
      "amount": "499.00",
      "amountDisplay": "499.00",
      "currency": "ETB",
      "transType": "P2P",
      "transTypeDisplay": "Transfer",
      "oppositeName": "Bekele Tadesse",
      "executeOperatorName": "Abebe Bekele",
      "transTime": 1759593600000
    }
  ]
}

Fetch transaction receipt detail

GET /v1/mm/passbook/{orderId} openbanking

Loads the receipt sheet for one wallet order, including refund/reverse flags and labeled tradeDetails rows.

Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

paymentOrderId
linkedOrderId
linkedOrderType
amount
amountDisplay
currency
businessType
tradeStatus
tradeStatusDesc
tradeDesc
refundStatus
reverseStatus
tradeDetails

GET /v1/mm/passbook/ORD-998877 HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Accept: application/json

{
  "responseCode": "0",
  "paymentOrderId": "PAY-998877",
  "linkedOrderId": "ORD-998877",
  "linkedOrderType": "P2P",
  "amount": "499.00",
  "amountDisplay": "499.00",
  "currency": "ETB",
  "businessType": "TRANSFER",
  "tradeStatus": "SUCCESS",
  "tradeStatusDesc": "Completed",
  "tradeDesc": "Send money",
  "refundStatus": "NONE",
  "reverseStatus": "NONE",
  "exportImage": true,
  "unit": "ETB",
  "unitType": "FIAT",
  "tradeDetails": [{"label": "Receiver", "value": "Bekele Tadesse"}]
}

Quote a wallet-to-wallet transfer

POST /v1/mm/p2p/quote openbanking

Quotes fee and debit amount for a P2P send and issues the prepayId the PIN confirmation screen submits.

Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token; requests carry initiatorMsisdn.

prepayId
oppositeName
originalAmount
feeAmount
actualAmount
balance
balanceDisplay
currency
expire

POST /v1/mm/p2p/quote HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Content-Type: application/json

{"initiatorMsisdn":"251911223344","receiverMsisdn":"251922334455","amount":"499.00","currency":"ETB"}

{
  "responseCode": "0",
  "prepayId": "PRE-441122",
  "oppositeName": "Bekele Tadesse",
  "originalAmount": "499.00",
  "originalAmountDisplay": "499.00",
  "feeAmount": "2.50",
  "feeAmountDisplay": "2.50",
  "actualAmount": "501.50",
  "actualAmountDisplay": "501.50",
  "balance": "1250.50",
  "balanceDisplay": "1,250.50",
  "currency": "ETB",
  "expire": "120",
  "unit": "ETB",
  "unitType": "FIAT"
}

Execute a wallet-to-wallet transfer

POST /v1/mm/p2p/commit openbanking

Commits a PIN-confirmed P2P transfer and returns orderId, transId and the debit breakdown shown on the result screen.

Auth: Session X-Auth-Token plus encrypted initiatorPin and pinVersion for money-moving calls.

prepayId
initiatorPin
pinVersion
notes
fundsSource
orderId
transId
orderStatus
originalAmount
feeAmount
actualAmount
currency
transTime

POST /v1/mm/p2p/commit HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Content-Type: application/json

{"prepayId":"PRE-441122","initiatorPin":"******","pinVersion":"1","notes":"rent","fundsSource":"WALLET"}

{
  "responseCode": "0",
  "orderId": "ORD-998877",
  "transId": "TXN-110022",
  "orderStatus": "SUCCESS",
  "businessType": "TRANSFER",
  "originalAmount": "499.00",
  "originalAmountDisplay": "499.00",
  "feeAmount": "2.50",
  "feeAmountDisplay": "2.50",
  "actualAmount": "501.50",
  "actualAmountDisplay": "501.50",
  "currency": "ETB",
  "transTime": "2026-10-04 12:05:11",
  "title": "Transfer successful"
}

List banks for wallet-to-bank payout

GET /v1/mm/banks openbanking

Lists destination banks (short code, masked account, holder name) for the Transfer to Bank picker.

Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

bankConfigs
recents
bankShortCode
bankName
bankNameI18n
bankAccountNo
holderName
showHolderName
logo

GET /v1/mm/banks HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Accept: application/json

{
  "responseCode": "0",
  "bankConfigs": [
    {
      "bankShortCode": "CBE",
      "bankName": "Commercial Bank of Ethiopia",
      "bankNameI18n": "Commercial Bank of Ethiopia",
      "bankAccountNo": "1000********12",
      "holderName": "Abebe Bekele",
      "showHolderName": "true"
    }
  ],
  "recents": []
}

Transfer wallet funds to a bank account

POST /v1/mm/payout/bank openbanking

Pays out ETB from the wallet to a linked bank card/account selected from the bank picker.

Auth: Session X-Auth-Token plus encrypted initiatorPin and pinVersion for money-moving calls.

bankCardId
amount
note
tradeType
orderId
transId
orderStatus
originalAmount
feeAmount
actualAmount
currency

POST /v1/mm/payout/bank HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Content-Type: application/json

{"initiatorMsisdn":"251911223344","bankCardId":"BC-88","amount":"800.00","note":"salary","tradeType":"WALLET_TO_BANK","initiatorPin":"******","pinVersion":"1"}

{
  "responseCode": "0",
  "orderId": "ORD-BANK-12",
  "transId": "TXN-BANK-12",
  "orderStatus": "SUCCESS",
  "originalAmount": "800.00",
  "feeAmount": "5.00",
  "actualAmount": "805.00",
  "currency": "ETB",
  "transTime": "2026-10-04 12:08:00"
}

Read Mela loan credit limit

GET /v1/mm/mela/limit openfinance

Loads the Mela / partner-bank credit limit and score that gate the loan-market and My telebirr Mela screens.

Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

creditLimit
creditScore
productList
productId
productName
avaiableLimit
minLimit
maxLimit
termDays
companyName
bankCode
fundsLenderId

GET /v1/mm/mela/limit?bankCode=CBE&fundsLenderId=LENDER-1 HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Accept: application/json

{
  "responseCode": "0",
  "creditLimit": "15000",
  "creditScore": "720",
  "productList": [
    {
      "productId": "MELA-STD",
      "productName": "telebirr Mela",
      "productNameI18n": "telebirr Mela",
      "companyName": "Commercial Bank of Ethiopia",
      "avaiableLimit": "12000",
      "minLimit": "100",
      "maxLimit": "15000",
      "termDays": 30,
      "allowApplyNPL": true
    }
  ]
}

List Mela loan products and contracts

GET /v1/mm/mela/contracts openfinance

Lists the subscriber's Mela contracts with outstanding, principal and due date for My telebirr Mela.

Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

active
totalCreditAmount
totalOutstandingAmount
totalPaidAmount
contracts
contractId
loanBalance
outstandingAmount
principal
disburseAmount
loanDueDate
status
currentInstallment
totalInstallments

GET /v1/mm/mela/contracts HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Accept: application/json

{
  "responseCode": "0",
  "active": true,
  "currency": "ETB",
  "totalCreditAmount": "15000.00",
  "totalOutstandingAmount": "3200.00",
  "totalPaidAmount": "1800.00",
  "contracts": [
    {
      "contractId": "CTR-1001",
      "productId": "MELA-STD",
      "productName": "telebirr Mela",
      "loanBalance": "3200.00",
      "outstandingAmount": "3200.00",
      "principal": "3000.00",
      "principalAmount": "3000.00",
      "disburseAmount": "3000.00",
      "loanDueDate": "2026-11-01",
      "status": "ACTIVE",
      "isActive": true,
      "currentInstallment": "1",
      "totalInstallments": "1",
      "currency": "ETB"
    }
  ]
}

Read a Mela loan contract

GET /v1/mm/mela/contracts/{contractId} openfinance

Opens one Mela contract with repayment schedule and disbursement/repay ledger lines.

Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

contractId
loanBalance
outstandingAmount
principal
disburseAmount
loanDueDate
status
allowRollover
repaymentSchedules
transactionList
transactionId
transactionAmount
transactionType
walletOrderID

GET /v1/mm/mela/contracts/CTR-1001 HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Accept: application/json

{
  "responseCode": "0",
  "contractId": "CTR-1001",
  "productName": "telebirr Mela",
  "loanBalance": "3200.00",
  "outstandingAmount": "3200.00",
  "principal": "3000.00",
  "disburseAmount": "3000.00",
  "loanDueDate": "2026-11-01",
  "status": "ACTIVE",
  "allowRollover": true,
  "allowIntall": false,
  "repaymentSchedules": [{"dueDate": "2026-11-01", "amount": "3200.00"}],
  "transactionList": [
    {
      "transactionId": "LTX-1",
      "orderID": "ORD-LOAN-1",
      "walletOrderID": "WO-1",
      "transactionAmount": "3000.00",
      "transactionType": "DISBURSE",
      "transactionTitle": "Loan disbursement",
      "transactionTime": "2026-09-01 10:00:00",
      "transfer": "In",
      "balance": "3000.00",
      "currency": "ETB"
    }
  ]
}

List Sanduq saving accounts

GET /v1/mm/sanduq/accounts openfinance

Lists Sanduq / locked-saving accounts with principal, accrued interest, rate and maturity for My telebirr saving.

Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

accountItems
accountNo
productName
balance
availableBalance
frozenBalance
principalAmount
accruedInterest
productRateValue
maturityDate
openAccountDate
status
currency

GET /v1/mm/sanduq/accounts HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Accept: application/json

{
  "responseCode": "0",
  "numberOfTotal": "1",
  "startNumberOfReturned": "1",
  "endNumberOfReturned": "1",
  "accountItems": [
    {
      "accountNo": "SAV-4401",
      "custAccountNo": "CA-4401",
      "accountType": "LOCKED",
      "productID": "SANDUQ-30",
      "productUnquieID": "SANDUQ-30-A",
      "productName": "telebirr Sanduq",
      "productNameI18N": "telebirr Sanduq",
      "balance": "5000.00",
      "availableBalance": "5000.00",
      "frozenBalance": "0.00",
      "unclearingBalance": "0.00",
      "principalAmount": "5000.00",
      "accruedInterest": "41.10",
      "productRateValue": "10",
      "productRateValueMode": "YEAR",
      "maturityDate": "2026-12-01",
      "openAccountDate": "2026-09-01",
      "status": "ACTIVE",
      "currency": "ETB"
    }
  ]
}

Wallet spend analytics (daily graph)

GET /v1/mm/spend/daily opendata

Feeds the in-app spend graph: period credit/debit totals and per-day bars.

Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

totalCreditAmount
totalDebitAmount
totalTransactionCount
transactionDailyList
daily
creditAmount
debitAmount

GET /v1/mm/spend/daily?startTime=2026-09-01&endTime=2026-09-30 HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Accept: application/json

{
  "responseCode": "0",
  "totalCreditAmount": "12000.00",
  "totalDebitAmount": "8450.00",
  "totalTransactionCount": "37",
  "transactionDailyList": [
    {"daily": "2026-09-12", "creditAmount": "500.00", "debitAmount": "120.00"}
  ]
}

Issue a receive-money QR

POST /v1/mm/receive/qr openbanking

Issues the rotating merchant/person QR shown on 'use telebirr scan to pay me'.

Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

qrCode
qrCodes
effectiveTime
expiredTime
refreshTime

POST /v1/mm/receive/qr HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Content-Type: application/json

{"initiatorMsisdn":"251911223344"}

{
  "responseCode": "0",
  "qrCode": "000201...",
  "qrCodes": [
    {
      "qrCode": "000201...",
      "effectiveTime": "2026-10-04T12:00:00Z",
      "expiredTime": "2026-10-04T12:05:00Z",
      "refreshTime": "30"
    }
  ]
}

Fetch CRM KYC record

GET /v1/mm/kyc/profile osint

Pulls the ethio telecom CRM KYC record (names, national ID, woreda/kebele address, photo) used in upgrades and profile.

Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

firstName
middleName
lastName
idNumber
dateOfBirth
gender
nationality
region
city
woreda
kebele
zone
isRegisteredInCRM
photo

GET /v1/mm/kyc/profile HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Accept: application/json

{
  "responseCode": "0",
  "firstName": "Abebe",
  "middleName": "Kebede",
  "lastName": "Bekele",
  "idNumber": "3124****",
  "dateOfBirth": "1990-03-12",
  "gender": "M",
  "nationality": "ET",
  "nationalityDisplay": "Ethiopian",
  "region": "Addis Ababa",
  "regionDisplay": "Addis Ababa",
  "city": "Addis Ababa",
  "woreda": "04",
  "kebele": "12",
  "zone": "Arada",
  "isRegisteredInCRM": "true",
  "photo": "base64..."
}

Quote USD–ETB exchange rate
GET /v1/mm/fx/quote openfinance
Returns the USD-to-ETB rate used on My USD Balance before a currency-exchange debit.
Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.
- sourceCurrency
- targetCurrency
- exchangeRate
- responseCode
```
GET /v1/mm/fx/quote?sourceCurrency=USD&targetCurrency=ETB HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Accept: application/json
```
```
{
  "responseCode": "0",
  "responseDesc": "Success",
  "exchangeRate": "57.2500"
}
```
Read issued Visa PAN
GET /v1/mm/card/visa openbanking
Loads the subscriber's issued Visa PAN (or apply=false) for My Visa PAN.
Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.
- apply
- visaPAN
- visaBackgroundUrl
- responseCode
```
GET /v1/mm/card/visa HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Accept: application/json
```
```
{
  "responseCode": "0",
  "apply": true,
  "visaPAN": "4***********1234"
}
```
Read Endekise overdraft limit
GET /v1/mm/endekise/limit openfinance
Reads Endekise credit-pay availableLimit and totalLimit cached on the home credit-pay tile.
Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.
- limitInfo
- limitInfo.currency
- availableLimit
- totalLimit
- serverTimestamp
- initiatorMsisdn
```
GET /v1/mm/endekise/limit HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Accept: application/json
```
```
{
  "responseCode": "0",
  "serverTimestamp": "2026-10-04T12:10:00Z",
  "limitInfo": {
    "currency": "ETB",
    "availableLimit": "2500.00",
    "totalLimit": "5000.00"
  }
}
```

List Endekise overdraft contracts

GET /v1/mm/endekise/contracts openfinance

Lists Endekise credit-pay contracts with unpaid/paid amounts and due dates for Credit Pay Home.

Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

availableLimit
totalLimit
totalPaidAmount
totalUnpaidAmount
contracts
contractId
contractName
contractState
outstandingAmount
paidAmount
dueDate
periodStartDate

GET /v1/mm/endekise/contracts HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Accept: application/json

{
  "responseCode": "0",
  "active": true,
  "availableLimit": "2500.00",
  "totalLimit": "5000.00",
  "totalPaidAmount": "800.00",
  "totalUnpaidAmount": "1200.00",
  "currency": "ETB",
  "contracts": [
    {
      "contractId": "OD-2201",
      "contractName": "Endekise",
      "contractState": "ACTIVE",
      "outstandingAmount": "1200.00",
      "paidAmount": "800.00",
      "disburseAmount": "2000.00",
      "principal": "2000.00",
      "totalAmount": "2000.00",
      "dueDate": "2026-10-31",
      "periodStartDate": "2026-10-01",
      "isActive": true
    }
  ]
}

List request-money orders

GET /v1/mm/collect/orders openbanking

Lists request-money (collect) orders with payee/payer identifiers and status for the Request Money inbox.

Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

totalCount
requestMoneyOrderInfos
requestMoneyOrderId
amount
payAmount
currency
payeeName
payeeIdentifier
payerName
payerIdentifier
status
statusDisplay
paymentMethod

GET /v1/mm/collect/orders HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Accept: application/json

{
  "responseCode": "0",
  "totalCount": "2",
  "requestMoneyOrderInfos": [
    {
      "requestMoneyOrderId": "RM-7788",
      "amount": "250.00",
      "payAmount": "250.00",
      "currency": "ETB",
      "payeeName": "Abebe Bekele",
      "payeeIdentifier": "251911223344",
      "payerName": "Bekele Tadesse",
      "payerIdentifier": "251922334455",
      "status": "PENDING",
      "statusDisplay": "Waiting",
      "paymentMethod": "WALLET"
    }
  ]
}

List scheduled automatic payments

GET /v1/mm/schedules openbanking

Lists Automatic Payment schedules (amount, frequency, receiver MSISDN and reminder window) shown on the scheduled-transfer screen.

Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

reminderScheduleInfoDetails
reminderScheduleId
scheduleName
amount
currency
frequency
receiverMsisdn
firstPaymentReminderDate
issuePaymentReminderUntil
transactionType
needConfirmation
initiatorIdentifier

GET /v1/mm/schedules HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Accept: application/json

{
  "responseCode": "0",
  "reminderScheduleInfoDetails": [
    {
      "reminderScheduleId": "SCH-3301",
      "scheduleName": "Rent",
      "amount": "8000.00",
      "currency": "ETB",
      "frequency": "5",
      "receiverMsisdn": "251922334455",
      "firstPaymentReminderDate": "2026-11-01",
      "issuePaymentReminderUntil": "2027-11-01",
      "transactionType": "TRANSFER",
      "needConfirmation": "true",
      "initiatorIdentifier": "251911223344"
    }
  ]
}

List airtime recharge denominations

GET /v1/mm/airtime/denoms openbanking

Loads Buy Airtime denominations (operator shortCode and priceId / finalPrice) for the airtime picker.

Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

topUpPageData
currency
customPriceId
operators
operatorName
shortCode
prices
priceId
priceDisplay
finalPrice
mode
discountDesc

GET /v1/mm/airtime/denoms HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Accept: application/json

{
  "responseCode": "0",
  "topUpPageData": {
    "currency": "ETB",
    "customPriceId": "CUSTOM",
    "operators": [
      {
        "operatorName": "ethio telecom",
        "shortCode": "251",
        "prices": [
          {
            "priceId": "AIR-50",
            "priceDisplay": "50.00",
            "finalPrice": "50.00",
            "mode": "0",
            "operatorShortCode": "251",
            "order": "1",
            "discountDesc": ""
          }
        ]
      }
    ]
  }
}

Quote a fuel payment

POST /v1/mm/fuel/quote openbanking

Quotes a fuel payment (amount plus labeled displayItems) before PIN confirmation on Pay Fuel.

Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

amount
displayItems

POST /v1/mm/fuel/quote HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Content-Type: application/json

{"initiatorMsisdn":"251911223344","amount":"1500.00","currency":"ETB"}

{
  "responseCode": "0",
  "amount": "1500.00",
  "displayItems": [
    {"label": "Station", "value": "NOC Addis"},
    {"label": "Plate", "value": "AA-3-12345"}
  ]
}

List billers for scheduled payments

GET /v1/mm/billers opendata

Lists billers (code, name, reference label) that Automatic Payment can schedule against.

Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

billerItems
billerCode
billerName
referenceName

GET /v1/mm/billers HTTP/1.1
X-Auth-Token: sess-8f21c4a0
Accept: application/json

{
  "responseCode": "0",
  "billerItems": [
    {
      "billerCode": "ETHIO-TEL",
      "billerName": "ethio telecom",
      "referenceName": "Account number"
    },
    {
      "billerCode": "AAWSA",
      "billerName": "Addis water",
      "referenceName": "Customer ID"
    }
  ]
}

Where teams use this data

ETB wallet reconciliation
Nightly jobs read amount / amountDisplay from the main wallet and the balances[] rows (accountType, currency, balanceId) so an ERP or agent till can match telebirr cash-in against its own ledger, including the USD wallet.
P2P and bank-payout ops
Collections platforms consume prepayId, feeAmount and actualAmount from the transfer quote, then settle on orderId / transId / orderStatus after PIN confirmation, fan wallet-to-bank payouts out through bankShortCode / bankAccountNo / holderName, and match request-money collects on requestMoneyOrderId / payeeIdentifier / status.
Mela, Sanduq and Endekise servicing
Credit and savings partners sync creditLimit, loanBalance, outstandingAmount and loanDueDate for Mela contracts, availableBalance, accruedInterest and maturityDate for Sanduq accounts, and availableLimit / totalLimit plus Endekise contractId / dueDate on the overdraft book.
KYC, airtime and receive-QR overlay
Onboarding and merchant tools reuse CRM firstName / idNumber / woreda / kebele plus the rotating qrCode with expiredTime, while airtime desks pull operators[].prices[].priceId / finalPrice and billers list billerCode / billerName without storing the PIN.

Frequently asked questions

What wallet balances does telebirr expose?

The main ETB wallet returns amount, amountDisplay, currency and unit. A multi-currency list then returns balances[] with balanceId, accountType (MAIN / USD / reward), amount and a forward key used to open My Balance or My USD Balance.

How are P2P transfers authorized?

After PIN (or fingerprint) sign-in the app sends token / accessToken as X-Auth-Token. A send first quotes prepayId, feeAmount and actualAmount, then commits with encrypted initiatorPin and pinVersion. The result carries orderId, transId and orderStatus.

Does the surface cover Mela loans and Sanduq savings?

Yes. The Mela limit call returns creditLimit and creditScore with product min/max limits; the contract list returns loanBalance, outstandingAmount and loanDueDate. Sanduq accounts return accountNo, availableBalance, accruedInterest, productRateValue and maturityDate.

Which identity fields come back after login?

Sign-in embeds customer.msisdn, firstName, idType, idNumber and customerLevel. The CRM KYC record adds middleName, lastName, dateOfBirth, nationality, region, city, woreda, kebele and photo from ethio telecom CRM.

More Payments apps

Topics

telebirr API
telebirr wallet balance
Ethio telecom mobile money
Mela loan API
Sanduq savings
ETB P2P transfer
telebirr KYC

Need this app's data API integrated?

We deliver scoped integrations for any named app — from USD 500 with source-code handoff, or hosted access billed per call. Tell us the data you need.

NDA + SOW on every engagement
Delivery in 3–7 days
Payment only after acceptance
Work scoped to authorized use

Get a quote

telebirr wallet and finance data API

Screenshots

API surface

Sign in and load customer profile

Read ETB wallet balance

List multi-currency wallet balances

Page wallet transaction history

Fetch transaction receipt detail

Quote a wallet-to-wallet transfer

Execute a wallet-to-wallet transfer

List banks for wallet-to-bank payout

Transfer wallet funds to a bank account

Read Mela loan credit limit

List Mela loan products and contracts

Read a Mela loan contract

List Sanduq saving accounts

Wallet spend analytics (daily graph)

Issue a receive-money QR

Fetch CRM KYC record

Quote USD–ETB exchange rate

Read issued Visa PAN

Read Endekise overdraft limit

List Endekise overdraft contracts

List request-money orders

List scheduled automatic payments

List airtime recharge denominations

Quote a fuel payment

List billers for scheduled payments

Data categories

Where teams use this data

ETB wallet reconciliation

P2P and bank-payout ops

Mela, Sanduq and Endekise servicing

KYC, airtime and receive-QR overlay

Frequently asked questions

More Payments apps

CashBook - Balance & Expense

Dhan Barse

IndianOil ONE

inyad Konnash: Bookkeeping App

Topics

Need this app's data API integrated?