Catalog Browsing

Use catalog endpoints to fetch active product and merchant metadata before submitting purchase or issuance requests.

Endpoints

Method	Path	Description
GET	/data-packages	Active data package offers.
GET	/gift-denominations	Active voucher denominations.
GET	/merchants	Eligible merchants.
GET	/promos	Active and scheduled promos.

Headers

Header	Required	Description
X-API-Key	Yes	Partner API key.
X-Timestamp	Yes	ISO timestamp used in signature verification.
X-Signature	Yes	Base64 Ed25519 signature for the request.
User-Agent	No	Optional client identifier.
Idempotency-Key	No	Optional tracing key for read requests.

Request Example

curl -X GET "$API_BASE_URL/data-packages" \
  -H "X-API-Key: $PARTNER_API_KEY" \
  -H "X-Timestamp: 2026-04-29T12:00:00.000Z" \
  -H "X-Signature: $PARTNER_SIGNATURE" \
  -H "Idempotency-Key: cat_01HXYZ0123ABC456DEF789GHJK"

Example Responses

Data Packages

[
  {
    "id": 101,
    "productCategoryId": 7,
    "offerId": "DP-ETHIO-1GB-7D",
    "packageName": "1GB Weekly Data",
    "description": "1GB data package valid for 7 days",
    "priceEtb": 100,
    "validityDays": 7,
    "status": "ACTIVE",
    "createdAt": "2026-04-27T08:00:00.000Z",
    "updatedAt": "2026-04-27T08:00:00.000Z",
    "deletedAt": null
  }
]

Gift Denominations

[
  {
    "id": 4,
    "amountEtb": 500,
    "isActive": true,
    "createdAt": "2026-04-27T08:00:00.000Z",
    "updatedAt": "2026-04-27T08:00:00.000Z",
    "deletedAt": null
  }
]

Merchants

[
  {
    "id": 12,
    "merchantName": "Abyssinia Market",
    "merchantLogo": "https://cdn.example.com/merchants/abyssinia-market.png",
    "category": {
      "id": 3,
      "categoryName": "Retail"
    },
    "status": "ACTIVE",
    "redemptionMethod": "OTP"
  }
]

Promos

[
  {
    "id": 18,
    "promoName": "Weekly Data Bonus",
    "promoDescription": "Bonus value for selected weekly data packages.",
    "promoStartDate": "2026-04-27T00:00:00.000Z",
    "promoEndDate": "2026-05-04T23:59:59.000Z",
    "discountPercentage": null,
    "bonusPercentage": 10,
    "status": "ACTIVE",
    "productCategoryId": 7,
    "productCategoryName": "Data Packages",
    "constraintValue": 100,
    "promoImage": "https://cdn.example.com/promos/weekly-data-bonus.png",
    "displayStatus": "ACTIVE",
    "createdAt": "2026-04-27T08:00:00.000Z",
    "updatedAt": "2026-04-27T08:00:00.000Z",
    "deletedAt": null
  }
]

Response Codes

Code	Meaning
200	Catalog returned.
400	Invalid request headers.
401	Missing or invalid API key, timestamp, or signature.
403	Access is forbidden.
500	Unexpected processing error.

Integration Notes

• Treat this data as operational reference and cache it in your integration service.
• Re-fetch catalog data regularly to pick up new offers, status changes, and promo schedules.
• Keep using signed requests for all reads; signature rules are the same as write endpoints.