Send Gifts

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

Sending Gifts requires three steps

Generating Voucher
Redeeming Voucher
Partially Redeeming Voucher
Transfer Gifts to Another Person

1. Generate Vouchers

Endpoint

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

First step to use a voucher is to generate it so it would be redeemable by users.
To generate a voucher a "denominated gift amount" and a merchant id is needed. Denominated gifts are a centeralized gift amounts that are defined by our system and can be configured from your side for each merchant. You can find the available merchants and their identifiers using the merchants endpoint.

Denominated Gifts

Denominated Gifts hold the amount information a single voucher can hold after it is generated and they are defined centerally by Telesend.
Each Denominated Gift holds information about its given amount and its status.
The selling price for each of the denominated gifts can be negotiated between you and your merchants. You can see below to see how you can define these selling prices.
Gift denomination id is required to be provided in your body request. and you can get the list of denominated gifts using.

Endpoint

> GET /client/gift-denominations

Response Schema

{
success: boolean;
message: string;
statusCode: number;
data: [
  {
    id: number,
    status: 'ACTIVE' | 'INACTIVE', 
    amountEtb: number, 
   }
 ]
}

Defining Selling Price for Denominated Gifts

You can define selling prices (USD) for each denominated Gift Amount (ETB) for each merchant. This information will be saved and centeralized in Telesend.

POST /client/partner-gift-denomination-prices

{
    'denominationId': 'the denomination of the gift (gift-denomiations see above #1)', 
    'sellingPriceUsd': '124',
}

The body for generating voucher can vary based on your usecase of the voucher. The available ways are listed below.

1.1. Vouchers

In these kind of Vouchers, the end owner of the voucher is known at the time of Generation and can't be used by any phone number other than the voucher sent to. These types of vouchers need to be verified by user before they are utilized. /check initiateing redeem/

NAME	Type	Description	Required	Default Value
denominationId	number	ID of the denominated Gift.	Yes	-
merchantId	number	Id of Merchant	Yes
msisdn	string	The phone number of the user who will claim the voucher/gift.	Yes	-
exchangeRate	string	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 gift in USD	Yes	-

1.2. Vouchers that can be redeemed by a different merchant.

Although specifying a merchant is necessary when generating vouchers, there are some scenarios where we would want the redeemed merchant to be different than the initial specified merchant. This feature has to be enabled on time of generating (It is disabled by default).

Payloads

Note: add this payload to the above request body

NAME	Type	Description	Required	Default Value
isRestricted	boolean	Indicates whether the voucher can be transferred to another merchant.	No	true

Sample Request

CurlTypescript

$  curl -H 'Content-Type: application/json' \
        -H 'x-api-token: ACCESS_TOKEN' \
        -d '{
              "denominationId": 7,
              "merchantId": 1,
              "msisdn": "251911234567",
            }' \
        "BASE_URL/generate-voucher"

Typescript

import * as axios from "axios";

const data = {
  denominationId: 7,
  merchantId: 1,
  msisdn: "251911234567",
};

axios
  .post("BASE_URL/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;
    }
  }
}

Error Schema

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

Error Types

Message	Status Code	Success	_Addtional Note_
Either merchantId or merchantIdentifier should be Specified	400	false	-
No Price defined for the product	404	false	-
You have no access to this product. please contact Admins.	404	false	-
You do not have adequate amount of money	405	false	-

2. Initiate Redeem /Optional/

This part is necessary if the voucher is not annoynomous. If you dont know what annoynomous vouchers are please refer to #1.1 above.

If a voucher is not annoynomous, we need to verify if the owner is the one who initiated the redeem. At the time of executing this endpoint a verification code is going to be sent to the user which he can use to initiate the redeem (see #3.)

Endpoint

> POST ${BASE_URL}/topup-transactions/initiate-claim

Payloads

NAME	Type	Required	Description
voucherCode	string	Yes	Voucher Code that is going to be claimed (found from #1)
amount	number	No (voucher amount will be used if not specified)	The amount of money to start redeeming

Sample Request

CurlTypescript

$  curl -H 'Content-Type: application/json' \
        -H 'x-api-token: ACCESS_TOKEN' \
        -d '{
              "voucherCode": "VOUCHER123",
              "amount": 500
            }' \
        "BASE_URL/topup-transactions/initiate-claim"

Typescript

import * as axios from "axios";

const data = {
  voucherCode: "VOUCHER123",
  amount: 500
};

axios
  .post("BASE_URL/topup-transactions/initiate-claim", 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 code has been sent to user Successfully";
}

Error Schema

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

Error Types

Message	Status Code	Success	_Addtional Note_
Voucher is already Redeemed	404	false	-
No voucher with specified code	404	false	-
Specified amount is more than the remaining voucher amount	403	false	-

3. Redeem Vouchers

This is the last step in sending gifts that need to be handled by end user apps. At the time of execution if it is Successful, the specified amount would be transferred to merchants.

> POST ${BASE_URL}/topup-transactions/redeem-gift

Payloads

NAME	Type	Required	Description
voucherCode	number	Yes	Voucher Code that is going to be claimed
verificationCode	string	No	Verification Code end user got via SMS when initiate-redeem was executed
msisdn	string	The phone number of the user who will claim the voucher/gift.	Not required. It will be taken from the original voucher owner specified when generating.

At the time of redeem the vouchers balance is transferred to the merchant while a service fee will be deducted from the voucher's remaining balance according to the merchant's service fee percent.

3.1. Redeeming in a different merchant

In addition to the above payloads (based on ur preferred scenario) you also need to pass merchantId if the money merchant is not the one specified at the time of generation (see #1.3)

Payloads

NAME	Type	Description
merchantId	number	Merchant Id where the money will be transferred if the request was successful

Sample Request

CurlTypescript

$  curl -H 'Content-Type: application/json' \
        -H 'x-api-token: ACCESS_TOKEN' \
        -d '{
              "voucherCode": "VOUCHER123",
              "verificationCode": "CODE123"
            }' 
        "BASE_URL/topup-transactions/redeem-gift"

Typescript

import * as axios from "axios";

const data = {
  voucherCode: "VOUCHER123",
  verificationCode: "CODE123",
};

axios
  .post("BASE_URL/topup-transactions/redeem-gift", 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: {
    response: string; // success response message
    referenceNumber: string; // telebirr reference number
  }
}

Error Schema

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

Error Types

Message	Status Code	Success	_Addtional Note_
Voucher is already Redeemed	404	false	-
No voucher with specified code	404	false	-
Specified amount is more than the remaining voucher amount	403	false	-
Verification Code is missing	403	false	If the voucher is not annoynomous
No Voucher redeem process started for by owner	403	false	If the voucher is not annoynomous
The provided verification code is not correct.	403	false	If the voucher is not annoynomous
Expiration date has already passed.	403	false	If the voucher is not annoynomous
The given voucher is restricted. You cant change merchant using this voucher card	403	false	If the voucher is not transferrable to another merchant and you are trying to to claim it in a different merchant
No merchant with given id	404	false	If merchantId was specified but it doesnt exist
Telebirr Error: "some error message from telebirr why the claim failed"	404	false

Send Gifts ​

1. Generate Vouchers ​

Denominated Gifts ​

Response Schema ​

Defining Selling Price for Denominated Gifts ​

1.1. Vouchers ​

1.2. Vouchers that can be redeemed by a different merchant. ​

Sample Request ​

Response Schema ​

2. Initiate Redeem /Optional/ ​

Sample Request ​

Response Schema ​

3. Redeem Vouchers ​

3.1. Redeeming in a different merchant ​

Sample Request ​

Response Schema ​

Send Gifts

1. Generate Vouchers

Denominated Gifts

Response Schema

Defining Selling Price for Denominated Gifts

1.1. Vouchers

1.2. Vouchers that can be redeemed by a different merchant.

Sample Request

Response Schema

2. Initiate Redeem /Optional/

Sample Request

Response Schema

3. Redeem Vouchers

3.1. Redeeming in a different merchant

Sample Request

Response Schema