Ethio Telecom Bundles

Bundles are packages provided by Ethio Telecom to customers. These include different types of packages such as: Voice, Data, and more. Packages are one part of our products list and they can be found using the products-list endpoint.

Getting List of Bundles

> GET ${BASE_URL}/product-list?q=productCategory.categoryName=PACKAGES

Buy Packages.

Once a bundle is selected from the product list you can use the following endpoint to buy the bundle.

> POST ${BASE_URL}/topup-transactions/airtime-package-topup

Payloads

NAME	Type	Description	Required
productId	number	product id from the list of products	Yes
msisdn	string	The user who will receive the package	Yes
exchangeRate	number	USD -> ETB Exchange Rate used for this sale	Yes
currency	string	The original currency used to buy the airtime	Yes
originatingCountry	string	From where country is this request coming	Yes
foreignCurrencyAmount	string	Amount in USD representing the sale price of the package	Yes

Sample Request

Curl

$  curl -H 'Content-Type: application/json' \
        -H 'x-api-token: ACCESS_TOKEN' \
        -d '{
              "productId": 123,
              "msisdn": "251911234567",
              "exchangeRate": 56.5,
              "currency": "USD",
              "originatingCountry": "ET"
            }' \
        "BASE_URL/topup-transactions/airtime-package-topup"

Typescript

import * as axios from "axios";

const data = {
  productId: 123,
  msisdn: "251911234567",
  exchangeRate: 56.5,
  currency: "USD",
  originatingCountry: "ET"
};

axios
  .post("BASE_URL/topup-transactions/airtime-package-topup", data, {
    headers: {
      "Content-Type": "application/json",
      "x-api-token": "ACCESS_TOKEN"
    },
  })
  .then((response) => {
    console.log("Success:", response.data);
  })
  .catch((error) => {
    console.error(
      "Error:",
      error.response ? error.response.data : error.message,
    );
  });

Response Schema

Success Schema

{
  success: boolean;
  message: string;
  statusCode: number;
  data: {
    message: string,
    referenceNo: string,
  }
}

Error Schema

{
  statusCode: number;
  success: boolean;
  message: string;
  data: any & {
      transactionId: number, 
      status: 'SUCCESS' | 'FAILED', 
      referenceNumber: null | string, 
  };
}

If you get a failure when trying to topup and your request is retriable you will get a transactionId in the error data. you can use this transactionId to retry failing request again.

Sample Response

{
  "success": true,
  "message": "Successful",
  "statusCode": 200,
  "data": {
    "message": "Your request is being processed"
    "referenceNo": "123456789"
  }
}

Error Types

Message	Status Code	Success	_Additional Note_
You do not have access to this product. please check with Admins.	404	false	-
You do not have adequate amount of money	405	false	-

Topup Request Retries

Upon a failure of a topup request the error response you will see will have an information about your unsuccessful attempt. The error response will hold information that looks like

{
    "message": "Message explaining why it failed", 
    "status": "FAILED", 
    "transactionId": 1, // Take a note of this field 
}

From this response, you can use the transactionId to retry your request. The necessary information about the retry endpoint has been written below

Endpoint

> POST ${BASE_URL}/topup-transactions/retry-topup

Payloads

NAME	Type	Description	Required
transactionId	number	Transaction Id from the above error response	Yes
msisdn (optional)	string	If you want the transaction happen to another number	Yes

Response Schema

Success Schema

{
  success: boolean;
  message: string;
  statusCode: number;
  data: {
    transactionId: number, 
    message: string, 
    referenceNumber: string, 
    status: 'SUCCESS' | 'FAILED'
  }
}