Gift Voucher Integration Flow

Partner-facing overview of issuing gift vouchers through the Telesend / OmniVAS Partner API and how redemption works for end customers.

Who does what

Actor	Responsibility
Partner	List denominations and merchants, generate vouchers, manage gift balance
Recipient	Receives SMS with voucher code; presents code at a merchant
Merchant	Validates and redeems the voucher via Merchant Redemption APIs

Partners do not implement redeem or OTP claim flows on the Partner API.

End-to-end sequence

Partner steps

1. Discover catalog

1. GET /gift-denominations — active gift denomination face values in ETB
2. GET /merchants — gift-enabled merchants

Details: Send Gifts, Merchants List

2. Generate a voucher

Call:

POST /topup-transactions/generate-voucher

Required fields include denominationId, merchantId, msisdn, senderName, and sale FX fields (foreignCurrencyAmount, exchangeRate, currency, originatingCountry).

On success:

• Your gift balance is debited for the denomination face value
• The response includes the voucher code and amount
• The recipient is notified by SMS with the voucher code

Full request/response examples: Send Gifts — Generate vouchers

3. Optional: listen for issuance-related webhooks

If you use webhooks, see Callbacks for events your account is configured to receive.

Merchant redemption (not Partner API)

After issuance, redemption is performed by the merchant:

1. Validate voucher code
2. Create a claim for the amount to redeem
3. Verify OTP sent to the voucher owner

Official merchant guides:

• Voucher redemption
• OTP verification

Deprecated Partner / legacy endpoints

Do not use these for new integrations. They return 410 Gone:

Endpoint	Notes
POST /partner-gift-denomination-prices	Selling-price setup removed; pass FX fields on generate
PUT / DELETE partner gift denomination prices	Same
POST /topup-transactions/initiate-claim	Merchant redemption only
POST /topup-transactions/redeem-gift	Merchant redemption only

GET on partner gift denomination prices remains available for historical read-only access.