Airtime Topup

Endpoint

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

Payloads

NAME	Type	Description	Required
amount	number	Amount the voucher will hold	Yes
msisdn	string	The user who will receive the airtime	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 product	Yes

Sample Request

Curl

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

Typescript

import * as axios from "axios";

const data = {
  amount: 100,
  msisdn: "251911234567",
  exchangeRate: 56.5,
  currency: "USD",
  originatingCountry: "USA"
};

axios
  .post("BASE_URL/topup-transactions/airtime-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,
    referenceNumber: 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.

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	400	false	-

Sample Response

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

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: {
    message: string, 
    referenceNumber: string, 
  }
}