Please Wait..

List of Basic and Important Steps

To purchase products from our API, certain fields are required. While similar fields are used for all purchases, their values will vary. Please note that some fields are mandatory for certain products but may be optional for others.

This page provides a collection of commonly used endpoints. However, this does not limit your development to only the listed endpoints. For more information on each endpoint, please refer to its documentation for usage details and required parameters.

Some Important Fields
Please note that all these fields are available when you list the product catalogue

 

Attribute	Description
productId	The ID of the product
providerId	The ID of the provider.
value	The value after the product (After conversion if applicable). This is the targetValue field from the product listing
walletId	The Wallet ID of the currency you want to use for the purchase
productCode	The productCode is required for some product such as utilities e.g Electricity, cable TV etc. This is compulsory for Utilities
uniqueAccountId	This is the Unique Account ID required for Airtime, Data and Utilities. This is compulsory for these product categories. E.g Phone number(In international format) for Airtime and Data, SmartCardno for cable TV or Meter No for electricity. This must be supplied.

 

1. Get List of All Possible Product Categories

  GET: {baseUrl}/api/v1/Product/Categories 

Please note the categoryCode from this endpoint.

 

2. Get List of All Possible Subcategories for a Category

 GET:  {baseUrl}/api/v1/Product/Category/{categoryCode} 

Please note the subCategoryCode from this endpoint.

 

3. Get Wallet ID

 GET:  {baseUrl}/api/v1/Report/AccountBalance

Note the walletId from this endpoint.
walletId: This is wallet id for the currency you will be using to pay for the product

 

4. List of Products by Category

  GET: {baseUrl}/api/v1/Product/Category/{categoryCode} 

Please note the basic fields from this endpoint. Use a categoryCode for {categoryCode}, e.g GiftCard

 

5. List of Products by Category Filtered by Usage Country

  GET: {baseurl}/api/v1/Product/Category/{categoryCode}?filters={"countryCode":"{countryCode}"}

Please use the appropriate categoryCode for {categoryCode} and countrCode for {countryCode}, e.g esim and GBR
Sample Request: {baseurl}/api/v1/Product/Category/esim?filters={"countryCode":"GBR"}

 

6. List of Products by Category Filtered by Subcategory

  GET: {baseurl}/api/v1/Product/Category/{categoryCode}?filters={"subCategoryCode":"{subCategoryCode}"} 

Please use the appropriate categoryCode for {categoryCode} and Sub Category Code for {subCategoryCode}, e.g giftcard and Food-Beverage
Sample Request: {baseurl}/api/v1/Product/Category/giftcard?filters={"subCategoryCode":"Food-Beverage"}

 

7. Validate a Customer Account
Some Services need to validate the customer acccount number before purchase. E.g Cable TVs and Electricity companies.

POST: {baseurl}/api/v1/validations

Please read the endpoint documentation for more details.

 

8. Make a Purchase

POST: {baseurl}/api/v1/orders

Please read the endpoint documentation for more details.

 

9. Currency Settings
Ensure that you set the X-Wallet-Id in the request header and that it matches the walletId attribute in the body of your request when making a purchase. This is the wallet for the settlement currency you are using for the purchase.

This endpoint allows you to retrieve the effective foreign exchange rates available for your account. It returns the applicable rate used to convert a product currency to the transacting currency.

Endpoint

GET: api/v1/Report/FxRate
Sample Request:  To get all effective exchange rates available, use the request shown below.
{baseUrl}/api/v1/Report/FxRate

NOTE: The endpoint returns multiple currency mappings, showing each product currency and its corresponding transacting rate.

Additional Required Request Headers:
X-Wallet-Id

 

Sample Response:

  

 {
    "authenticated": true,
    "sysDate": "2025-11-02T23:23:58.165Z",
    "sysErr": 200,
    "sysId": 251102232356083368,
    "sessionUid": "S:HBVKHSABATJIPKIDWIMEKVBLM",
    "requestStatus": "PROCESSED",
    "message": "REQUEST OK",
    "response": [
        {
            "productCurrency": "HKD",
            "productValue": 1,
            "transactingCurrency": "NGN",
            "allInRate": 203.7913350000
        },
        {
            "productCurrency": "AED",
            "productValue": 1,
            "transactingCurrency": "NGN",
            "allInRate": 437.2800300000
        },
        {
            "productCurrency": "GBP",
            "productValue": 1,
            "transactingCurrency": "NGN",
            "allInRate": 2313.3000000000
        },
        {
            "productCurrency": "USD",
            "productValue": 1,
            "transactingCurrency": "NGN",
            "allInRate": 1721.5000000000
        }
    ]
}

  

 

Attribute	Description
productCurrency	The base or source currency of the product (e.g., HKD, AED, USD).
productValue	A reference value of the product in the product currency (usually 1).
transactingCurrency	The transacting or settlement currency (e.g., NGN).
allInRate	The overall effective exchange rate applied to convert productCurrency to transactingCurrency. We quote a single all-in rate, this already includes the FX rate, our charges, and your commission. There are no separate mark-ups or hidden add-ons so that the price shown is the final recommended retail selling price out

 

Below is a description of our standard response attributes and their meanings. Please note that some attributes may not have values in some purchase or order request response.

This is related to the /orders endpoint response. .

POST: /api/v1/orders

 

Attribute	Description
authenticated	Indicates if the request is authenticated (true/false).
sysDate	System date and time when the request was processed.
sysErr	System error code (200 indicates success).
sysId	Unique system identifier for the request.
sessionUid	Unique identifier for the session.
requestStatus	Indicates the status of the request (e.g., PROCESSED).
message	General message indicating the status of the request.
responseStatus	Status of the response (e.g., SUCCESS or FAILED or PENDING).
responseMessage	Detailed message about the response (e.g., Product purchased successfully).
customerReference	Reference identifier supplierd with the request.
transactionReference	Unique identifier for the transaction.
voucherCode	Code that represents the purchased product.
redemptionUrl	URL where the voucher can be redeemed (When applicable).
qrCodeData	QR code data for order that can redeem the product (e.g in eSim Purchase).
deliveryField	Indicates which field (qrCodeData, voucherCode, or redemptionUrl) contains the redemption details.
redemptionInfo	This field will provide relevant information on how to redeem the product where applicable.
productId	Unique identifier for the product.
productCode	Code assigned to the product.
providerId	Unique identifier for the provider.
providerName	Name of the provider.
name	Name of the product.
description	Details about the product and possible redemption methods.
productMoreInfoUrl	URL for more information about the product.
expirationDate	Date when the voucher or product expires.
value	Value of the product.
valueCurrencyId	Unique identifier for the currency of the product value.
valueCurrencyCode	Currency code (e.g., GBP for British Pounds).
walletId	Wallet identifier associated with the transaction.
productCost	Cost of the product.
productCostCurrencyCode	Currency code for the product cost.
productCostCurrencyId	Unique identifier for the currency of the product cost.
sysComment	System-generated comment.
fxRate.rate	Exchange rate applicable to the transaction.
fxRate.currencyCode	Currency code associated with the exchange rate.

 

 

This endpoint allows you to query an order status to determine its current or final status using the transactionReference or x-nonce value.

You can retrieve order status using either a POST request with a request body or a GET request with a query parameter.

 

Option 1 – POST Request

POST: /api/v1/order/status

Sample Request Body when using transactionReference:

{ "transactionReference": "250315235931835041:S:QRKUOSODRMCYMLTXBQHGMLOQH" } 

Sample Request Body when using x-nonce:

{ "x-nonce":"110426053014142800271506"  } 

 

Option 2 – GET Request

GET: /api/v1/order/status?transactionReference={transactionReference}

Sample Request when using transactionReference:

{baseUrl}/api/v1/order/status?transactionReference=260218112821240181:S:JMVOUAEVOTUUEWNBVTSPBSNDB 

Sample Request when using x-nonce:

{baseUrl}/api/v1/order/status?x-nonce=1104260528172249158979271

 

Parameter	Description
transactionReference	Unique identifier returned when the order was created. This value is required to retrieve the current or final status of the original transaction.
x-nonce	The unique nonce value (sent in the request header as X-Nonce) of the original transaction.

 

Sample Response

{
  "authenticated": true,
  "sysDate": "2025-03-16T00:00:05.932Z",
  "sysErr": 200,
  "sysId": 250316000084034332,
  "sessionUid": "S:GDOSLUUEARGFGYYZNGFQFPDHA",
  "requestStatus": "PROCESSED",
  "message": "REQUEST OK",
  "response": {
    "responseStatus": "SUCCESS",
    "responseMessage": "Transaction completed successfully",
    "orderStatus": "SUCCESS",
    "transactionReference": "250315235931835041:S:QRKUOSODRMCYMLTXBQHGMLOQH",
    "name": "UK_Trial_Test (Code/PIN/URL)",
    "productId": 9431,
    "productCost": 110.00,
    "productCostCurrencyCode": "GBP",
    "voucherCode": "CODE-1013",
    "redemptionInfo": "This is a Sample Test Product in the Sandbox Environment. In the Production Environment based on the Product, you will receive clear instructions on how and where to use it in the API response.",
    "redemptionUrl": "https://trailexample.com",
    "qrCodeData": "",
    "deliveryField": "redemptionUrl",
    "transactionDate": "2025-03-15T00:00:00",
    "transactionTime": "23:59:37",
    "requestComment": "Transaction record retrieved"
  }
}

 

Attribute	Description
authenticated	Indicates if the request is authenticated (true/false).
sysDate	System date and time when the request was processed.
sysErr	System error code (200 indicates success).
sysId	Unique system identifier for the request.
sessionUid	Unique identifier for the session.
requestStatus	Indicates the state of the request (e.g., PROCESSED).
message	General message indicating the status of the request.
responseStatus	Status of the request (e.g., SUCCESS or FAILED or PENDING).
responseMessage	Detailed message about the response.
customerReference	Reference identifier supplied with the order request.
orderStatus	Current state or Status of the order.
transactionReference	Unique identifier for the transaction.
voucherCode	Code that represents the purchased product.
redemptionUrl	URL where the voucher can be redeemed.
qrCodeData	QR code data for order that can redeem the product (e.g in eSim Pruchase).
deliveryField	Indicates which field (qrCodeData, voucherCode, or redemptionUrl) contains the redemption details.
productId	Unique identifier for the product.
providerName	Name of the provider.
name	Name of the product.
productCost	Cost of the product.
productCostCurrencyCode	Currency code for the product cost.
transactionDate	The date the trasaction was carried out.
transactionTime	The time the trasaction was carried out.
requestComment	Comment about the query request

 

This endpoint allows you to get your transaction history between two dates as a Service Reseller or Merchant.

You must provide three parameters (fromDate, toDate and status). Please note that you can not pull more than 2 month's record at a time. If you require a wider range, you can use export endpoint and the exported data will be sent to your admin email address.
Please Note: Personally identifiable information will be masked out in this report.

GET: /api/v1/Report/Reseller/TransactionHistory

Sample Request

GET: /api/v1/Report/Reseller/TransactionHistory?fromDate=2021-01-01&toDate=2021-02-01&status=all

Url Parameter	Description
fromDate	This is the start date of transactions you want to report on. Format must be ISO 8601 (YYYY-MM-DD) e.g 2021-01-25
toDate	This is the end date of transactions you want to report on. Format must be ISO 8601 (YYYY-MM-DD) e.g 2021-02-25
status	This is the type of report you want. Value must either be all, used or unused : all means all records including redeemed and unredeemed vouchers used means all voucher records that has been purchased and redeemed unused means all voucher records that has been purchased but not redeemed

 

Sample Response

Attribute	Description
transactionReference	The unique reference number for the transaction
transactionDate	The date of the transaction
voucher	The voucher code
currency	The currency of the voucher
voucherValue	The value of the voucher in the currency specified
transactedCurrency	The currency used in the transaction
transactedValue	The value of the transaction in the transacted currency
redeemedStatus	The status of the voucher (redeemed or not redeemed)
buyerFirstname	The first name of the buyer
buyerLastname	The last name of the buyer
buyerTelephone	The telephone number of the buyer
buyerEmail	The email address of the buyer
beneficiaryTelephone	The telephone number of the beneficiary
beneficiaryEmail	The email address of the beneficiary

 

{
    "authenticated": true,
    "sysDate": "2023-04-09T12:54:12.049Z",
    "sysErr": 200,
    "sysId": 230409125443850421,
    "sessionUid": "S:MJZQCMGEWECYVUCOZJXWQQVLP",
    "requestStatus": "PROCESSED",
    "message": "REQUEST OK",
    "response": [
        {
            "transactionReference": "2023040ikhkumwxxykymhjm",
            "transactionDate": "2023/04/09",
            "voucher": "GEJ*********KDB",
            "currency": "NGN",
            "voucherValue": "100.00",
            "transactedCurrency": "NGN",
            "transactedValue": "100.00",
            "redeemedStatus": "Not Redeemed",
            "buyerFirstname": "Harry",
            "buyerLastname": "Porter",
            "buyerTelephone": "+**********77",
            "buyerEmail": "po**************com",
            "beneficiaryTelephone": "+**********77",
            "beneficiaryEmail": "po**************com"
        },
        {
            "transactionReference": "2023040jeltyyfiseaddrvvas",
            "transactionDate": "2023/04/09",
            "voucher": "PVZ*********YOX",
            "currency": "GBP",
            "voucherValue": "100.00",
            "transactedCurrency": "NGN",
            "transactedValue": "0.00",
            "redeemedStatus": "Not Redeemed",
            "buyerFirstname": "Harry",
            "buyerLastname": "Porter",
            "buyerTelephone": "+**********77",
            "buyerEmail": "po**************com",
            "beneficiaryTelephone": "+**********77",
            "beneficiaryEmail": "po**************com"
        },
        {
            "transactionReference": "20230tqenmtdbnhhfavenpmm",
            "transactionDate": "2023/04/09",
            "voucher": "XCJ*********UYV",
            "currency": "GBP",
            "voucherValue": "100.00",
            "transactedCurrency": "NGN",
            "transactedValue": "57,191.70",
            "redeemedStatus": "Not Redeemed",
            "buyerFirstname": "Harry",
            "buyerLastname": "Porter",
            "buyerTelephone": "+**********77",
            "buyerEmail": "po**************com",
            "beneficiaryTelephone": "+**********77",
            "beneficiaryEmail": "po**************com"
        }
    ]
}

This endpoint allows you to update the delivery Email and Mobile phone for an already sold voucher as a Service Reseller or a Merchant .

A JSON object as described below must be sent in a http PATCH request body to the API endpoint. The transaction reference voucher must be used to perform this update.

Please note that this function is associated with elevated privileges. An email notification will be sent to your company's administrator concerning this modification.

PATCH: /api/v1/Voucher/UpdateDelivery

Sample Request Body

 
{
    buyerEmail:"tom.thomas@vendifydigital.com",
    beneficiaryEmail:"john.packer@vendifydigital.com",
    beneficiaryTelephone:"+4470000000000",
    transactionReference:"20230329084310lvjvztylvixpxlblgjsglomcc"
}

 

Attribute	Description
buyerEmail	The new email address of the buyer that will be updated on the voucher record.
beneficiaryEmail	The new email address of the beneficiary that will be updated on the voucher record.
beneficiaryTelephone	The new telephone number of the beneficiary in international format, the voucher PIN will be sent to this number.
transactionReference	A unique identifier for the transaction when the voucher was purchased. This will be used to identify the voucher to update.

 

Sample Response

Attribute	Description
voucherCode	The masked code of the voucher. Note the real voucher code would be sent to the buyer and beneficiary email.
status	The status of the voucher, with 1 indicating that it is successful and 0 indicating update request failed.
requestResponse	The server response message for the request to update the delivery details.
expirationDate	The expiration date of the voucher.

 

{
    "authenticated": true,
    "sysDate": "2023-04-23T22:16:17.525Z",
    "sysErr": 200,
    "sysId": 230410221663061557,
    "sessionUid": "S:TJCREQQVTWYUQTCGGQZKDZSSP",
    "requestStatus": "PROCESSED",
    "message": "REQUEST OK",
    "response": {
        "voucherCode": "LV***********LB",
        "status": 1,
        "requestResponse": "Delivery details has been updated.",
        "expirationDate": "2024-03-23"
    }
}

This endpoint allows you to retrieve a list of products for a specific category by providing the categoryCode in the GET request.

Endpoint

GET: api/v1/Product/Category/{categoryCode}
Sample Request: CategoryCode using giftcard
{baseurl}/api/v1/Product/Category/giftcard

Additional Required Request Headers:
X-Wallet-Id

 

Optional Product Filtering
You can filter products using the filters query parameter.

Available Filter Parameters

Filter Name	Example Value	Description
countryCode	USA USA,GBR ALL	Filters products by ISO country code. Use comma-separated values for multiple countries. Use ALL to return products for all countries.
subCategoryCode	Food-Beverage Food-Beverage,Home-Living	Filters products by subcategory. Use comma-separated values for multiple subcategories.
brandFamily	Xbox Amazon	Filters products by parent brand grouping. Useful when multiple regional brand codes belong to the same master brand.
brandCode	Uk-Xbox UK-Amazon	Filters products by brand code grouping.

 

Example Filtered Requests

Scenario	Example Request
Filter by USA only	{baseurl}/api/v1/Product/Category/esim?filters={"countryCode":"USA"}
Filter by USA & GBR	{baseurl}/api/v1/Product/Category/esim?filters={"countryCode":"USA,GBR"}
Filter by SubCategory	{baseurl}/api/v1/Product/Category/giftcard?filters={"subCategoryCode":"Food-Beverage"}
Filter by Brand Family	{baseurl}/api/v1/Product/Category/giftcard?filters={"brandFamily":"Xbox"}
Filter by Brand Code	{baseurl}/api/v1/Product/Category/giftcard?filters={"brandCode":"uk-aldi"}

 

NOTES: 

You can get a list of all available country codes by executing a GET request to:
{baseurl}/api/v1/product/countries

You can get a list of all available brand family by executing a GET request to:
{baseurl}/api/v1/product/brand-families

You can get a list of all available category codes by executing a GET request to:
{baseurl}/api/v1/product/categories

You can get a list of all available sub category codes for a Category of product by executing a GET request to:
{baseurl}/api/v1/product/subcategory/{categoryCode}

 

Sample Response:

{
    authenticated: true,
    sysDate: 2023-04-08T09:09:41.903Z,
    sysErr: 200,
    sysId: 230408090966705261,
    sessionUid: S:SRVBPHSDOBJGQREPJDPRGBQFE,
    requestStatus: PROCESSED,
    message: REQUEST OK,
    response: [
      {
            "productId": 4299,
            "productCode": "RW001827",
            "providerId": 8,
            "name": "Amazon UK eGift Voucher (Realtime)",
            "targetValue": 2313.30,
            "targetCurrencyId": 160,
            "targetCurrencyCode": "NGN",
            "originalValue": 1.00,
            "originalCurrencyId": 229,
            "originalCurrencyCode": "GBP",
            "value": 1.00,
            "valueCurrencyId": 229,
            "valueCurrencyCode": "GBP",
            "productCost": 2197.6350,
            "productCostCurrencyCode": "NGN",
            "productCostCurrencyId": 160,
            "walletId": "NGN-59",
            "category": "Gift Card",
            "categoryCode": "giftcard",
            "subCategory": "E-Commerce & Online Shopping",
            "subCategoryCode": "E-Commerce-Online-Shopping",
            "serviceCode": "amazon-uk",
            "brandFamily": "Amazon",
            "brandCode": "amazon-uk",
            "brandLogoUrl": "https://evend-assets-brands.s3.eu-west-2.amazonaws.com/app-images/amazon-uk.png",
            "providerName": "amazon-uk",
            "description": "Amazon a leading online retailer of products that inform, educate, and inspire.",
            "productMoreInfoUrl": "#",
            "expirationDate": "2035-12-09",
            "validity": "",
            "fxRate": {
                "rate": 2313.30,
                "currencyCode": "NGN"
            },
            "denominations": [
                {
                    "type": "range",
                    "minValue": 2.0,
                    "maxValue": 1000.0,
                    "currencyCode": "GBP"
                }
            ],
            "sysComment": "Cost converted from GBP to NGN"
        },
        {
            "productId": 4300,
            "productCode": "RW001827",
            "providerId": 8,
            "name": "Amazon UK eGift Voucher (Realtime)",
            "targetValue": 11566.50,
            "targetCurrencyId": 160,
            "targetCurrencyCode": "NGN",
            "originalValue": 5.00,
            "originalCurrencyId": 229,
            "originalCurrencyCode": "GBP",
            "value": 5.00,
            "valueCurrencyId": 229,
            "valueCurrencyCode": "GBP",
            "productCost": 10988.1750,
            "productCostCurrencyCode": "NGN",
            "productCostCurrencyId": 160,
            "walletId": "NGN-59",
            "category": "Gift Card",
            "categoryCode": "giftcard",
            "subCategory": "E-Commerce & Online Shopping",
            "subCategoryCode": "E-Commerce-Online-Shopping",
            "serviceCode": "amazon-uk",
            "brandFamily": "Amazon",
            "brandCode": "amazon-uk",
            "brandLogoUrl": "https://evend-assets-brands.s3.eu-west-2.amazonaws.com/app-images/amazon-uk.png",
            "providerName": "amazon-uk",
            "description": "Amazon a leading online retailer of products that inform, educate, and inspire.",
            "productMoreInfoUrl": "#",
            "expirationDate": "2035-12-09",
            "validity": "",
            "fxRate": {
                "rate": 2313.30,
                "currencyCode": "NGN"
            },
            "denominations": [
                {
                    "type": "fixed",
                    "minValue": 5.00,
                    "maxValue": 5.00,
                    "currencyCode": "GBP"
                }
            ],
            "sysComment": "Cost converted from GBP to NGN"
        }
  ]
}

 

Below is a description of product attributes returned inside the response object when retrieving product details.

 

Attribute	Description
productId	Unique identifier for the product.
productCode	Code assigned to the product. This code is used when making certain purchase request.
providerId	Unique identifier of the provider supplying the product.
name	Name of the product (e.g., Amazon UK Voucher).
targetValue	Converted value of the product based on the wallet currency (target currency) in use.
targetCurrencyId	Unique identifier of the target currency.
targetCurrencyCode	Currency code of the converted value (e.g., NGN).
originalValue	Original base value of the product before any currency conversion. You can use this as faceValue when placing an order
originalCurrencyId	Unique identifier of the original currency.
originalCurrencyCode	Currency code of the original value (e.g., USD).
value	Note: This field is depreaciated-It has the same value as originalValue field. It is the Original base value of the product before any currency conversion.
valueCurrencyId	Note: This field is depreaciated. Unique identifier of the product value currency.
valueCurrencyCode	Note: This field is depreaciated. Currency code of the product value (e.g., USD).
productCost	Total cost of the product in the wallet currency after conversion.
productCostCurrencyCode	Currency code of the product cost (e.g., NGN).
productCostCurrencyId	Unique identifier of the product cost currency.
walletId	Identifier of the wallet that will be debited for the purchase.
category	High-level product category (e.g., eSim).
categoryCode	Code representing the product category (e.g., esim).
subCategory	Specific grouping within the category (e.g., Middle East).
subCategoryCode	Code representing the product subcategory.
serviceCode	Internal service identifier where applicable. May be empty for some products.
brandFamily	The parent brand grouping for related brand variants (e.g., Apple). Useful for filtering or aggregating products across multiple regional brand codes.
brandCode	Unique code identifying the product brand.
brandLogoUrl	URL pointing to the brand’s logo image.
providerName	Name of the provider or network offering the product.
description	Detailed product description. I may include coverage countries, usage terms, and validity period.
productMoreInfoUrl	URL providing additional product details or documentation (if applicable).
expirationDate	Date when the product listing or voucher expires (if applicable).
validity	This field describes how long the product remains valid after purchase or activation. If this field is empty, the product may not have a specific validity period, or the validity information may be included in the product description.
fxRate.rate	Exchange rate applied when converting from the original currency to the wallet currency.
fxRate.currencyCode	Currency code associated with the exchange rate.
denominations.type	Indicates whether the product value is fixed or within a range (e.g., fixed).
denominations.minValue	Minimum allowable purchase value. For fixed products, this equals the maxValue.
denominations.maxValue	Maximum allowable purchase value. For fixed products, this equals the minValue.
denominations.currencyCode	Currency code applicable to the denomination values.
sysComment	System-generated note explaining pricing or conversion logic.
redeemableCountryCodes	List of ISO country codes where the product can be redeemed or expected to be used(e.g., GBR).

 

To retrieve products that can be used in a specific country, use the Get Product List By Category endpoint:

GET: api/v1/Product/Category/{categoryCode}

You can filter the product list using the countryCode filter parameter.

Example – Get eSIM products usable in the USA
{baseUrl}/api/v1/Product/Category/esim?filters={"countryCode":"USA"}

Example – Get eSIM products usable in USA and Great Britain
{baseUrl}/api/v1/Product/Category/esim?filters={"countryCode":"USA,GBR"}

The response will return products whose redeemableCountryCodes include the specified countries.

The redeemableCountryCodes field indicates the countries where a product can be redeemed or used.

This field is mainly applicable to eSIM products, and all eSIM products usually include one or more country codes in this field.

Example
"redeemableCountryCodes": ["GBR", "USA", "NGA"]

The values returned are ISO country codes representing the countries where the product is valid for use or redemption.

If the field contains an empty array, for example:

"redeemableCountryCodes": []

This usually means the product can be redeemed online globally or is not restricted to a specific country or region.

This endpoint allows you to retrieve a list of airtime and data bundle products using airtime or data-bundle as categoryCode in the GET request.

Airtime Endpoint: {baseurl}/api/v1/Product/Category/airtime

Databundle Endpoint: {baseurl}/api/v1/Product/Category/data-bundle

Endpoint Sample Request for Airtime

GET:api/v1/Product/Category/{categoryCode}
Sample Request for Airtime: CategoryCode using airtime
{baseurl}/api/v1/Product/Category/airtime

Pull Airtime using Filters
To filter airtime products by country or region, you can add a filters query parameter to the endpoint. For example, to get products in the "airtime" category available in a country, use the following request:
{baseurl}/api/v1/Product/Category/airtime?filters={"countryCode":"{countryCode}"}

To pull all products in a airtime category, regardless of country or region, you can also use the ALL filter value. For example, to get all products in the "airtime" category for all countries:
{baseurl}/api/v1/Product/Category/airtime?filters={"countryCode":"ALL"}

 

You can obtain a list of all country codes by executing a GET request to:
{baseurl}/api/v1/Product/Countries

Additional Required Request Headers:
X-Currency-Id and X-Currency-Code

 

NOTES: 

You can obtain a list of all available country codes by executing a GET request to:
{baseurl}/api/v1/product/countries

You can obtain a list of all available sub category codes for a Category of product by executing a GET request to:
{baseurl}/api/v1/product/SubCategory/{categoryCode}

 

Sample Response:

{
    authenticated: true,
    sysDate: 2023-04-08T09:09:41.903Z,
    sysErr: 200,
    sysId: 230408090966705261,
    sessionUid: S:SRVBPHSDOBJGQREPJDPRGBQFE,
    requestStatus: PROCESSED,
    message: REQUEST OK,
     response: [
        {
            "originalCurrencyId": 160,
            "targetCurrencyId": 230,
            "originalCurrencyCode": "NGN",
            "targetCurrencyCode": "USD",
            "originalValue": 500.00,
            "targetValue": 0.278000,
            "status": 1,
            "category": "AirTime",
            "categoryCode": "airtime",
            "subCategory": "Africa - Nigeria - MTN",
            "subCategoryCode": "Africa-Nigeria-MTN",
            "productId": 9418,
            "productCode": "MFIN5OR",
            "brandCode": "mtn-nigeria",
            "brandLogoUrl": "https://evend-assets-brands.aws.com/mylogo.png",
            "providerId": 123,
            "providerName": "eVend Data Store",
            "name": "MTN Airtime",
            "description": "MTN Airtime. Product Code MFIN-5-OR",
            "productMoreInfoUrl": "#",
            "expirationDate": "2035-12-09",
            "value": 500.00,
            "valueCurrencyId": 160,
            "valueCurrencyCode": "NGN",
            "productCost": 0.278000,
            "productCostCurrencyCode": "USD",
            "productCostCurrencyId": 230,
            "sysComment": "Cost Converted from base(NGN) to USD rate of 0.000556",
            "denominations": [
                {
                    "type": "fixed",
                    "minValue": 500.0,
                    "maxValue": 500.0,
                    "currencyCode": "NGN"
                },
                {
                    "type": "range",
                    "minValue": 500.0,
                    "maxValue": 50000.0,
                    "currencyCode": "NGN"
                }
            ]
        },
        {
            "originalCurrencyId": 160,
            "targetCurrencyId": 230,
            "originalCurrencyCode": "NGN",
            "targetCurrencyCode": "USD",
            "originalValue": 500.00,
            "targetValue": 0.278000,
            "status": 1,
            "category": "AirTime",
            "categoryCode": "airtime",
            "subCategory": "Africa - Nigeria - AIRTEL",
            "subCategoryCode": "Africa-Nigeria-AIRTEL",
            "productId": 9419,
            "productCode": "MFIN1OR",
            "brandCode": "airtel-nigeria",
            "brandLogoUrl": "https://evend-assets-brands.aws.com/mylogo.png",
            "providerId": 123,
            "providerName": "eVend Data Store",
            "name": "Airtel NG Airtime",
            "description": "Airtel Airtime. Code MFIN-1-OR",
            "productMoreInfoUrl": "#",
            "expirationDate": "2025-12-09",
            "value": 500.00,
            "valueCurrencyId": 160,
            "valueCurrencyCode": "NGN",
            "productCost": 0.278000,
            "productCostCurrencyCode": "USD",
            "productCostCurrencyId": 230,
            "sysComment": "Cost Converted from base(NGN) to USD rate of 0.000556",
            "denominations": [
                {
                    "type": "fixed",
                    "minValue": 500.0,
                    "maxValue": 500.0,
                    "currencyCode": "NGN"
                },
                {
                    "type": "range",
                    "minValue": 500.0,
                    "maxValue": 50000.0,
                    "currencyCode": "NGN"
                }
            ]
        },
        {
            "originalCurrencyId": 160,
            "targetCurrencyId": 230,
            "originalCurrencyCode": "NGN",
            "targetCurrencyCode": "USD",
            "originalValue": 500.00,
            "targetValue": 0.278000,
            "status": 1,
            "category": "AirTime",
            "categoryCode": "airtime",
            "subCategory": "Africa - Nigeria - GLO",
            "subCategoryCode": "Africa-Nigeria-GLO",
            "productId": 9420,
            "productCode": "MFIN6OR",
            "brandCode": "glo-nigeria",
            "brandLogoUrl": "https://evend-assets-brands.aws.com/mylogo.png",
            "providerId": 123,
            "providerName": "eVend Data Store",
            "name": "Glo NG Airtime",
            "description": "Glo NG Airtime. Code MFIN-6-OR",
            "productMoreInfoUrl": "#",
            "expirationDate": "2025-12-09",
            "value": 500.00,
            "valueCurrencyId": 160,
            "valueCurrencyCode": "NGN",
            "productCost": 0.278000,
            "productCostCurrencyCode": "USD",
            "productCostCurrencyId": 230,
            "sysComment": "Cost Converted from base(NGN) to USD rate of 0.000556",
            "denominations": [
                {
                    "type": "fixed",
                    "minValue": 500.0,
                    "maxValue": 500.0,
                    "currencyCode": "NGN"
                },
                {
                    "type": "range",
                    "minValue": 500.0,
                    "maxValue": 50000.0,
                    "currencyCode": "NGN"
                }
            ]
        },
        {
            "originalCurrencyId": 160,
            "targetCurrencyId": 230,
            "originalCurrencyCode": "NGN",
            "targetCurrencyCode": "USD",
            "originalValue": 500.00,
            "targetValue": 0.278000,
            "status": 1,
            "category": "AirTime",
            "categoryCode": "airtime",
            "subCategory": "Africa - Nigeria - 9Mobile",
            "subCategoryCode": "Africa-Nigeria-9Mobile",
            "productId": 9421,
            "productCode": "MFIN2OR",
            "brandCode": "nigeria-9mobile",
            "brandLogoUrl": "https://evend-assets-brands.aws.com/mylogo.png",
            "providerId": 123,
            "providerName": "eVend Data Store",
            "name": "9mobile NG Airtime",
            "description": "9mobile NG Airtime. Code MFIN-2-OR",
            "productMoreInfoUrl": "#",
            "expirationDate": "2025-12-09",
            "value": 500.00,
            "valueCurrencyId": 160,
            "valueCurrencyCode": "NGN",
            "productCost": 0.278000,
            "productCostCurrencyCode": "USD",
            "productCostCurrencyId": 230,
            "sysComment": "Cost Converted from base(NGN) to USD rate of 0.000556",
            "denominations": [
                {
                    "type": "fixed",
                    "minValue": 500.0,
                    "maxValue": 500.0,
                    "currencyCode": "NGN"
                },
                {
                    "type": "range",
                    "minValue": 500.0,
                    "maxValue": 50000.0,
                    "currencyCode": "NGN"
                }
            ]
        }
    ]

}

 

Attribute	Description
originalCurrencyId	ID of the original currency used for the product.
targetCurrencyId	ID of the target currency after conversion.
originalCurrencyCode	Currency code of the original currency (e.g., GBP).
targetCurrencyCode	Currency code of the target currency (e.g., USD).
originalValue	Value of the product in the original currency.
targetValue	Converted value of the product in the target currency.
status	Status of the product (e.g., 1 is active, 0 is inactive).
category	General category of the product (e.g., Gift Card).
categoryCode	Code representing the product's category.
subCategory	Specific subcategory of the product (e.g., Home & Living).
subCategoryCode	Code representing the product's subcategory.
productId	Unique identifier for the product.
productCode	Code representing the specific product.
brandCode	Code representing the product brand.
brandLogoUrl	Url for the product brand logo.
providerId	Unique identifier of the product provider.
providerName	Name of the provider offering the product.
name	Name of the product.
description	Brief description of the product.
productMoreInfoUrl	URL for more information about the product.
expirationDate	Date when the product expires.
value	The face value of the product.
valueCurrencyId	ID of the currency of the product's value.
valueCurrencyCode	Currency code used for the product's value (e.g., USD).
productCost	The product cost. Amount paid for the product. This is exclusive of any commission received
productCostCurrencyId	ID of the currency of the product's cost.
productCostCurrencyCode	Currency code used for the product's cost (e.g., USD).
sysComment	System-generated comment explaining the value conversion where applicable.

 

This endpoint allows you to validate a Utility Service such as Electricty, Cable TV unique account ID before making a purchase.

This endpoint will show you available product codes that you can use when purchasing certain services and if the uniqueAccountId provided is valid

Validation Endpoint: {baseurl}/api/v1/validations

Required Input Fields

Attribute	Required	Description
uniqueAccountId	YES	This is the Unique Customer or Client Account number for the service been requested. E.g Meter number, DTSV Smart Card number etc
productId	YES/NO	This is the Product id for the product or service. Other optional fields will be ignored if this field is provided
serviceCode	YES/NO	Specifies the Service Code for the product. Please check the product listing for this value. This field is optional if the productId is provided.
brandCode	YES/NO	Specifies the Brand Code for the product. Please check the product listing for this value. This field is optional if the productId is provided.
serviceType	YES/NO	Specifies the service type for the product. For utility products, the value must be either PREPAID or POSTPAID. This field is optional if the productId is provided.

 

Sample Request:

 {
 "serviceCode":"TV",
 "productId":123,
 "uniqueAccountId":"4111ZZZZ863979",
 "brandCode":"DSTV",
 "serviceType":"PREPAID"
 }

Sample Response:

{
    "authenticated": true,
    "sysDate": "2024-01-06T10:39:44.406Z",
    "sysErr": 200,
    "sysId": 240106103984646342,
    "sessionUid": "S:ICXXLOSROUTFKQDSZTHFJFZLY",
    "requestStatus": "PROCESSED",
    "message": "REQUEST OK",
    "response": {
        "productId": 9422,
        "providerId": 123,
        "status": "200",
        "message": "successful",
        "accountName": "Test User",
        "uniqueAccountId": "4111ZZZZ863979",
        "brandCode": "DSTV",
        "productOptions": [
            {
                "productName": "Compact + Showmax_",
                "productCode": "ng_dstv_showcompe36",
                "noOfMonths": 1,
                "value": 17450
            },
            {
                "productName": "ASIAE36 + SHOWMAXE36_",
                "productCode": "ng_dstv_showasiae36",
                "noOfMonths": 1,
                "value": 15900
            },
            {
                "productName": "DStv Indian_",
                "productCode": "ng_dstv_asiae36",
                "noOfMonths": 1,
                "value": 12400
            },
            {
                "productName": "DStv Yanga_",
                "productCode": "ng_dstv_nnj1e36",
                "noOfMonths": 1,
                "value": 5100
            },
            {
                "productName": "PremiumFrench + Showmax_",
                "productCode": "ng_dstv_showprwfrnse36",
                "noOfMonths": 1,
                "value": 57500
            },
            {
                "productName": "DStv Compact Plus_",
                "productCode": "ng_dstv_comple36",
                "noOfMonths": 1,
                "value": 25000
            },
            {
                "productName": "DStv French Touch_",
                "productCode": "ng_dstv_frn7e36",
                "noOfMonths": 1,
                "value": 5800
            },
            {
                "productName": "CompactPlus + Showmax_",
                "productCode": "ng_dstv_showcomple36",
                "noOfMonths": 1,
                "value": 26750
            }
        
        ],
        "transactionReference": "20250106103944daauwrodttxydpjhcnbidspgq",
        "validated": true
    }
}

 

Attribute	Description
productId	Unique identifier for the product.
providerId	Identifier for the service provider.
productCode	Code assigned to the product, can be null.
status	Response status code indicating the request outcome.
message	Descriptive message about the request status.
accountName	Name of the account associated with the uniqueAccountId.
uniqueAccountId	Unique identifier for the account.
brandCode	Code representing the brand of the product.
productOptions	List of available product options (when available).
productName	Name of the product.
productCode	Code assigned to the product.
noOfMonths	Duration of the product subscription in months.
value	Price or cost of the product.
validated	Boolean flag indicating whether the data is validated.

 

This guide provides a step-by-step walkthrough to help you purchase airtime products from our API.
We will be using Nigerian airtime for this use case.

Please note that this is just a guide, and we trust that you will automate the process to suit your application's needs.

Please note {{baseUrl}} is the API base url

STEP 1: In the header of your request, make sure the following attributes are present

Header	Required	Description
X-Api-Key	Yes	The API key for authenticating the API request
X-Nonce	Yes	A unique nonce value to prevent replay attacks
X-Signature	Yes	The signature for the API request. You are required to sign your APIKey+Nonce and include the signature in this header.
X-Wallet-Id	Yes	This is the wallet Id of the currency you wish to use to transanct.
X-Currency-Id	No	The ID of the currency being used in the request. Our system may ignore it in some requests if not relevant. This is depreciated. Use X-Wallet-Id instead
X-Currency-Code	No	X-Currency-Code is the ISO code of the currency being used in the request. Our system may ignore it in some requests if not relevant. This is depreciated. Use X-Wallet-Id instead

 

STEP 2: Get List of Airtime products
GET: {{baseUrl}}/api/v1/Product/Category/airtime?filters={"countryCode":"nga"}

 

STEP 3: Choose Network you want to buy from and the note the following fields:
productId,providerId

STEP 4: Use values retrieved in Step 3 to fill the standard request payload and use the end point below.
POST: {{baseUrl}}/api/v1/orders

Sample Request Payload

{
 productId:9418,
 providerId:123,
 value:500.00,
 walletId:"NGN-456",
 uniqueAccountId : "+2348038030133",
 transactionTitle : "MTN Nigeria Airtime",
 transactionComment : "MTN Nigeria Airtime via Voucher-API",
 beneficiaryEmail : "info@vendifydigital.com"
 }

Sample Response

{
    "authenticated": true,
    "sysDate": "2025-01-29T11:57:11.976Z",
    "sysErr": 200,
    "sysId": 250129115711054438,
    "sessionUid": "S:BAXPCIDRKCCQDUHEFAYMWKVOD",
    "requestStatus": "PROCESSED",
    "message": "REQUEST OK",
    "response": {
        "responseStatus": "SUCCESS",
        "responseMessage": "Product purchased successfully. Email receipt sent.",
        "transactionReference": "250129115711054438:S:BAXPCIDRKCCQDUHEFAYMWKVOD",
        "voucherCode": "AIRT 2501 2911 5711 0544 38:S :BAX PCID RKCC QDUH EFAY MWKV OD",
        "productId": 9418,
        "productCode": "MFIN5OR",
        "providerId": 123,
        "providerName": "MTN NG",
        "name": "MTN Airtime",
        "description": "MTN Airtime. Product Code MFIN-5-OR",
        "productMoreInfoUrl": "#",
        "expirationDate": "2035-12-09",
        "value": 500.0,
        "valueCurrencyId": 160,
        "valueCurrencyCode": "NGN",
        "productCost": 500.0,
        "productCostCurrencyCode": "NGN",
        "productCostCurrencyId": 160,
        "sysComment": ""
    }
}

 

To simulate SUCCESSFUL or FAILED transactions, use the following test numbers in the Sandbox environment for airtime purchase.

• SUCCESSFUL: Use +2348012121212 as the uniqueAccountId in the order request.

• FAILED: Use +2348013131313 as the uniqueAccountId in the order request.

These test cases allow you to mimic real-world scenarios where a transaction is Successful or may Fail

To review what your system sent to the API and the response returned by the system, use the View API Logs feature available in the Portal.

Navigation Path
PORTAL TOOLS → Site Management → View API Logs

What You Can See
Request payload sent to the API
System response returned for the request
HTTP status code and timestamps

Audit Trail & Email Notification
Each time an API log is accessed, an audit trail entry is recorded and an automatic email notification is sent to the logged-in user confirming the log access.

This feature is useful for troubleshooting, reconciliation, and security monitoring.