Merchant API — Voucher Redemption

This guide is for merchants redeeming OmniVAS / Telesend gift vouchers at point of sale or via your own systems.

Current redemption platform

Voucher redemption is performed through the Merchant Redemption APIs.

Resource	Link
Redemption overview & validate / claim	Voucher redemption
OTP / claim verification	OTP verification
Merchant API access & signing	Merchant API access

Use those guides for authentication headers (X-API-Key, X-Timestamp, X-Signature, Idempotency-Key), request bodies, and response codes.

Redemption flow

1. Validate

Confirm the voucher exists and inspect remaining balance before charging the customer.

POST /merchant-api/vouchers/validate

{
  "voucherCode": "9876543210987654"
}

Example success payload (see official docs for the full schema):

{
  "id": 123,
  "code": "9876543210987654",
  "ownerNumber": "+251911234567",
  "originalAmount": "500.00",
  "remainingBalance": "350.00",
  "totalRedeemed": "150.00",
  "status": "PARTIALLY_REDEEMED",
  "isRestricted": true,
  "originatingMerchantId": 12,
  "originatingMerchantName": "Abyssinia Market",
  "expirationDate": "2026-07-27T23:59:59.000Z"
}

2. Create claim

Start redemption for an amount up to remainingBalance. An OTP is sent to the voucher owner.

POST /merchant-api/claims

{
  "voucherId": 123,
  "amount": "50.00"
}

Example response:

{
  "claimId": 7721,
  "otpExpiresAt": "2026-04-27T08:05:00.000Z",
  "maskedPhone": "+2519*****67"
}

3. Verify claim (OTP)

Complete the redemption with the OTP provided by the customer.

POST /merchant-api/claims/:id/verify

See OTP verification for the exact body and success/failure responses.

Portal redemption

If you redeem through the merchant portal rather than a custom API integration, use the portal workflows provided by OmniVAS. API merchants should follow the links above.

Legacy Telesend merchant endpoints (retired)

The previous Telesend merchant claim/redeem endpoints are no longer available for live redemption:

Method	Path	Status
POST	/api/v1/merchant/client/topup-transactions/initiate-claim	410 Gone
POST	/api/v1/merchant/client/topup-transactions/initiate-redeem	410 Gone
POST	/api/v1/merchant/client/topup-transactions/redeem-gift	410 Gone

Migrate integrations to the Merchant Redemption APIs documented at docs.odm.et.

Voucher lookup on legacy paths, if still exposed in your environment, is for historical/issuance reference only and must not be used as the live redemption flow.