OpenAPI v3.0 Specification

API Reference

REST API endpoints for initiating payment sessions, checking transaction statuses, and executing Amharic NLP tokenization.

Base URL: `https://api.zemen.com.et`· HTTPS SSL Required

POST/v1/payments/initialize

Initialize Payment Session

Creates a payment session for Telebirr, CBE Birr, or Chapa. Returns a checkout URL and transaction reference.

Required Headers:Authorization: Bearer <API_KEY>Content-Type: application/json

Request Example (cURL)

curl -X POST https://api.zemen.com.et/v1/payments/initialize \
  -H "Authorization: Bearer zm_live_98127391823" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500.00,
    "currency": "ETB",
    "payment_method": "telebirr",
    "customer_phone": "+251911002233"
  }'

Response Example (JSON 200 OK)

{
  "status": "success",
  "transaction_id": "zm_tx_881923012",
  "checkout_url": "https://pay.zemen.com.et/checkout/zm_tx_881923012",
  "expires_at": "2026-08-04T20:30:00Z"
}

GET/v1/payments/verify/{transaction_id}

Verify Payment Status

Queries the status of a specific transaction directly against banking or Telebirr ledger reconciliation endpoints.

Required Headers:Authorization: Bearer <API_KEY>

Request Example (cURL)

curl -X GET https://api.zemen.com.et/v1/payments/verify/zm_tx_881923012 \
  -H "Authorization: Bearer zm_live_98127391823"

Response Example (JSON 200 OK)

{
  "status": "completed",
  "transaction_id": "zm_tx_881923012",
  "amount": 2500.00,
  "currency": "ETB",
  "payment_method": "telebirr",
  "settlement_ref": "FT260804000918",
  "paid_at": "2026-08-04T18:14:02Z"
}

POST/v1/ai/amharic/tokenize

Amharic Text Tokenization

Parses raw Ge'ez script text and outputs tokenized phonemes, root morphemes, and sentiment scores.

Required Headers:Authorization: Bearer <API_KEY>Content-Type: application/json

Request Example (cURL)

curl -X POST https://api.zemen.com.et/v1/ai/amharic/tokenize \
  -H "Authorization: Bearer zm_live_98127391823" \
  -d '{ "text": "ዘመን ቴክኖሎጂስ የኢትዮጵያ መሪ የሶፍትዌር ድርጅት ነው።" }'

Response Example (JSON 200 OK)

{
  "tokens": ["ዘመን", "ቴክኖሎጂስ", "የኢትዮጵያ", "መሪ", "የሶፍትዌር", "ድርጅት", "ነው"],
  "language": "am",
  "script": "Ethiopic",
  "word_count": 7
}