OmniVAS - Digital Voucher Card Merchant API

Integration Guide & Technical Reference

---

Document Revision History

Version	Date	Author	Description
1.0	2025-12-19	Omniva Team	Initial release

---

Table of Contents

1. Introduction
2. Getting Started
3. Authentication
4. Gift Voucher Redemption
5. Security Best Practices

---

Introduction

This document provides comprehensive technical specifications for integrating with OmniVAS Gift Voucher Redemption API. It covers design principles, object definitions, operational behaviors, and error handling procedures.

Intended Audience: Technical teams responsible for implementing merchant integrations with the OmniVAS platform.

---

Getting Started

Prerequisites

Step	Action	Details
1	Account Signup	Complete registration via the account activation email from the OmniVAS Business Team. Activation must occur within 24 hours.
2	Portal Login	Access the merchant portal at tmerchants.telesend.et
3	API Configuration	Navigate to /manage-apis to enable API access, configure IP whitelisting, and generate API credentials.

IMPORTANT

• Ensure API Integration is enabled before proceeding.
• Store API credentials securely using industry-standard practices.
• Whitelist valid IP addresses (format: xxx.xxx.xxx.xxx) or Fully Qualified Domain Names (FQDN).

Base URLs

Environment	Base URL
Production	https://api.telesend.et/api/v1/merchant/client
Test	https://tapi.telesend.et/api/v1/merchant/client

---

Authentication

Authentication Flow

Step 1: Obtain API Key

Retrieve your API key from the Manage API Page.

Step 2: Configure IP Whitelist

Register your server IP address(es) in the portal's Manage APIs section.

Step 3: Generate and Register Public Key

To ensure secure and tamper-proof communications, all request bodies must be digitally signed.

Key Generation Requirements:

1. Generate a private/public key pair.
2. Use the private key to sign your request payloads.
3. Register the public key in the portal's Manage APIs section (Public Key field).
4. The registered public key will be used to verify incoming requests.

Example: Generating Keys with OpenSSL

# Install OpenSSL if not already installed
sudo apt-get install openssl

# Generate private key
openssl ecparam -name secp256k1 -genkey -noout -out ec-secp256k1-priv-key.pem

# Generate public key from private key
openssl ec -in ec-secp256k1-priv-key.pem -pubout > ec-secp256k1-pub-key.pem

After executing the above commands, you will have two .pem files in your current directory:

• ec-secp256k1-priv-key.pem — Keep this private key secure and use it when signing requests to the server.
• ec-secp256k1-pub-key.pem — Copy and register this public key in the portal's Manage APIs section.

Signature Format:

1. Sign your request payload using your private key.
2. Include a unique message with the signed payload (e.g., current timestamp or request-specific identifier).
3. Set the x-signature header value as: {signed_payload}\n{timestamp}

Step 4: Obtain Access Token

Request:

curl -X POST "BASE_URL/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"key": "YOUR_API_KEY"}'

Response:

{
  "accessToken": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "success": true,
  "statusCode": 200,
  "message": "Login Successful"
}

NOTE

• Access tokens are valid for 300 seconds (5 minutes).
• Token requests must originate from a secure back-channel only.

Step 5: Verify Configuration

Request:

curl -X POST "https://tapi.telesend.et/api/v1/merchant/client/test" \
  -H "x-api-token: ACCESS_TOKEN"

Expected Response:

{
  "test": "successful"
}

---

Gift Voucher Redemption

Gift vouchers are prepaid digital cards with a specified monetary value, redeemable at OmniVAS-integrated merchants.

Redemption Flow Overview

---

1. Initiate Claim

Initiates the voucher redemption process and dispatches a verification code to the voucher owner via SMS.

Endpoint: POST /topup-transactions/initiate-claim

Request Headers

Field	Type	Required	Description
x-api-token	string	Yes	Access token obtained from login
x-signature	string	Yes	Digitally signed payload using your private key

Request Body

Field	Type	Required	Description
voucherCode	string	Yes	Voucher code to claim
amount	number	No	Amount to redeem (defaults to full voucher balance if not specified)
idempotencyKey	string	Yes	Unique key ensuring request idempotency and preventing duplicate processing
metadata	string	No	Optional JSON string containing additional contextual data (eg. merchant name, product name, product price etc)

Example Request

curl -X POST "BASE_URL/topup-transactions/initiate-claim" \
  -H "Content-Type: application/json" \
  -H "x-api-token: ACCESS_TOKEN" \
  -H "x-signature: SIGNED_PAYLOAD" \
  -d '{
    "voucherCode": "3225118500682251",
    "amount": 500,
    "idempotencyKey": "unique-key-123",
    "metadata": "{}"
  }'

Success Response

{
  "success": true,
  "message": "OTP Code has been sent to user Successfully",
  "statusCode": 200,
  "data": {
    "message": "OTP Code has been sent to user Successfully",
    "idempotencyKey": "unique-key-123",
    "metadata": "{}"
  }
}

Response Body Explanations

Field	Type	Description
message	String	Confirmation message that OTP was sent
idempotencyKey	String	The idempotency key from your request (allows you to verify response matches your submission)
metadata	String	The metadata from your request (allows you to verify response matches your submission)

Error Response Format

{
    "statusCode": 4001,
    "success": false,
    "message": "Error description",
    "data": null
}

Error Codes

Status Code	Error Message
4041	No voucher found with specified code
4042	Voucher is already redeemed
4091	Amount exceeds voucher balance
5001	Error fetching merchant service fee
5002	Failed to update voucher status
5004	Database transaction failed

---

2. Get Voucher Detail Information

This gives you detail information based on the voucher code. This can be used to get full information about a voucher such as its remaining balance, expiration date and its current status.

Endpoint: GET /topup-transactions/:voucherCode

Request Headers

Field	Type	Required	Description
x-api-token	string	Yes	Access token obtained from login

Success Response

{
    "statusCode": 200,
    "success": true,
    "message": "Successful",
    "data": {
        "voucher": {
            "id": 118,
            "code": "2585771156933526",
            "serialNumber": "1000000000046",
            "amount": "50.000000",
            "remainingBalance": "0.005000",
            "status": "REDEEM_INITIATED",
            "expirationDate": "2025-12-21T22:10:17.000Z"
        },
        "serviceFee": "1.000000"
    }
}

Response Body Explanations

Field	Type	Description
voucher	Object	Detailed Voucher data showing information about particular voucher
serviceFee	String	Service Fee attached to the voucher

The voucher object in the response holds these informations about a voucher.

Field	Type	Description
id	Number	Unique identifier for the voucher in the system
code	String	Unique voucher code
serialNumber	String	Serial number assigned to the voucher
amount	String	Original voucher amount
remainingBalance	String	Available balance remaining on the voucher
status	String	Current voucher status (e.g., ACTIVE, REDEEM_INITIATED, REDEEMED)
expirationDate	String	Date and time when the voucher expires (ISO 8601 format)

---

3. Redeem Gift

Completes the redemption process and transfers funds to the merchant account.

Endpoint: POST /topup-transactions/redeem-gift

Request Headers

Field	Type	Required	Description
x-api-token	string	Yes	Access token obtained from login
x-signature	string	Yes	Digitally signed payload using your private key

Request Body

Field	Type	Required	Description
voucherCode	string	Yes	Voucher code to redeem
verificationCode	string	Yes	SMS verification code received by voucher owner
msisdn	string	No	Phone number of client (defaults to voucher owner if not specified)
idempotencyKey	string	Yes	Unique key ensuring request idempotency and preventing duplicate processing
metadata	string	No	Optional JSON string containing additional contextual data

Example Request

curl -X POST "BASE_URL/topup-transactions/redeem-gift" \
  -H "Content-Type: application/json" \
  -H "x-api-token: ACCESS_TOKEN" \
  -H "x-signature: SIGNED_PAYLOAD" \
  -d '{
    "voucherCode": "3225118500682251",
    "verificationCode": "735191",
    "idempotencyKey": "unique-key-123",
    "metadata": "{}"
  }'

Success Response

{
  "success": true,
  "message": "Gift redeemed successfully",
  "statusCode": 200,
  "data": {
    "response": "Success",
    "referenceNumber": "TBR123456789",
    "omnivasReferenceNumber": "TX-1234567",
    "idempotencyKey": "unique-key-123",
    "metadata": "{}"
  }
}

Response Body Explanations

Field	Type	Description
response	String	Status message indicating redemption success
referenceNumber	String	Reference number from telebirr confirming fund transfer to merchant
omnivasReferenceNumber	String	OmniVAS unique reference for tracking and support inquiries
idempotencyKey	String	The idempotency key from your request (allows you to verify response matches your submission)
metadata	String	The metadata from your request (allows you to verify response matches your submission)

Error Response Format

{
    "statusCode": 4031,
    "success": false,
    "message": "Error description",
    "data": null
}

Error Codes

Status Code	Error Message
4031	The given voucher is restricted. Merchant cannot be changed for this voucher
4032	Voucher is already redeemed
4033	Verification code is missing
4034	No voucher redemption process initiated
4035	The provided verification code is incorrect
4036	Voucher expiration date has passed
4041	No voucher found with specified code
4043	No merchant found with the given ID
4044	Voucher balance is insufficient for transaction
4045	Specified partner company is not available
4091	Amount exceeds voucher balance
4092	Transaction mismatch error. Please retry
4093	Reserved balance update failed. Please contact support
4094	Redemption record creation failed
4095	Reserved balance debit from company failed
4096	Remaining balance cannot be negative after service fee deduction
5002	Failed to update voucher status
5003	Failed to queue SMS notification
5004	Database transaction failed
5031	Transfer failed: [Provider error message]

---

Security Best Practices

This section outlines critical security measures for merchants integrating with the Gift Voucher API.

Security Architecture Overview

Credential Management

Practice	Priority	Description
Environment Isolation	Critical	Use separate API keys for test and production environments
Key Rotation	High	Rotate API keys every 90 days or immediately upon suspected compromise
Access Control	High	Restrict API key access to authorized personnel only

WARNING

• Never hardcode API keys in source code.
• Never commit credentials to version control systems.
• Never expose API keys in client-side applications or logs.

---

Support

For technical support or integration assistance, please contact the OmniVAS Business Team.

---

© 2025 OmniVAS. All rights reserved.