Send Gifts

Gift vouchers are prepaid cards that hold a specific monetary value. They can be used as payment for goods or services at merchants that work with Telesend / OmniVAS.

Integration overview

Sending gifts with the Partner API has two parts:

1. Issue the voucher using your partner credentials (this guide).
2. Redeem the voucher at a merchant — handled by the merchant integration, not the Partner API.

Step	Who	What you call
List denominations	Partner	GET /gift-denominations
List merchants	Partner	GET /merchants
Generate voucher	Partner	POST /topup-transactions/generate-voucher
Redeem voucher	Merchant	Merchant Redemption APIs — see Merchant voucher redemption

Breaking changes

• Configuring per-merchant selling prices via partner-gift-denomination-prices is no longer supported (POST / PUT / DELETE return 410 Gone). Pass foreignCurrencyAmount and exchangeRate on each generate request.
• Partner and legacy IAT redeem / claim endpoints return 410 Gone. Merchants must use the Merchant Redemption APIs linked above.
• The recipient receives the voucher SMS from the issuance platform. Your integration should not expect a separate Telesend SMS for the voucher code after generate.
• senderName is now required on POST /topup-transactions/generate-voucher. Requests that omit it are rejected with 400 before your gift balance is touched.

---

1. List gift denominations

Denominations define the face value (ETB) of vouchers you can issue. The list returns only active, gift-enabled denominations. Use the denomination id as denominationId when generating.

Endpoint

> GET ${BASE_URL}/gift-denominations

Response schema

{
  success: boolean;
  message: string;
  statusCode: number;
  data: Array<{
    id: number;
    amountEtb: number;
    isActive: boolean;
  }>;
  meta?: {
    itemsPerPage: number;
    totalItems: number;
    currentPage: number;
    totalPages: number;
  };
}

---

2. List merchants

Use a merchant from the Merchants List when generating a voucher. Only gift-enabled merchants are returned for gift issuance.

Endpoint

> GET ${BASE_URL}/merchants

You may also load denominations available for a merchant:

> GET ${BASE_URL}/merchants/:id/denominations

---

3. Generate vouchers

Endpoint

> POST ${BASE_URL}/topup-transactions/generate-voucher

Generating a voucher:

• Debits your gift balance for the denomination face value
• Issues a voucher code to the recipient phone number
• Returns voucher details in the API response

Request body

Name	Type	Description	Required	Default
denominationId	number	Gift denomination id from the denominations list	Yes	—
merchantId	number	Merchant id from the merchants list	Yes	—
msisdn	string	Recipient phone number (Ethio Telecom MSISDN)	Yes	—
exchangeRate	string	Exchange rate used for this sale (e.g. USD → ETB)	Yes	—
currency	string	Original sale currency (e.g. USD)	Yes	—
originatingCountry	string	Country where the sale originated	Yes	—
foreignCurrencyAmount	string	Sale price in the original currency	Yes	—
senderName	string	Name of the person sending the gift, shown to the recipient and used for reconciliation. Max 255 characters	Yes	—
isRestricted	boolean	If true, redemption is limited to the issuing merchant	No	true

Sample request

Curl

$ curl -H 'Content-Type: application/json' \
       -H 'x-api-token: ACCESS_TOKEN' \
       -d '{
             "denominationId": 7,
             "merchantId": 1,
             "msisdn": "251911234567",
             "exchangeRate": "56.5",
             "currency": "USD",
             "originatingCountry": "US",
             "foreignCurrencyAmount": "8.85",
             "senderName": "Kebede Alemu",
             "isRestricted": true
           }' \
       "${BASE_URL}/topup-transactions/generate-voucher"

Typescript

import * as axios from "axios";

const data = {
  denominationId: 7,
  merchantId: 1,
  msisdn: "251911234567",
  exchangeRate: "56.5",
  currency: "USD",
  originatingCountry: "US",
  foreignCurrencyAmount: "8.85",
  senderName: "Kebede Alemu",
  isRestricted: true,
};

axios
  .post(`${BASE_URL}/topup-transactions/generate-voucher`, 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: {
    voucher: {
      id: string;
      voucherCode: string;
      amount: string;
      expirationDate?: string;
      serialNumber?: string;
    }
  }
}

Error Schema

{
  statusCode: number;
  success: boolean;
  message: string;
  data: any;
}

Common errors

Message	Status Code	Success	Note
merchantId is required / Either merchantId or merchantIdentifier should be Specified	400	false	Provide a valid merchant
No merchant found / merchant not available for gifts	404	false	Use a merchant from GET /merchants
Gift denomination not found / inactive	404	false	Use an active denomination
You do not have adequate amount of money	405	false	Top up gift balance
Recipient phone must be an Ethio Telecom MSISDN	400	false	Invalid recipient number

---

4. Selling prices (deprecated)

Previously you could store USD selling prices per denomination and merchant:

POST /client/partner-gift-denomination-prices

That configuration is deprecated:

Method	Path	Status
POST / PUT / DELETE	/partner-gift-denomination-prices	410 Gone
GET	/partner-gift-denomination-prices	Still available (read-only / historical)

Pass foreignCurrencyAmount and exchangeRate on every generate request instead.

---

5. Redemption (merchants)

Partners do not call redeem endpoints on the Partner API.

After you generate a voucher:

1. The recipient receives an SMS with the voucher code.
2. The recipient presents the code at a participating merchant.
3. The merchant validates and redeems the voucher using the Merchant Redemption APIs.

Merchant integration guide:

• Voucher redemption
• OTP / claim verification

The following Partner / legacy claim-redeem endpoints are retired and return 410 Gone:

• POST /topup-transactions/initiate-claim
• POST /topup-transactions/redeem-gift

---

Related

• Merchants List
• Callbacks
• Gift voucher flow overview