NAV Navbar
Logo
cURL

Introduction

Welcome to the Ugmart API! You can use our API to access Ugmart API endpoints, which can enable you to request and deposit mobile money payments to mobile money subscribers in Uganda.

We support mobile money providers including, MTN, Airtel and SmartPesa. Our API also support VISA and Mastercard. The Ugmart API is REST based. You can view examples on how to use use the API on the right.

All the responses will be JSON formatted.

Getting Started

Please follow the steps below to setup your account with UGMART and start receiving or making payments;

  1. Create Account here. Please ensure that you provide an email you have access to. A confirmation link will be sent to that address for verification before the sign up is completed. Click the link in the email to complete the account creation process.

  2. Login to create your first collection account. A collection account is a requirement for one to start receiving payments or sending money with UGMART.

  3. Once the collection account creation is done, you are now ready to proceed with the API endpoints and start processing payments.

API Endpoint

The UGMART API can be accessed at the following endpoint;

All requests to the API must use the HTTPS protocol

Authentication

Authentication Request

Sample authentication request:

curl "https://app.ugmart.ug/api/login" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
      "email": "jane.doe@domain.com",
      "password": "password"
    }'

The UGMART API uses JSON Web Token (JWT) Authentication, and requires the generated token for all the API requests. To obtain this token, authenticate using the details created during sign up. Use the email and password to authenticate and obtain the JWT.

The JWT can be stored on your end and for every other request made to the API, the token should be passed in Authorization header as demonstrated in the sample request on the right.

The JWT is reusable until it expires. Each request after token expiration will result in a 401 response. Redo the authentication process to obtain a new token.

Authentication Response

Sample Authentication Response

{
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXUyJ9.eyJleHAiOjE0MzQ3Mjc1MzYsInVzZXJuYW1lIjoia29ybGVvbiIsImlhdCI6IjE0MzQ2NDExMzYifQ.nh0L_wuJy6ZKIQWh6OrW5hdLkviTs1_bau2GqYdDCB0Yqy_RplkFghsuqMpsFls8zKEErdX5TYCOR7muX0aQvQxGQ4mpBkvMDhJ4-pE4ct2obeMTr_s4X8nC00rBYPofrOONUOR4utbzvbd4d2xT_tj4TdR_0tsr91Y7VskCRFnoXAnNT-qQb7ci7HIBTbutb9zVStOFejrb4aLbr7Fl4byeIEYgp2Gd7gY",
    "expires_in": 1800,
    "email": "jane.doe@domain.com"
}

When the correct credentials are supplied for the authentication request, a token is returned with other session details as described below

Parameter Type Description
token string The JWT authentication token
expires_in integer The duration (seconds) from the token creation time in which the token will expire
email string Email address of the logged in user

Error Handling

Sample 401 Unauthorized Error due to sending an expired token with the request:

{
    "code": 401,
    "message": "Expired JWT. Please renew it"
}

UGMART uses HTTP response status codes to indicate success or failure. When a request to our API is successful, UGMART returns an HTTP response code in the 2XX range. And when a request fails, UGMART returns an HTTP response code in the 4XX or 5XX range. Below is a summary of the response codes

Common Error Codes

HTTP Error Code Meaning
200 OK - Request was successful
400 Bad Request - Malformed request or missing required parameters
401 Unauthorized - Missing token, expired token
403 Forbidden - You are trying to access a resource for which you don’t have proper access rights.
404 Not Found - You are trying to access a resource that does not exist
422 Unprocessable Entity - You provided all the required parameters but they are not proper for the request
500 Internal Server Error - We had a glitch in our servers. Retry the request in a little while or contact support
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Payment Providers

Provider List Request

Payment Provider List request

curl "https://app.ugmart.ug/api/payment-providers" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" 

Before making any requests for payment or to send money, you may need to know the available payment providers on the UGMART platform and respective codes that are used in the requests. The endpoint below requests for the list of available payment providers.

HTTP Request

GET https://app.ugmart.ug/api/payment-providers

Provider List Response

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully",
    "data": [
        {
            "name": "Airtel Money",
            "code": "airtel_money",
            "available": true
        },
        {
            "name": "MTN Mobile Money",
            "code": "mtn_mobile_money",
            "available": true
        },
        {
            "name": "Smart Pesa",
            "code": "smart_pesa",
            "available": true
        },
        {
            "name": "VISA-MasterCard",
            "code": "visa_mastercard",
            "available": true
        }
    ]
}

Response Parameters

Parameter Type Description
code integer The HTTP Status Code
status string Response status: SUCCESS or FAILED
message string Descriptive response message
data JSON String Details of the each payment provider. code is the value you would use for requesting payment or sending money. available indicates the availability of the payment provider for transaction processing

Mobile Money

Request Money

Example request payment request

curl "https://app.ugmart.ug/api/collection" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "account_code": "DD00556698745",
      "transaction_id": "auto",
      "provider_id": "airtel_money",
      "msisdn": "256123456789",
      "currency": "UGX",
      "amount": 500,
      "application": "Acme",
      "description": "Payment Request."
    }'

This endpoint requests payment from a mobile money subscriber. If request returns success, the mobile money provider has accepted the request and forwarded to the subscriber. Subscriber will enter their PIN and authorize the transaction. On successful authorization, we will send a callback to client provided endpoint or they can manually check for the status of a transaction by using the following endpoint: Retrieve a single transaction

HTTP Request

POST https://app.ugmart.ug/api/collection

Arguments

Parameter Type Required Description
account_code string Required Collection Account code. This can be copied from the dashboard where the account was created
transaction_id string Required A unique generated string to identify request. If the value is “auto”, the API generates this ID on your behalf
provider_id string Required Mobile money provider identifier. Currently available values: mtn_mobile_money, airtel_money
msisdn string Required Mobile money subscribers phone number from which to deduct payment. for example 256123456789
currency string Required 3 letter ISO currency code for example UGX. No currency conversion is done, so the currency must be valid for the given phone number (msisdn). Currently the only available value is: UGX
amount integer Required Amount to be deducted from mobile money subscriber’s account.
application string Required Name for application making request
description string Required A description for the request

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Collection request accepted!",
    "data": {
        "transaction_id": "9632555544444",
        "external_transaction_id": "TT54785478547",
        "msisdn": "256123456789",
        "status": "PENDING",
        "amount": 500,
        "currency": "UGX",
        "transaction_charge": 12.5,
        "provider_id": "airtel_money",
        "description": "Payment Request."
    }
}

Example failure response:

{
    "code": 400,
    "status": "FAILED",
    "message": "The phone number '0123456789' is not valid for Airtel Money."
}

HTTP Response

Arguments

Parameter Type Description
code integer The HTTP Status Code
status string Response status: SUCCESS or FAILEDor INCOMPLETE
message string Descriptive response message
data JSON String Details of the request plus the transaction charge (amount charged by UGMART for the transaction)

Send Money

Example send payment request

curl "https://app.ugmart.ug/api/payout" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "account_code": "AA01234567",
      "transaction_id": "auto",
      "msisdn": "256701345672",
      "currency": "UGX",
      "amount": 500,
      "application": "Acme",
      "description": "School Fees",
      "recipient_name": "Jane Doe"
    }'

This endpoint sends payment/money to a mobile money subscriber.

HTTP Request

POST https://app.ugmart.ug/api/payout

Arguments

Parameter Type Required Description
account_code string Required Collection Account code. This can be copied from the dashboard where the account was created
transaction_id string Required A unique generated string to identify request. If the value is “auto”, the API generates this ID on your behalf
msisdn string Required The recipient’s mobile money account number to which the money will be sent. for example 256701345672
currency string Required 3 letter ISO currency code for example UGX. No currency conversion is done, so the currency must be valid for the given phone number (msisdn). Currently the only available value is: UGX
amount integer Required Amount to be withdrawn from the collection account wallet and sent to the recipient’s mobile money account.
application string Required Name for application making request. This also serves as the reason in the mobile money SMS to the recipient
description string Required A description for the request
recipient_name string Required Full Name of the mobile money recipient

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Transaction completed successfully",
    "data": {
        "transaction_id": "1513641884",
        "msisdn": "256701345672",
        "amount": 500,
        "currency": "UGX",
        "transaction_charge": 1000,
        "provider_id": "airtel_money",
        "description": "Jane Doe (School Fees)"
    }
}

Example failure response:

{
    "code": 422,
    "status": "FAILED",
    "message": "Airtel Money does not support the 'USD' currency."
}

HTTP Response

Arguments

Parameter Type Description
code integer The HTTP Status Code
status string Response status: SUCCESS or FAILEDor INCOMPLETE
message string Descriptive response message
data JSON String Details of the request plus the transaction charge (amount charged by UGMART for the transaction)

Validate Mobile Number

Example validate mobile number request

curl "https://app.ugmart.ug/api/validate-account" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "provider_id": "airtel_money",
      "msisdn": "256703560861"
    }'

This endpoint validates a mobile money subscriber’s number.

HTTP Request

POST https://app.ugmart.ug/api/validate-account

Arguments

Parameter Type Required Description
provider_id string Required Mobile money provider identifier. Currently available values: airtel_money, smart_pesa
msisdn string Required Mobile money subscriber’s phone number. for example 256703560861.

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "CUSTOMER VALIDATED OK",
    "data": {
        "valid": true,
        "customer_name": "SEKAMANYA GILBERT",
        "msisdn": "256703560861"
    }
}

Example failure response:

{
    "code": 400,
    "status": "FAILED",
    "message": "'256777044237' is not valid for Airtel Money"
}

VISA / MasterCard

Request Payment Session

Example request payment session request

curl "https://app.ugmart.ug/api/request-payment" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "account_code": "AA01234567",
      "transaction_id": "auto",
      "provider_id": "visa_mastercard",
      "msisdn": "0701345672",
      "currency": "UGX",
      "amount": 500,
      "application": "Acme",
      "description": "Payment Request.",
      "callback_url": "http://www.callbackurl.com"
    }'

This endpoint requests payment from VISA / MasterCard.

HTTP Request

POST https://app.ugmart.ug/api/request-payment

Arguments

Parameter Type Required Description
account_code string Required Collection Account code. This can be copied from the dashboard where the account was created
transaction_id string Required A unique generated string to identify request. If the value is “auto”, the API generates this ID on your behalf
provider_id string Required Payment provider identifier: visa_mastercard
msisdn string Required A contact mobile number on which the payment confirmation SMS will be sent. for example 0701345672
currency string Required 3 letter ISO currency code for example UGX. Currently available values are: UGX and USD
amount integer Required Amount to be deducted from payer’s card.
application string Required Name for application making request
description string Required A description for the request
callback_url string Required The URL that will be called back on SUCCESS, FAILURE or CANCEL
Event Type Callback URL
failure http://www.callbackurl.com?code=&status=FAILED&message=&data[transaction_id]=
cancel http://www.callbackurl.com?code=&status=CANCELLED&message=&data[transaction_id]=
success http://www.callbackurl.com?code=&status=SUCCESS&message=&data[transaction_id]=

Example success response:

{
    "code": 200,
    "status": "PENDING",
    "message": "Transaction Initiated",
    "data": {
        "transaction_id": "1513795691",
        "payment_url": "https://app.ugmart.ug/api/visa-payment/1513852112505"
    }
}

Example failure response:

{
    "code": 400,
    "status": "FAILED",
    "message": "Please provide a value for the 'callback_url' parameter"
}

HTTP Response

Arguments

Parameter Type Description
code integer The HTTP Status Code
status string Response status: PENDING
message string Descriptive response message
data JSON String Details of the request plus the payment URL (URL that loads the payment form to be filled by customer. only returned on success)

Balance Check

Balance(s) for all Collection Accounts

Example balance check request for all collection accounts

curl "https://app.ugmart.ug/api/balance" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" 

This endpoint requests for the balance(s) of the user collection account(s)

HTTP Request

GET https://app.ugmart.ug/api/balance

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully",
    "data": [
        {
            "account_code": "15B0D8D8BE",
            "account_name": "GBi-Solutions (U) Ltd",
            "wallets": [
                {
                    "currency": "USD",
                    "balance": 0.96
                },
                {
                    "currency": "UGX",
                    "balance": 2342.5
                }
            ]
        }
    ]
}

Example failure response:

{
    "code": 401,
    "status": "FAILED",
    "message": "Expired JWT. Please renew it."
}

HTTP Response

Arguments

Parameter Type Description
code integer The HTTP Status Code
status string Response status: SUCCESS or FAILED
message string Descriptive response message
data JSON String Details of each collection account and the balances on each currency wallet

Balance(s) for one Collection Account

Example balance check request for a single collection account

curl "https://app.ugmart.ug/api/balance/15B0D8D8BE" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" 

This endpoint requests for the balance(s) of the specified user collection account

HTTP Request

GET https://app.ugmart.ug/api/balance/{account_code}

URL Parameters

Parameter Type Required Description
account_code string Required Collection Account code. This can be copied from the dashboard where the account was created

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully",
    "data": {
        "account_code": "15B0D8D8BE",
        "account_name": "GBi-Solutions (U) Ltd",
        "wallets": [
            {
                "currency": "USD",
                "balance": 0.96
            },
            {
                "currency": "UGX",
                "balance": 2342.5
            }
        ]
    }
}

Example failure response:

{
    "code": 404,
    "status": "FAILED",
    "message": "Collection Account with code '15B0D8D8B' does not exist in your profile",
    "data": []
}

HTTP Response

Arguments

Parameter Type Description
code integer The HTTP Status Code
status string Response status: SUCCESS or FAILED
message string Descriptive response message
data JSON String Details of the collection account and the balances on each currency wallet

Transactions

List all transactions

Example transactions request

curl "https://app.ugmart.ug/api/transactions" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" 

This endpoint requests a list of transactions under all the collection accounts owned by the logged in user

HTTP Request

GET https://app.ugmart.ug/api/transactions

Example success response:

{
    "currentPage": 1,
    "itemsPerPage": 20,
    "totalItems": 100,
    "data": [
        {
            "transaction_id": "1513319878",
            "collection_account": {
                "account_code": "15B0D8D8BE",
                "account_name": "GBi-Solutions (U) Ltd"
            },
            "payment_provider": {
                "name": "VISA-MasterCard",
                "code": "visa_mastercard"
            },
            "type": "COLLECTION",
            "msisdn": "VISA-MasterCard",
            "currency": "UGX",
            "application": "CallbackTest",
            "description": "Transaction Event Test",
            "amount": 1000,
            "charge": 0,
            "status": "CANCELLED",
            "status_message": "Transaction has been cancelled",
            "transaction_date": "2017-12-15T09:13:39+03:00",
            "completed_on": "2017-12-15T09:15:03+03:00"
        },
        {
            "transaction_id": "1512446532",
            "collection_account": {
                "account_code": "UGM6779231",
                "account_name": "Jane Doe Enterprises"
            },
            "payment_provider": {
                "name": "VISA-MasterCard",
                "code": "visa_mastercard"
            },
            "type": "COLLECTION",
            "msisdn": "VISA-MasterCard",
            "currency": "UGX",
            "application": "CallbackTest",
            "description": "Transaction Event Test",
            "amount": 1000,
            "charge": 0,
            "status": "FAILED",
            "status_message": "Unexpected parameter 'interaction.operation' (Cause: INVALID_REQUEST).",
            "transaction_date": "2017-12-05T06:17:37+03:00",
            "completed_on": "2017-12-05T06:18:16+03:00"
        }
    ]
}

Example failure response:

{
    "code": 401,
    "message": "Expired JWT. Please renew it"
}

HTTP Response

Arguments

Parameter Type Description
currentPage integer Pagination parameter describing the currently requested page
itemsPerPage integer Pagination parameter describing how many items have been requested for every page. 20 is the default
totalItems integer Pagination parameter describing the total number of results
data JSON String Details of each transaction (for all types of transactions). The status of each transaction at the time of the request is provided in the response

List transactions of a collection account

Example transactions request for a collection account

curl "https://app.ugmart.ug/api/transactions?collectionAccount=15B0D8D8BE" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" 

This endpoint requests a list of transactions under the given collection account

HTTP Request

GET https://app.ugmart.ug/api/transactions?collectionAccount={account_code}

URL Parameters

Parameter Type Required Description
collectionAccount string Required Collection Account code. This can be copied from the dashboard where the account was created

Example success response:

{
    "currentPage": 1,
    "itemsPerPage": 20,
    "totalItems": 100,
    "data": [
        {
            "transaction_id": "1513319878",
            "collection_account": {
                "account_code": "15B0D8D8BE",
                "account_name": "GBi-Solutions (U) Ltd"
            },
            "payment_provider": {
                "name": "VISA-MasterCard",
                "code": "visa_mastercard"
            },
            "type": "COLLECTION",
            "msisdn": "VISA-MasterCard",
            "currency": "UGX",
            "application": "CallbackTest",
            "description": "Transaction Event Test",
            "amount": 1000,
            "charge": 0,
            "status": "CANCELLED",
            "status_message": "Transaction has been cancelled",
            "transaction_date": "2017-12-15T09:13:39+03:00",
            "completed_on": "2017-12-15T09:15:03+03:00"
        },
        {
            "transaction_id": "1512446532",
            "collection_account": {
                "account_code": "15B0D8D8BE",
                "account_name": "GBi-Solutions (U) Ltd"
            },
            "payment_provider": {
                "name": "VISA-MasterCard",
                "code": "visa_mastercard"
            },
            "type": "COLLECTION",
            "msisdn": "VISA-MasterCard",
            "currency": "UGX",
            "application": "CallbackTest",
            "description": "Transaction Event Test",
            "amount": 1000,
            "charge": 0,
            "status": "FAILED",
            "status_message": "Unexpected parameter 'interaction.operation' (Cause: INVALID_REQUEST).",
            "transaction_date": "2017-12-05T06:17:37+03:00",
            "completed_on": "2017-12-05T06:18:16+03:00"
        }
    ]
}

Example failure response:

{
    "code": 404,
    "status": "FAILED",
    "message": "Collection Account with code '15B0D8D8B' does not exist in your profile"
}

HTTP Response

Arguments

Parameter Type Description
currentPage integer Pagination parameter describing the currently requested page
itemsPerPage integer Pagination parameter describing how many items have been requested for every page. 20 is the default
totalItems integer Pagination parameter describing the total number of results
data JSON String Details of each transaction (for all types of transactions). The status of each transaction at the time of the request is provided in the response

Retrieve a single transaction

Example single transaction request

curl "https://app.ugmart.ug/api/transactions?id=1513319878" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" 

This endpoint requests for a single collection account transaction

HTTP Request

GET https://app.ugmart.ug/api/transactions?id={transaction_id}

URL Parameters

Parameter Type Required Description
id string Required ID of the transaction to be retrieved

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully",
    "data": {
        "transaction_id": "1513319878",
        "collection_account": {
            "account_code": "15B0D8D8BE",
            "account_name": "GBi-Solutions (U) Ltd"
        },
        "payment_provider": {
            "name": "VISA-MasterCard",
            "code": "visa_mastercard"
        },
        "type": "COLLECTION",
        "msisdn": "VISA-MasterCard",
        "currency": "UGX",
        "application": "CallbackTest",
        "description": "Transaction Event Test",
        "amount": 1000,
        "charge": 0,
        "status": "CANCELLED",
        "status_message": "Transaction has been cancelled",
        "transaction_date": "2017-12-15T09:13:39+03:00",
        "completed_on": "2017-12-15T09:15:03+03:00"
    }
}

Example failure response:

{
    "code": 404,
    "status": "FAILED",
    "message": "Transaction '151331987' not found"
}

HTTP Response

Arguments

Parameter Type Description
code integer The HTTP Status Code
status string Response status: SUCCESS or FAILED
message string Descriptive response message
data JSON String Details of the transaction. Please take not of the transaction status when working with the response

Filtering Transactions

Example transactions request with filter values

curl "https://app.ugmart.ug/api/transactions?collectionAccount=15B0D8D8BE&currency=UGX" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" 

This endpoint requests a list of transactions, filtered according to the provided parameters. Provide a single or combination of parameters to filter the transactions. The name of the filter field parameter is derived from the camelCase version of the single transaction data fields. For example collection_account becomes collectionAccount, transaction_date becomes transactionDate as described in the parameter table below;

HTTP Request

GET https://app.ugmart.ug/api/transactions?collectionAccount=&paymentProvider=&type=&status=&msisdn=&transactionDate=&minDate=&maxDate=&currency=&amount=&minAmount=&maxAmount=&sort=&direction=&page=&limit=

URL Parameters

Parameter Type Description
collectionAccount string Collection Account code. Filter only the transactions under the collection account.
paymentProvider string Payment provider code. Filter only the transactions processed by the payment provider. Examples are airtel_money, mtn_mobile_money
type string Transaction Type. Filter only the transactions of a given type. Values can be COLLECTION, PAYOUT, CASH_WITHDRAW, ADMIN_FUNDS_DEPOSIT or ADJUSTMENT, WALLET_REFUND
msisdn string The phone number used in the transaction. Filter only the transactions done by that number. Values should be of the format 256*** for example 256777123456
transactionDate string The transaction date. Filter only the transactions processed on this date. Values should be of the format YYYY-MM-DD for example 2017-11-30
minDate string The lower limit of the transaction date. Filter only the transactions processed on and after this date. Values should be of the format YYYY-MM-DD for example 2017-11-30
maxDate string The upper limit of the transaction date. Filter only the transactions processed on and before this date. Values should be of the format YYYY-MM-DD for example 2017-11-30
currency string The transaction currency. Filter only the transactions processed in this currency. Values can be UGX, USD
amount integer Transaction amount. Filter only the transactions where the amount is this amount.
minAmount integer Lower limit of the transaction amount. Filter only the transactions where the amount is greater than or equal to this amount.
maxAmount integer Upper limit of the transaction amount. Filter only the transactions where the amount is less than or equal to this amount.
status string Transaction status. Filter only the transactions of the given status. Values can be COMPLETE, FAILED, PENDING, CANCELLED, AWAIT_REFUND or INCOMPLETE
sort string Field name to sort/order by. Values can be transactionDate, amount or charge. Default sort field is transactionDate
direction string The sort direction. Values can be ASC or DESC. Default sort direction is DESC
page integer The page number to be requested. This is used in pagination. Default page is 1
limit integer This value determines how many records should be returned. Default limit value is 20

Example success response:

{
    "currentPage": 1,
    "itemsPerPage": 20,
    "totalItems": 100,
    "data": [
        {
            "transaction_id": "1513319878",
            "collection_account": {
                "account_code": "15B0D8D8BE",
                "account_name": "GBi-Solutions (U) Ltd"
            },
            "payment_provider": {
                "name": "VISA-MasterCard",
                "code": "visa_mastercard"
            },
            "type": "COLLECTION",
            "msisdn": "VISA-MasterCard",
            "currency": "UGX",
            "application": "CallbackTest",
            "description": "Transaction Event Test",
            "amount": 1000,
            "charge": 0,
            "status": "CANCELLED",
            "status_message": "Transaction has been cancelled",
            "transaction_date": "2017-12-15T09:13:39+03:00",
            "completed_on": "2017-12-15T09:15:03+03:00"
        },
        {
            "transaction_id": "1512446532",
            "collection_account": {
                "account_code": "15B0D8D8BE",
                "account_name": "GBi-Solutions (U) Ltd"
            },
            "payment_provider": {
                "name": "VISA-MasterCard",
                "code": "visa_mastercard"
            },
            "type": "COLLECTION",
            "msisdn": "VISA-MasterCard",
            "currency": "UGX",
            "application": "CallbackTest",
            "description": "Transaction Event Test",
            "amount": 1000,
            "charge": 0,
            "status": "FAILED",
            "status_message": "Unexpected parameter 'interaction.operation' (Cause: INVALID_REQUEST).",
            "transaction_date": "2017-12-05T06:17:37+03:00",
            "completed_on": "2017-12-05T06:18:16+03:00"
        }
    ]
}

Example failure response:

{
    "code": 404,
    "status": "FAILED",
    "message": "Collection Account with code '15B0D8D8B' does not exist in your profile"
}

HTTP Response

Arguments

Parameter Type Description
currentPage integer Pagination parameter describing the currently requested page
itemsPerPage integer Pagination parameter describing how many items have been requested for every page. 20 is the default
totalItems integer Pagination parameter describing the total number of results
data JSON String Details of each transaction (for all types of transactions). The status of each transaction at the time of the request is provided in the response

SMS

Single text message

Example SMS send request to a single destination

curl "https://app.ugmart.ug/api/send-sms" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "account_code": "15B0D8D8BE",
      "transaction_id": "auto",
      "to": "256700392138",
      "text": "Test SMS."
    }'

This endpoint allows you to send a single textual message to one destination address/phone number

HTTP Request

POST https://app.ugmart.ug/api/send-sms

Arguments

Parameter Type Required Description
account_code string Required Collection Account code. This can be copied from the dashboard where the account was created
transaction_id string Required A unique generated string to identify request. If the value is “auto”, the API generates this ID on your behalf
to string Required The SMS recipient phone number. The phone number must be in international format for example 256700392138 without the +
text string Required Text of the message that will be sent. The maximum length of one message is 160 characters

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "transaction_id": "SMS1522740604",
    "sms_charge_rate": 30,
    "messages": [
        {
            "to": "256700392138",
            "messageId": "1522806820139",
            "status": {
                "code": 4,
                "name": "SUCCESS",
                "description": "Message Sent"
            }
        }
    ]
}

Example failure response:

{
    "code": 422,
    "status": "FAILED",
    "message": "SMS Credit Purchase failed. Insufficient Balance on your UGX wallet. At least 3,000 is required.",
    "sms_charge_rate": 30
}

HTTP Response

Arguments

Parameter Type Description
code integer The HTTP status code
status string Indicates whether the API request succeeded, failed or is pending
transaction_id string The unique string identifier of the request
sms_charge_rate integer The price (UGX) per SMS sent. This is charged on the collection account defined in the request
messages SMSResponseDetails Array of sent message objects, one object for every message.

SMSResponseDetails

Parameter Type Description
to string The message destination address.
messageId string The ID that uniquely identifies the message sent.
status Status Indicates whether the message is successfully sent, not sent, delivered, not delivered, waiting for delivery or any other possible status.

Status

Parameter Type Description
code integer The status code.
name string The status name.
description string Human-readable description of the status.

Products List

Besides the mobile money and VISA/MasterCard payments, UGMART also provides an API for digital purchase of products. These products are in the categories of AIRTIME, INTERNET, UTILITIES, TV, TAXES and any other category defined by UGMART. When the products list is queried, the response contains the type of every product on the list.

Some products have extra price lists against them e.g. Data Bundles, TV Bouquets while other products are straight forward e.g. Airtime.

Recipient accounts of these products are validated before the purchase/funds transfer is done. Only valid recipient accounts receive the purchased product. Validation returns all the details on the account including balance due (For the case of Utilities, TV and Taxes), account status (For example a TV account can be suspended pending payment of arrears). For the products whose validation returns a balance, the purchase amount should be greater than or equal to this balance for the process to succeed.

Product List Request

Example products list request

curl "https://app.ugmart.ug/api/products" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" 

This endpoint requests for the list of available products for sale. A list of products is returned with all the required details to help with the subsequent requests. This list contains a broader scope of products and for some of the products in the list (those with has_price_list being true), there is need to query that extra price list to get the actual products that are to be purchased.

HTTP Request

GET https://app.ugmart.ug/api/products

Product List Response

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully",
    "data": [
        {
            "name": "Airtel Airtime",
            "type": "AIRTIME",
            "code": "AIRTEL",
            "price": 500,
            "has_price_list": false,
            "available": true,
            "billable": false
        },
        {
            "name": "Vodafone Internet",
            "type": "INTERNET",
            "code": "VodafoneInet.Bundle",
            "price": 1000,
            "has_price_list": true,
            "available": true,
            "billable": false
        },
        {
            "name": "URA",
            "type": "TAXES",
            "code": "URA",
            "price": 500,
            "has_price_list": false,
            "available": true,
            "billable": true
        },
        {
            "name": "DSTV Multichoice",
            "type": "TV",
            "code": "DSTV.Primary",
            "price": 4000,
            "has_price_list": true,
            "available": true,
            "billable": true
        },
        {
            "name": "UMEME Yaka",
            "type": "UTILITIES",
            "code": "UMEME",
            "price": 500,
            "has_price_list": false,
            "available": true,
            "billable": true
        }
    ]
}

The table below describes the parameters returned under the data value. This value contains an array of products with each having the parameters described below

Response Parameters

Parameter Type Description
name string The name of the product. This can be displayed on your client applications for easy navigation
type string The type of the product. Available values are: AIRTIME, INTERNET,TAXES, TV,UTILITIES, OTHERS
code string This is the unique identifier of the product in the list. This value has many purposes including; listing extra price lists, listing purchase choice-lists, customer account validation, product purchase etc
price integer This value represents the allowed minimum amount to be paid for the product
has_price_list boolean This value represents whether or not the product has an extra price list to be queried. The products in that price list are what can actually be purchased and it should be displayed in your client applications for the buyer to select
available boolean Represents whether or not the product is available for purchase
billable boolean Indicates whether or not a tariff is charged for the purchase of the product. If true, the collection account doing the purchase would incur this charge on top of the purchase amount

Product Price List

Price List Request

Example product price list request

curl "https://app.ugmart.ug/api/products?code=DSTV.Primary" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" 

This endpoint requests for the price list of the specified product. If the product from the previous endpoint had its has_price_list value being true, pass the code of that product as a parameter in this request to retrieve the price list. The returned list should be displayed in your client applications so that customers make a selection.

HTTP Request

GET https://app.ugmart.ug/api/products?code={main_product_code}

Price List Response

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully.",
    "data": [
        {
            "code": "DSTV.Primary:ACSSE36",
            "price": 33000,
            "name": "DStv Access Bouquet E36 - 33,000 UGX"
        },
        {
            "code": "DSTV.Primary:COFAME36",
            "price": 60000,
            "name": "DStv Family Bouquet E36 - 60,000 UGX"
        },
        {
            "code": "DSTV.Primary:COMPE36",
            "price": 115000,
            "name": "DStv Compact Bouquet E36 - 115,000 UGX"
        },
        {
            "code": "DSTV.Primary:COMPLE36",
            "price": 180000,
            "name": "DStv Compact Plus Bouquet E36 - 180,000 UGX"
        }
    ]
}

The table below describes the parameters returned under the data value. This value contains an array of products with each having the parameters described below

Parameter Type Description
code string This is the unique identifier of the product in the list. This value will be used during recipient account validation and also at purchase
price integer This value represents the purchase price for the product
name string The name of the product. This can be displayed on your client applications for easy navigation.

Airtime

Phone Number Validation

Example airtime validation request for Airtel Airtime

curl "https://app.ugmart.ug/api/products/validate" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "amount": 1000,
      "msisdn": "0700392138",
      "product_code": "AIRTEL"
    }'

This section describes the validation and purchase procedure regarding AIRTIME products. The validation endpoint requests for the validation of the product recipient account. The API response determines whether or not the recipient account is eligible for the given product.

Validation HTTP Request

POST https://app.ugmart.ug/api/products/validate

Request Parameters

Parameter Type Required Description
amount integer Required The amount to be paid for the product
msisdn string Required The recipient account number
product_code string Required The unique identifier for the product. It can be got from the response of the Products list endpoint

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully.",
    "data": {
        "valid": true,
        "msisdn": "0700392138"
    }
}

HTTP Response

Arguments

Parameter Type Description
valid boolean Whether or not the recipient account is valid for the product
msisdn string The recipient account number
customer_name string In some cases, the name attached to the recipient account is provided in the response

Airtime Purchase

Example airtime purchase request for MTN Airtime

curl "https://app.ugmart.ug/api/products/purchase" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "account_code": "15B0D8D8BE",
      "transaction_id": "auto",
      "amount": 500,
      "msisdn": "0777044237",
      "product_code": "MTN",
      "description": "MTN Airtime"
    }'

The purchase endpoint requests for the funds transfer or purchase of the given product to the given recipient. This purchase is done against the balance of a specified collection account.

Purchase HTTP Request

POST https://app.ugmart.ug/api/products/purchase

Request Parameters

Parameter Type Required Description
account_code string Required Collection Account code. This can be copied from the dashboard where the account was created. The balance on this account is deducted to effect the purchase. By default, the UGX wallet is used for this procedure.
transaction_id string Required A unique generated string to identify request. If the value is “auto”, the API generates this ID on your behalf
amount integer Required The amount to be paid for the product
msisdn string Required The recipient account number
product_code string Required The unique identifier for the product. It can be got from the response of the Products list endpoint
description string Required Description of the purchase. You could use the product name (obtained from the products list endpoint above)

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Purchase completed successfully",
    "data": {
        "transaction_id": "1513647009",
        "msisdn": "0777044237",
        "description": "MTN Airtime",
        "product_type": "AIRTIME",
        "memo": "SUCCESS",
        "provider_transaction_id": 5021238514
    }
}

HTTP Response

Arguments

Parameter Type Description
code integer The HTTP Status Code
status string Response status: SUCCESS or FAILED or INCOMPLETE
message string Descriptive response message
data JSON String Details of the purchase

Data Bundles

Phone Number Validation

Example data bundles validation request for Vodafone Bundles

curl "https://app.ugmart.ug/api/products/validate" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "amount": 1000,
      "msisdn": "0723190253",
      "product_code": "VodafoneInet.Bundle:841"
    }'

This section describes the validation and purchase procedure regarding INTERNET products. The validation endpoint requests for the validation of the product recipient account. The API response determines whether or not the recipient account is eligible for the given product.

Validation HTTP Request

POST https://app.ugmart.ug/api/products/validate

Request Parameters

Parameter Type Required Description
amount integer Required The amount to be paid for the product
msisdn string Required The recipient account number
product_code string Required The unique identifier for the product. It can be got from the response of the Products Price List endpoint

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully.",
    "data": {
        "valid": true,
        "msisdn": "0723190253",
        "customer_name": "FRED TEBANDEKE, ACTIVATED"
    }
}

HTTP Response

Arguments

Parameter Type Description
valid boolean Whether or not the recipient account is valid for the product
msisdn string The recipient account number
customer_name string In some cases, the name attached to the recipient account is provided in the response

Data Bundle Purchase

Example data bundle purchase request for Airtel Bundles

curl "https://app.ugmart.ug/api/products/purchase" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "account_code": "15B0D8D8BE",
      "transaction_id": "auto",
      "amount": 500,
      "msisdn": "0700392138",
      "product_code": "Airtel.Inet:D25MB",
      "description": "1 Day, 25MB - 500 UGX"
    }'

The purchase endpoint requests for the funds transfer or purchase of the given product to the given recipient. This purchase is done against the balance of a specified collection account.

Purchase HTTP Request

POST https://app.ugmart.ug/api/products/purchase

Request Parameters

Parameter Type Required Description
account_code string Required Collection Account code. This can be copied from the dashboard where the account was created. The balance on this account is deducted to effect the purchase. By default, the UGX wallet is used for this procedure.
transaction_id string Required A unique generated string to identify request. If the value is “auto”, the API generates this ID on your behalf
amount integer Required The amount to be paid for the product
msisdn string Required The recipient account number
product_code string Required The unique identifier for the product. It can be got from the response of the Product Price list endpoint
description string Required Description of the purchase. You could use the product name (obtained from the products list endpoint above)

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Purchase completed successfully",
    "data": {
        "transaction_id": "1513854180",
        "msisdn": "0700392138",
        "description": "1 Day, 25MB - 500 UGX",
        "product_type": "INTERNET",
        "memo": "SUCCESS",
        "provider_transaction_id": 5037966027
    }
}

HTTP Response

Arguments

Parameter Type Description
code integer The HTTP Status Code
status string Response status: SUCCESS or FAILED or INCOMPLETE
message string Descriptive response message
data JSON String Details of the purchase

National Water (NWSC)

NWSC Area IDs

Example request for National Water Area IDs

curl "https://app.ugmart.ug/api/products/choice-list?code=NWSC" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" 

The choice list endpoint retrieves the list of NWSC Area IDs. These IDs are necessary for account validation and also for purchase. This list should be displayed in the client applications so that customers choose their areas.

Area ID List HTTP Request

GET https://app.ugmart.ug/api/products/choice-list?code=NWSC

Request Parameters

Parameter Type Required Description
code string Required The National Water Product Code (Obtained from the products list)

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully.",
    "data": [
        {
            "id": "Entebbe",
            "description": "Entebbe",
            "long_label": "Entebbe",
            "short_label": "Entebbe"
        },
        {
            "id": "Iganga",
            "description": "Iganga",
            "long_label": "Iganga",
            "short_label": "Iganga"
        },
        {
            "id": "Jinja",
            "description": "Jinja",
            "long_label": "Jinja",
            "short_label": "Jinja"
        }
    ]
}

HTTP Response

Parameter Type Description
id string The choice ID. This value is what should be passed in the validation request object for NWSC
description string Description of the choice (Can be displayed in the client application interfaces)
long_label string Long label for the choice (Can be displayed in the client application interfaces)
short_label string Short label for the choice (Can be displayed in the client application interfaces)

Customer Validation

Example utilities validation request for National Water

curl "https://app.ugmart.ug/api/products/validate" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "amount": 1000,
      "msisdn": "21169727",
      "product_code": "NWSC",
      "details": {
            "contact_phone": "0777044237",
            "area_id": "Kampala"
        }
    }'

The validation endpoint requests for the validation of the product recipient account. The API response determines whether or not the recipient account is eligible for the given product.

Validation HTTP Request

POST https://app.ugmart.ug/api/products/validate

Request Parameters

Parameter Type Required Description
amount integer Required The amount to be paid for the product
msisdn string Required The recipient account number
product_code string Required The unique identifier for the product. It can be got from the response of the Products List endpoint
contact_phone string Required A valid mobile phone number
area_id string Required The customer area ID obtained from the area ID list above

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully.",
    "data": {
        "valid": true,
        "msisdn": "21169727",
        "customer_name": "KIWANUKA JOSEPH",
        "balance": -529,
        "tariff_charge": 0
    }
}

HTTP Response

Arguments

Parameter Type Description
valid boolean Whether or not the recipient account is valid for the product
msisdn string The recipient account number
customer_name string In some cases, the name attached to the recipient account is provided in the response
balance integer The value represents the arrears on the utility account
tariff_charge integer The value represents the amount that’s to be charged from the collection account balance to facilitate the purchase. It’s charged on top of the product price.

National Water Purchase

Example utility purchase request for National Water

curl "https://app.ugmart.ug/api/products/purchase" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "account_code": "15B0D8D8BE",
      "transaction_id": "auto",
      "amount": 1500,
      "msisdn": "21169727",
      "product_code": "NWSC",
      "description": "National Water",
      "details": {
            "contact_phone": "0777044237",
            "area_id": "Kampala"
        }
    }'

The purchase endpoint requests for the funds transfer or purchase of the given product to the given recipient. This purchase is done against the balance of a specified collection account.

Purchase HTTP Request

POST https://app.ugmart.ug/api/products/purchase

Request Parameters

Parameter Type Required Description
account_code string Required Collection Account code. This can be copied from the dashboard where the account was created. The balance on this account is deducted to effect the purchase. By default, the UGX wallet is used for this procedure.
transaction_id string Required A unique generated string to identify request. If the value is “auto”, the API generates this ID on your behalf
amount integer Required The amount to be paid for the product
msisdn string Required The recipient account number (In this case, the National Water Metre number)
product_code string Required The unique identifier for the product. It can be got from the response of the Product Price list endpoint
description string Required Description of the purchase. You could use the product name (obtained from the products list endpoint above)
contact_phone string Required Mobile Phone Number. Purchase SMS will be sent to this number (In this case, the token and number of units would be sent to this phone number)
area_id string Required The customer area ID obtained from the area ID list above

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Purchase completed successfully",
    "data": {
        "transaction_id": "1513940716",
        "msisdn": "21169727",
        "description": "National Water",
        "product_type": "UTILITIES",
        "memo": "KIWANUKA JOSEPH (Area: Kampala, Receipt: 21202395)",
        "tariff_charge": 0,
        "provider_transaction_id": 5038199359,
        "details": {
            "customer_name": "KIWANUKA JOSEPH",
            "receipt_number": "21202395",
            "description": "KIWANUKA JOSEPH 21169727 Kampala",
            "area_id":"Kampala"
        }
    }
}

HTTP Response

Arguments

Parameter Type Description
code integer The HTTP Status Code
status string Response status: SUCCESS or FAILED or INCOMPLETE
message string Descriptive response message
data JSON String Details of the purchase

UMEME Yaka

Customer Meter Validation

Example utilities validation request for UMEME Yaka

curl "https://app.ugmart.ug/api/products/validate" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "amount": 1500,
      "msisdn": "04230640783",
      "product_code": "UMEME",
      "details": {
            "contact_phone": "0777044237"
        }
    }'

The validation endpoint requests for the validation of the product recipient account. The API response determines whether or not the recipient account is eligible for the given product.

Validation HTTP Request

POST https://app.ugmart.ug/api/products/validate

Request Parameters

Parameter Type Required Description
amount integer Required The amount to be paid for the product
msisdn string Required The recipient account number
product_code string Required The unique identifier for the product. It can be got from the response of the Products List endpoint
contact_phone string Required A valid mobile phone number

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully.",
    "data": {
        "valid": true,
        "msisdn": "04230640783",
        "customer_name": "SAM BUSULWA",
        "balance": 587,
        "tariff_charge": 0
    }
}

HTTP Response

Arguments

Parameter Type Description
valid boolean Whether or not the recipient account is valid for the product
msisdn string The recipient account number
customer_name string In some cases, the name attached to the recipient account is provided in the response
balance integer The value represents the arrears on the utility account
tariff_charge integer The value represents the amount that’s to be charged from the collection account balance to facilitate the purchase. It’s charged on top of the product price.

UMEME Yaka Purchase

Example utility purchase request for UMEME Yaka

curl "https://app.ugmart.ug/api/products/purchase" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "account_code": "15B0D8D8BE",
      "transaction_id": "auto",
      "amount": 1500,
      "msisdn": "04230640783",
      "product_code": "UMEME",
      "description": "UMEME Yaka",
      "details": {
            "contact_phone": "0777044237"
        }
    }'

The purchase endpoint requests for the funds transfer or purchase of the given product to the given recipient. This purchase is done against the balance of a specified collection account.

Purchase HTTP Request

POST https://app.ugmart.ug/api/products/purchase

Request Parameters

Parameter Type Required Description
account_code string Required Collection Account code. This can be copied from the dashboard where the account was created. The balance on this account is deducted to effect the purchase. By default, the UGX wallet is used for this procedure.
transaction_id string Required A unique generated string to identify request. If the value is “auto”, the API generates this ID on your behalf
amount integer Required The amount to be paid for the product
msisdn string Required The recipient account number (In this case, the UMEME Yaka Metre number)
product_code string Required The unique identifier for the product. It can be got from the response of the Product Price list endpoint
description string Required Description of the purchase. You could use the product name (obtained from the products list endpoint above)
contact_phone string Required Mobile Phone Number. Purchase SMS will be sent to this number (In this case, the token and number of units would be sent to this phone number)

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Purchase completed successfully",
    "data": {
        "transaction_id": "1513940716",
        "msisdn": "04230640783",
        "description": "UMEME Yaka",
        "product_type": "UTILITIES",
        "memo": "SAM BUSULWA : 4433 2904 5279 0983 7607 (1.9 Units, DebtRecovery: 0)",
        "tariff_charge": 0,
        "provider_transaction_id": 5038199359,
        "details": {
            "customer_name": "SAM BUSULWA",
            "receipt_number": "779700869",
            "token": "4433 2904 5279 0983 7607",
            "token_value": "1292.15",
            "units": 1.9,
            "debt_recovery": 0,
            "description": "1.9 KWh at UGX 685.60 per KWh"
        }
    }
}

HTTP Response

Arguments

Parameter Type Description
code integer The HTTP Status Code
status string Response status: SUCCESS or FAILED or INCOMPLETE
message string Descriptive response message
data JSON String Details of the purchase

Pay TV

StarTimes/StarSat

Example validation request for StarTimes/StarSat

curl "https://app.ugmart.ug/api/products/validate" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "amount": 2000,
      "msisdn": "02036620039",
      "product_code": "STARTIMES",
      "details": {
            "contact_phone": "0777044237"
        }
    }'

The validation endpoint requests for the validation of the product recipient account. The API response determines whether or not the recipient account is eligible for the given product.

The purchase endpoint requests for the funds transfer or purchase of the given product to the given recipient. This purchase is done against the balance of a specified collection account.

Validation HTTP Request

POST https://app.ugmart.ug/api/products/validate

Request Parameters

Parameter Type Required Description
amount integer Required The amount to be paid for the product
msisdn string Required The recipient account number (The Startimes customer smart card number)
product_code string Required The unique identifier for the product. It can be got from the response of the Products List endpoint
contact_phone string Required A valid mobile phone number

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully.",
    "data": {
        "valid": true,
        "msisdn": "02036620039",
        "customer_name": "NASSIWA OLIVIA",
        "tariff_charge": 0
    }
}

HTTP Response

Arguments

Parameter Type Description
valid boolean Whether or not the recipient account is valid for the product
msisdn string The recipient account number
customer_name string The name attached to the recipient account
tariff_charge integer The value represents the amount that’s to be charged from the collection account balance to facilitate the purchase. It’s charged on top of the product price.

Example purchase request for StarTimes/StarSat

curl "https://app.ugmart.ug/api/products/purchase" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "account_code": "15B0D8D8BE",
      "transaction_id": "auto",
      "amount": 1500,
      "msisdn": "02036620039",
      "product_code": "STARTIMES",
      "description": "StarTimes/StarSat",
      "details": {
            "contact_phone": "0777044237"
        }
    }'

Purchase HTTP Request

POST https://app.ugmart.ug/api/products/purchase

Request Parameters

Parameter Type Required Description
account_code string Required Collection Account code. This can be copied from the dashboard where the account was created. The balance on this account is deducted to effect the purchase. By default, the UGX wallet is used for this procedure.
transaction_id string Required A unique generated string to identify request. If the value is “auto”, the API generates this ID on your behalf
amount integer Required The amount to be paid for the product
msisdn string Required The recipient account number (The StarTimes smart card number)
product_code string Required The unique identifier for the product. It can be got from the response of the Product Price list endpoint
description string Required Description of the purchase. You could use the product name (obtained from the products list endpoint above)
contact_phone string Required Mobile Phone Number. Purchase SMS will be sent to this number

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Purchase completed successfully",
    "data": {
        "transaction_id": "1513940716",
        "msisdn": "02036620039",
        "description": "StarTimes/StarSat",
        "product_type": "TV",
        "memo": "Account Number 02036620039 topped up successfully : NASSIWA OLIVIA",
        "tariff_charge": 0,
        "provider_transaction_id": 5038199359,
        "details": {
            "customer_name": "NASSIWA OLIVIA"
        }
    }
}

HTTP Response

Arguments

Parameter Type Description
code integer The HTTP Status Code
status string Response status: SUCCESS or FAILED or INCOMPLETE
message string Descriptive response message
data JSON String Details of the purchase

Simba TV

Example validation request for Simba TV

curl "https://app.ugmart.ug/api/products/validate" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "amount": 2000,
      "msisdn": "4023",
      "product_code": "TVNXT",
      "details": {
            "contact_phone": "0777044237"
        }
    }'

The validation endpoint requests for the validation of the product recipient account. The API response determines whether or not the recipient account is eligible for the given product.

The purchase endpoint requests for the funds transfer or purchase of the given product to the given recipient. This purchase is done against the balance of a specified collection account.

Validation HTTP Request

POST https://app.ugmart.ug/api/products/validate

Request Parameters

Parameter Type Required Description
amount integer Required The amount to be paid for the product
msisdn string Required The recipient account number (The SIMBA TV customer number)
product_code string Required The unique identifier for the product. It can be got from the response of the Products List endpoint
contact_phone string Required A valid mobile phone number

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully.",
    "data": {
        "valid": true,
        "msisdn": "4023",
        "customer_name": "MUKASA MOSES",
        "tariff_charge": 0
    }
}

HTTP Response

Arguments

Parameter Type Description
valid boolean Whether or not the recipient account is valid for the product
msisdn string The recipient account number
customer_name string The name attached to the recipient account
tariff_charge integer The value represents the amount that’s to be charged from the collection account balance to facilitate the purchase. It’s charged on top of the product price.

Example purchase request for SIMBA TV

curl "https://app.ugmart.ug/api/products/purchase" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "account_code": "15B0D8D8BE",
      "transaction_id": "auto",
      "amount": 2000,
      "msisdn": "4023",
      "product_code": "TVNXT",
      "description": "SIMBA TV",
      "details": {
            "contact_phone": "0777044237"
        }
    }'

Purchase HTTP Request

POST https://app.ugmart.ug/api/products/purchase

Request Parameters

Parameter Type Required Description
account_code string Required Collection Account code. This can be copied from the dashboard where the account was created. The balance on this account is deducted to effect the purchase. By default, the UGX wallet is used for this procedure.
transaction_id string Required A unique generated string to identify request. If the value is “auto”, the API generates this ID on your behalf
amount integer Required The amount to be paid for the product
msisdn string Required The recipient account number (The SIMBA TV customer number)
product_code string Required The unique identifier for the product. It can be got from the response of the Products list endpoint
description string Required Description of the purchase. You could use the product name (obtained from the products list endpoint above)
contact_phone string Required Mobile Phone Number. Purchase SMS will be sent to this number

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Purchase completed successfully",
    "data": {
        "transaction_id": "1513940716",
        "msisdn": "4023",
        "description": "SIMBA TV",
        "product_type": "TV",
        "memo": "Account Number 4023 topped up successfully : MUKASA MOSES",
        "tariff_charge": 0,
        "provider_transaction_id": 5038199359,
        "details": {
            "customer_name": "MUKASA MOSES"
        }
    }
}

HTTP Response

Arguments

Parameter Type Description
code integer The HTTP Status Code
status string Response status: SUCCESS or FAILED or INCOMPLETE
message string Descriptive response message
data JSON String Details of the purchase

Zuku TV Default Bucket and Free To Air

Example validation request for Zuku TV Default Bucket

curl "https://app.ugmart.ug/api/products/validate" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "amount": 2000,
      "msisdn": "513472",
      "product_code": "DPB",
      "details": {
            "contact_phone": "0777044237"
        }
    }'

The validation endpoint requests for the validation of the product recipient account. The API response determines whether or not the recipient account is eligible for the given product.

The purchase endpoint requests for the funds transfer or purchase of the given product to the given recipient. This purchase is done against the balance of a specified collection account.

Validation HTTP Request

POST https://app.ugmart.ug/api/products/validate

Request Parameters

Parameter Type Required Description
amount integer Required The amount to be paid for the product
msisdn string Required The recipient account number (The Zuku TV customer number)
product_code string Required The unique identifier for the product. It can be got from the response of the Products List endpoint
contact_phone string Required A valid mobile phone number

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully.",
    "data": {
        "valid": true,
        "msisdn": "513472",
        "tariff_charge": 0
    }
}

HTTP Response

Arguments

Parameter Type Description
valid boolean Whether or not the recipient account is valid for the product
msisdn string The recipient account number
tariff_charge integer The value represents the amount that’s to be charged from the collection account balance to facilitate the purchase. It’s charged on top of the product price.

Example purchase request for Zuku TV Free To Air

curl "https://app.ugmart.ug/api/products/purchase" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "account_code": "15B0D8D8BE",
      "transaction_id": "auto",
      "amount": 2000,
      "msisdn": "513472",
      "product_code": "FTA",
      "description": "Zuku TV Free To Air",
      "details": {
            "contact_phone": "0777044237"
        }
    }'

Purchase HTTP Request

POST https://app.ugmart.ug/api/products/purchase

Request Parameters

Parameter Type Required Description
account_code string Required Collection Account code. This can be copied from the dashboard where the account was created. The balance on this account is deducted to effect the purchase. By default, the UGX wallet is used for this procedure.
transaction_id string Required A unique generated string to identify request. If the value is “auto”, the API generates this ID on your behalf
amount integer Required The amount to be paid for the product
msisdn string Required The recipient account number (The Zuku TV customer number)
product_code string Required The unique identifier for the product. It can be got from the response of the Products list endpoint
description string Required Description of the purchase. You could use the product name (obtained from the products list endpoint above)
contact_phone string Required Mobile Phone Number. Purchase SMS will be sent to this number

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Purchase completed successfully",
    "data": {
        "transaction_id": "1513940716",
        "msisdn": "513472",
        "description": "Zuku TV Free To Air",
        "product_type": "TV",
        "memo": "Account Number 513472 topped up successfully",
        "tariff_charge": 0,
        "provider_transaction_id": 5038199359
    }
}

HTTP Response

Arguments

Parameter Type Description
code integer The HTTP Status Code
status string Response status: SUCCESS or FAILED or INCOMPLETE
message string Descriptive response message
data JSON String Details of the purchase

AZAM Media

Example validation request for Azam Pure Bouquet

curl "https://app.ugmart.ug/api/products/validate" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "amount": 10000,
      "msisdn": "212911665676",
      "product_code": "Azam:APURE",
      "details": {
            "contact_phone": "0777044237"
        }
    }'

The validation endpoint requests for the validation of the product recipient account. The API response determines whether or not the recipient account is eligible for the given product.

The purchase endpoint requests for the funds transfer or purchase of the given product to the given recipient. This purchase is done against the balance of a specified collection account.

Validation HTTP Request

POST https://app.ugmart.ug/api/products/validate

Request Parameters

Parameter Type Required Description
amount integer Required The amount to be paid for the product
msisdn string Required The recipient account number (The Zuku TV customer number)
product_code string Required The unique identifier for the product. It can be got from the response of the Product Price List endpoint
contact_phone string Required A valid mobile phone number

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully.",
    "data": {
        "valid": true,
        "msisdn": "212911665676",
        "customer_name": "BRIDGET KOMUHANGI",
        "tariff_charge": 0
    }
}

HTTP Response

Arguments

Parameter Type Description
valid boolean Whether or not the recipient account is valid for the product
msisdn string The recipient account number
tariff_charge integer The value represents the amount that’s to be charged from the collection account balance to facilitate the purchase. It’s charged on top of the product price.

Example purchase request for Azam Pure Bouquet

curl "https://app.ugmart.ug/api/products/purchase" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "account_code": "15B0D8D8BE",
      "transaction_id": "auto",
      "amount": 10000,
      "msisdn": "212911665676",
      "product_code": "Azam:APURE",
      "description": "Azam Pure",
      "details": {
            "contact_phone": "0777044237"
        }
    }'

Purchase HTTP Request

POST https://app.ugmart.ug/api/products/purchase

Request Parameters

Parameter Type Required Description
account_code string Required Collection Account code. This can be copied from the dashboard where the account was created. The balance on this account is deducted to effect the purchase. By default, the UGX wallet is used for this procedure.
transaction_id string Required A unique generated string to identify request. If the value is “auto”, the API generates this ID on your behalf
amount integer Required The amount to be paid for the product
msisdn string Required The recipient account number (The Zuku TV customer number)
product_code string Required The unique identifier for the product. It can be got from the response of the Product Price list endpoint
description string Required Description of the purchase. You could use the product name (obtained from the products list endpoint above)
contact_phone string Required Mobile Phone Number. Purchase SMS will be sent to this number

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Purchase completed successfully",
    "data": {
        "transaction_id": "1513940716",
        "msisdn": "212911665676",
        "description": "Azam Pure",
        "product_type": "TV",
        "memo": "Account Number 212911665676 topped up successfully : BRIDGET KOMUHANGI",
        "tariff_charge": 0,
        "provider_transaction_id": 5038199359,
        "details": {
            "customer_name": "BRIDGET KOMUHANGI"
        }
    }
}

HTTP Response

Arguments

Parameter Type Description
code integer The HTTP Status Code
status string Response status: SUCCESS or FAILED or INCOMPLETE
message string Descriptive response message
data JSON String Details of the purchase

GOtv

Select Purchase Mode

Example choice list request for GOtv

curl "https://app.ugmart.ug/api/products/choice-list?code=GOtv" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" 

The choice list endpoint retrieves the list of GOtv purchase modes i.e. whether to pay for a full bouquet or topup an existing one

Choice-list HTTP Request

GET https://app.ugmart.ug/api/products/choice-list?code=GOtv

Request Parameters

Parameter Type Required Description
code string Required The unique product code. This is obtained from the products list

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully.",
    "data": [
        {
            "id": "Bouquet",
            "description": "You will be prompted to choose a GOTV bouquet",
            "long_label": "Bouquet",
            "short_label": "Bouquet"
        },
        {
            "id": "TopUp",
            "description": "The funds will be transferred to top up your bouquet",
            "long_label": "TopUp",
            "short_label": "TopUp"
        }
    ]
}

HTTP Response

Arguments

Parameter Type Description
id string The choice ID. This value is what should be passed in the validation and purchase request objects as purchase_mode
description string Description of the choice (Can be displayed in the client application interfaces)
long_label string Long label for the choice (Can be displayed in the client application interfaces)
short_label string Short label for the choice (Can be displayed in the client application interfaces)

Customer Account Validation

Example validation request for GOtv (TopUp option)

curl "https://app.ugmart.ug/api/products/validate" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "amount": 10000,
      "msisdn": "2022750158",
      "product_code": "GOtv",
      "details": {
            "contact_phone": "0777044237",
            "purchase_mode": "TopUp"
        }
    }'

The validation endpoint requests for the validation of the product recipient account. The API response determines whether or not the recipient account is eligible for the given product.

Validation HTTP Request

POST https://app.ugmart.ug/api/products/validate

Request Parameters

Parameter Type Required Description
amount integer Required The amount to be paid for the product
msisdn string Required The recipient account number (The GOtv customer number)
product_code string Required The unique identifier for the product. It can be got from the response of the Product Price List endpoint
contact_phone string Required A valid mobile phone number

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully.",
    "data": {
        "valid": true,
        "msisdn": "2022750158",
        "customer_name": "NAKAWEESI K",
        "tariff_charge": 0
    }
}

HTTP Response

Arguments

Parameter Type Description
valid boolean Whether or not the recipient account is valid for the product
msisdn string The recipient account number
tariff_charge integer The value represents the amount that’s to be charged from the collection account balance to facilitate the purchase. It’s charged on top of the product price.

TopUp Mode

Example purchase request for GOtv (TopUp)

curl "https://app.ugmart.ug/api/products/purchase" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "account_code": "15B0D8D8BE",
      "transaction_id": "auto",
      "amount": 10000,
      "msisdn": "2022750158",
      "product_code": "GOtv",
      "description": "GOtv",
      "details": {
            "contact_phone": "0777044237",
            "purchase_mode": "TopUp"
        }
    }'

Purchase HTTP Request

POST https://app.ugmart.ug/api/products/purchase

Request Parameters

Parameter Type Required Description
account_code string Required Collection Account code. This can be copied from the dashboard where the account was created. The balance on this account is deducted to effect the purchase. By default, the UGX wallet is used for this procedure.
transaction_id string Required A unique generated string to identify request. If the value is “auto”, the API generates this ID on your behalf
amount integer Required The amount to be paid for the product
msisdn string Required The recipient account number (The GOtv customer number)
product_code string Required The unique identifier for the product. It can be got from the response of the Product Price list endpoint
description string Required Description of the purchase. You could use the product name (obtained from the products list endpoint above)
contact_phone string Required Mobile Phone Number. Purchase SMS will be sent to this number
purchase_mode string Required The choice of purchase for the TV subscription

Example success response for GOtv TopUp:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Purchase completed successfully",
    "data": {
        "transaction_id": "1513940716",
        "msisdn": "2022750158",
        "description": "GOtv",
        "product_type": "TV",
        "memo": "Account Number 2022750158 topped up successfully : NAKAWEESI K",
        "tariff_charge": 0,
        "provider_transaction_id": 5038199359,
        "details": {
            "customer_name": "NAKAWEESI K"
        }
    }
}

HTTP Response

Arguments

Parameter Type Description
code integer The HTTP Status Code
status string Response status: SUCCESS or FAILED or INCOMPLETE
message string Descriptive response message
data JSON String Details of the purchase

Bouquet Mode (Choose bouquet)

Example bouquet list request for GOtv

curl "https://app.ugmart.ug/api/products?code=GOtv" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" 

This endpoint retrieves the list of GOtv bouquets available for subscription; as described in the the products price list endpoint above. The returned list is displayed to the users so that they choose the bouquet of their choice

Bouquet list HTTP Request

GET https://app.ugmart.ug/api/products?code=GOtv

Request Parameters

Parameter Type Required Description
code string Required The unique product code. This is obtained from the products list

Example success response for GOtv bouquet list:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully.",
    "data": [
        {
            "code": "GOtv:GOTV",
            "price": 16000,
            "name": "GOtv Value - 16,000 UGX"
        },
        {
            "code": "GOtv:GOTVPLS",
            "price": 26000,
            "name": "GOtv Plus Bouquet - 26,000 UGX"
        },
        {
            "code": "GOtv:GOLITE",
            "price": 22000,
            "name": "GOtv Lite Bouquet - 22,000 UGX"
        },
        {
            "code": "GOtv:GOLTANL",
            "price": 60000,
            "name": "GOtv Lite 12 - 60,000 UGX"
        },
        {
            "code": "GOtv:GOTVMAX",
            "price": 49000,
            "name": "GOtv Max - 49,000 UGX"
        },
        {
            "code": "GOtv:GOHAN",
            "price": 9500,
            "name": "GOtv Lite IP1 - 9,500 UGX"
        }
    ]
}

HTTP Response

Description of the response parameters

The table below describes the parameters returned under the data value. This value contains an array of of the available bouquets with each having the parameters described below

Parameter Type Description
code string This is the unique identifier of the bouquet in the list. This value will be used during recipient account validation and also at purchase
price integer This value represents the purchase price for the bouquet
name string The name of the bouquet. This can be displayed on your client applications for easy navigation.

Subscription Period

Example subscription period request

curl "https://app.ugmart.ug/api/products/secondary-price-list?id=GOtv.Period&primary=GOtv" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}"  

For bouquet purchase, a subscription period should be selected to determine the period of time the client wishes to pay for. This endpoint retrieves the list of available periods and their respective prices. These subscription periods depend on the selected bouquet as described below;

Bouquet Code List ID
GOtv:GOLITE GOtv.Period2
GOtv:GOHAN GOtv.Period3
All the rest GOtv.Period

Subscription Period HTTP Request

GET https://app.ugmart.ug/api/products/secondary-price-list?id=&primary=

Request Parameters

Parameter Type Required Description
id string Required The list ID to be queried. The ID to use is depends on the selected bouquet as described above
primary string Required The primary/main product code, obtained from the products list. In this case, GOtv

Example success response for GOtv subscription period:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully.",
    "data": [
        {
            "code": "GOtv.Period:1",
            "price": 1,
            "name": "1 Month"
        },
        {
            "code": "GOtv.Period:2",
            "price": 2,
            "name": "2 Months"
        },
        {
            "code": "GOtv.Period:3",
            "price": 3,
            "name": "3 Months"
        },
        {
            "code": "GOtv.Period:4",
            "price": 4,
            "name": "4 Months"
        },
        {
            "code": "GOtv.Period:5",
            "price": 5,
            "name": "5 Months"
        },
        {
            "code": "GOtv.Period:6",
            "price": 6,
            "name": "6 Months"
        },
        {
            "code": "GOtv.Period:7",
            "price": 7,
            "name": "7 Months"
        },
        {
            "code": "GOtv.Period:8",
            "price": 8,
            "name": "8 Months"
        },
        {
            "code": "GOtv.Period:9",
            "price": 9,
            "name": "9 Months"
        },
        {
            "code": "GOtv.Period:10",
            "price": 10,
            "name": "10 Months"
        },
        {
            "code": "GOtv.Period:11",
            "price": 11,
            "name": "11 Months"
        }
    ]
}

HTTP Response

Description of the response parameters

The table below describes the parameters returned under the data value. This value contains an array of of the available subscription periods with each having the parameters described below

Parameter Type Description
code string This is the unique identifier of the period in the list. This value will be used during purchase
price integer This value represents the purchase price for the period
name string The name of the subscription period. This can be displayed on your client applications for easy navigation.

GOtv bouquet purchase

Example purchase request for GOtv (Bouquet)

curl "https://app.ugmart.ug/api/products/purchase" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "account_code": "15B0D8D8BE",
      "transaction_id": "auto",
      "amount": 22000,
      "msisdn": "2022750158",
      "product_code": "GOtv:GOLITE",
      "description": "GOtv Lite Bouquet - 22,000 UGX",
      "details": {
            "contact_phone": "0777044237",
            "purchase_mode": "Bouquet",
            "period": "GOtv.Period:1"
        }
    }'

Purchase HTTP Request

POST https://app.ugmart.ug/api/products/purchase

Request Parameters

Parameter Type Required Description
account_code string Required Collection Account code. This can be copied from the dashboard where the account was created. The balance on this account is deducted to effect the purchase. By default, the UGX wallet is used for this procedure.
transaction_id string Required A unique generated string to identify request. If the value is “auto”, the API generates this ID on your behalf
amount integer Required The amount to be paid for the product. In this case, it’s the bouquet price multiplied by the price of the subscription period
msisdn string Required The recipient account number (The GOtv customer number)
product_code string Required The unique identifier for the product. It can be got from the response of the Product Price list endpoint
description string Required Description of the purchase. You could use the product name (obtained from the products list endpoint above)
contact_phone string Required Mobile Phone Number. Purchase SMS will be sent to this number
purchase_mode string Required The choice of purchase for the TV subscription
period string Required The subscription period code. This is obtained from the secondary price list as described above

Example success response for GOtv Bouquet subscription:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Purchase completed successfully",
    "data": {
        "transaction_id": "1513940716",
        "msisdn": "2022750158",
        "description": "GOtv",
        "product_type": "TV",
        "memo": "Account Number 2022750158 topped up successfully : NAKAWEESI K",
        "tariff_charge": 0,
        "provider_transaction_id": 5038199359,
        "details": {
            "customer_name": "NAKAWEESI K"
        }
    }
}

HTTP Response

Arguments

Parameter Type Description
code integer The HTTP Status Code
status string Response status: SUCCESS or FAILED or INCOMPLETE
message string Descriptive response message
data JSON String Details of the purchase

DSTV Multichoice

Select Purchase Mode

Example choice list request for DSTV

curl "https://app.ugmart.ug/api/products/choice-list?code=DSTV.Primary" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" 

The choice list endpoint retrieves the list of DSTV purchase modes i.e. whether to pay for a full bouquet or topup an existing one

Choice-list HTTP Request

GET https://app.ugmart.ug/api/products/choice-list?code=DSTV.Primary

Request Parameters

Parameter Type Required Description
code string Required The unique product code. This is obtained from the products list

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully.",
    "data": [
        {
            "id": "Bouquet",
            "description": "You will be prompted to choose a DSTV bouquet, and optionally you can select a secondary DSTV product: Dual View, HD PVR or SD PVR. Additionally you will be prompted to specify the subscription period.",
            "long_label": "I wish to specify the bouquet",
            "short_label": "Bouquet"
        },
        {
            "id": "TopUp",
            "description": "You will be prompted to select a DStv bouquet. The funds will be transferred to top up your bouquet.",
            "long_label": "I wish to top up an existing bouquet",
            "short_label": "TopUp"
        }
    ]
}

HTTP Response

Arguments

Parameter Type Description
id string The choice ID. This value is what should be passed in the validation and purchase request objects as purchase_mode
description string Description of the choice (Can be displayed in the client application interfaces)
long_label string Long label for the choice (Can be displayed in the client application interfaces)
short_label string Short label for the choice (Can be displayed in the client application interfaces)

Customer Account Validation

Example validation request for DSTV (TopUp option)

curl "https://app.ugmart.ug/api/products/validate" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "amount": 10000,
      "msisdn": "1025628563",
      "product_code": "DSTV.Primary",
      "details": {
            "contact_phone": "0777044237",
            "purchase_mode": "TopUp"
        }
    }'

The validation endpoint requests for the validation of the product recipient account. The API response determines whether or not the recipient account is eligible for the given product.

Validation HTTP Request

POST https://app.ugmart.ug/api/products/validate

Request Parameters

Parameter Type Required Description
amount integer Required The amount to be paid for the product
msisdn string Required The recipient account number (The DSTV customer number)
product_code string Required The unique identifier for the product. It can be got from the response of the Product Price List endpoint
contact_phone string Required A valid mobile phone number

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully.",
    "data": {
        "valid": true,
        "msisdn": "1025628563",
        "customer_name": "LAWRENCE B, DUE: 172500 UGX / 11-APR-2018",
        "due_amount": 172500,
        "due_date": "11-Apr-2018",
        "tariff_charge": 0
    }
}

HTTP Response

Arguments

Parameter Type Description
valid boolean Whether or not the recipient account is valid for the product
msisdn string The recipient account number
tariff_charge integer The value represents the amount that’s to be charged from the collection account balance to facilitate the purchase. It’s charged on top of the product price.

TopUp Mode

Example purchase request for DSTV (TopUp)

curl "https://app.ugmart.ug/api/products/purchase" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "account_code": "15B0D8D8BE",
      "transaction_id": "auto",
      "amount": 10000,
      "msisdn": "1025628563",
      "product_code": "DSTV.Primary",
      "description": "DSTV Multichoice",
      "details": {
            "contact_phone": "0777044237",
            "purchase_mode": "TopUp"
        }
    }'

Purchase HTTP Request

POST https://app.ugmart.ug/api/products/purchase

Request Parameters

Parameter Type Required Description
account_code string Required Collection Account code. This can be copied from the dashboard where the account was created. The balance on this account is deducted to effect the purchase. By default, the UGX wallet is used for this procedure.
transaction_id string Required A unique generated string to identify request. If the value is “auto”, the API generates this ID on your behalf
amount integer Required The amount to be paid for the product
msisdn string Required The recipient account number (The DSTV customer number)
product_code string Required The unique identifier for the product. It can be got from the response of the Product Price list endpoint
description string Required Description of the purchase. You could use the product name (obtained from the products list endpoint above)
contact_phone string Required Mobile Phone Number. Purchase SMS will be sent to this number
purchase_mode string Required The choice of purchase for the TV subscription

Example success response for DSTV TopUp:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Purchase completed successfully",
    "data": {
        "transaction_id": "1513940716",
        "msisdn": "1025628563",
        "description": "DSTV Multichoice",
        "product_type": "TV",
        "memo": "Account Number 1025628563 topped up successfully : LAWRENCE B",
        "tariff_charge": 0,
        "provider_transaction_id": 5038199359,
        "details": {
            "customer_name": "LAWRENCE B, DUE: 172500 UGX / 11-APR-2018"
        }
    }
}

HTTP Response

Arguments

Parameter Type Description
code integer The HTTP Status Code
status string Response status: SUCCESS or FAILED or INCOMPLETE
message string Descriptive response message
data JSON String Details of the purchase

Bouquet Mode (Choose bouquet)

Example bouquet list request for DSTV

curl "https://app.ugmart.ug/api/products?code=DSTV.Primary" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" 

This endpoint retrieves the list of DSTV bouquets available for subscription; as described in the the products price list endpoint above. The returned list is displayed to the users so that they choose the bouquet of their choice

Bouquet list HTTP Request

GET https://app.ugmart.ug/api/products?code=DSTV.Primary

Request Parameters

Parameter Type Required Description
code string Required The unique product code. This is obtained from the products list

Example success response for DSTV bouquet list:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully.",
    "data": [
        {
            "code": "DSTV.Primary:ACSSE36",
            "price": 33000,
            "name": "DStv Access Bouquet E36 - 33,000 UGX"
        },
        {
            "code": "DSTV.Primary:COFAME36",
            "price": 60000,
            "name": "DStv Family Bouquet E36 - 60,000 UGX"
        },
        {
            "code": "DSTV.Primary:COMPE36",
            "price": 115000,
            "name": "DStv Compact Bouquet E36 - 115,000 UGX"
        },
        {
            "code": "DSTV.Primary:COMPLE36",
            "price": 180000,
            "name": "DStv Compact Plus Bouquet E36 - 180,000 UGX"
        },
        {
            "code": "DSTV.Primary:PREE36",
            "price": 280000,
            "name": "DStv Premium E/Afr E36 - 280,000 UGX"
        },
        {
            "code": "DSTV.Primary:PREASIE36",
            "price": 298000,
            "name": "DStv Premium E/Afr + Asian Bouquet E36 - 298,000 UGX"
        },
        {
            "code": "DSTV.Primary:ASIAE36",
            "price": 128000,
            "name": "DStv Asian Bouquet E36 - 128,000 UGX"
        },
        {
            "code": "DSTV.Primary:GWALLW7",
            "price": 24375,
            "name": "DStv Great Wall Standalone I - 24,375 UGX"
        }
    ]
}

HTTP Response

Description of the response parameters

The table below describes the parameters returned under the data value. This value contains an array of of the available bouquets with each having the parameters described below

Parameter Type Description
code string This is the unique identifier of the bouquet in the list. This value will be used during recipient account validation and also at purchase
price integer This value represents the purchase price for the bouquet
name string The name of the bouquet. This can be displayed on your client applications for easy navigation.

Secondary DSTV Feature

Example choice list request for the secondary DSTV feature

curl "https://app.ugmart.ug/api/products/choice-list?code=DSTV.Primary&type=features" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" 

During the purchase of a DSTV bouquet, the client can optionally select a secondary DSTV product: Dual View, HD PVR or SD PVR. This endpoint returns the list for the client to make the decision whether or not they would like to pay for the secondary product (Dual View, HD PVR or SD PVR)

Choice-list HTTP Request

GET https://app.ugmart.ug/api/products/choice-list?code=DSTV.Primary&type=features

Request Parameters

Parameter Type Required Description
code string Required The unique product code. This is obtained from the products list
type string Required The choice list type to be retrieved. In this case, features is passed as the value

Example success response:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully.",
    "data": [
        {
            "id": "Yes",
            "description": "You will be prompted to specify secondary DSTV product to include in the payment.",
            "long_label": "Yes, I do",
            "short_label": "Yes"
        },
        {
            "id": "No",
            "description": "No secondary DSTV product selection will be prompted and included in the payment.",
            "long_label": "No, I don't",
            "short_label": "No"
        }
    ]
}

HTTP Response

Arguments

Parameter Type Description
id string The choice ID. This value is what should be passed in the validation and purchase request objects as feature
description string Description of the choice (Can be displayed in the client application interfaces)
long_label string Long label for the choice (Can be displayed in the client application interfaces)
short_label string Short label for the choice (Can be displayed in the client application interfaces)

Subscription Period

Example subscription period request

curl "https://app.ugmart.ug/api/products/secondary-price-list?id=DSTV.Period&primary=DSTV.Primary" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}"  

For bouquet purchase, a subscription period should be selected to determine the period of time the client wishes to pay for. This endpoint retrieves the list of available periods and their respective prices.

Subscription Period HTTP Request

GET https://app.ugmart.ug/api/products/secondary-price-list?id=&primary=

Request Parameters

Parameter Type Required Description
id string Required The list ID to be queried. In this case, DSTV.Period
primary string Required The primary/main product code, obtained from the products list. In this case, DSTV.Primary

Example success response for DSTV subscription period:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully.",
    "data": [
        {
            "code": "DSTV.Period:1",
            "price": 1,
            "name": "1 month"
        },
        {
            "code": "DSTV.Period:3",
            "price": 3,
            "name": "3 months"
        },
        {
            "code": "DSTV.Period:12",
            "price": 12,
            "name": "12 months"
        }
    ]
}

HTTP Response

Description of the response parameters

The table below describes the parameters returned under the data value. This value contains an array of of the available subscription periods with each having the parameters described below

Parameter Type Description
code string This is the unique identifier of the period in the list. This value will be used during purchase
price integer This value represents the purchase price for the period
name string The name of the subscription period. This can be displayed on your client applications for easy navigation.

Secondary DSTV Product

Example secondary DSTV product list request

curl "https://app.ugmart.ug/api/products/secondary-price-list?id=DSTV.Secondary&primary=DSTV.Primary" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}"  

If the client wishes to pay for any of the available secondary DSTV products, this endpoint retrieves the list of those products. The client can then choose from the list

Secondary Product list HTTP Request

GET https://app.ugmart.ug/api/products/secondary-price-list?id=&primary=

Request Parameters

Parameter Type Required Description
id string Required The list ID to be queried. In this case, DSTV.Secondary
primary string Required The primary/main product code, obtained from the products list. In this case, DSTV.Primary

Example success response for DSTV secondary product list:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Request completed successfully.",
    "data": [
        {
            "code": "DSTV.Secondary:HDPVRE36",
            "price": 41250,
            "name": "DStv HDPVR Access Service E36 - 41,250 UGX"
        }
    ]
}

HTTP Response

Description of the response parameters

The table below describes the parameters returned under the data value. This value contains an array of of the available subscription periods with each having the parameters described below

Parameter Type Description
code string This is the unique identifier of the period in the list. This value will be used during purchase
price integer This value represents the purchase price for the period
name string The name of the subscription period. This can be displayed on your client applications for easy navigation.

Bouquet purchase with secondary product

Example purchase request for DSTV bouquet purchase with secondary product

curl "https://app.ugmart.ug/api/products/purchase" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "account_code": "15B0D8D8BE",
      "transaction_id": "auto",
      "amount": 74250,
      "msisdn": "1025628563",
      "product_code": "DSTV.Primary:ACSSE36",
      "description": "DStv Access Bouquet E36 - 33,000 UGX",
      "details": {
            "contact_phone": "0777044237",
            "purchase_mode": "Bouquet",
            "period": "DSTV.Period:1",
            "feature": "Yes",
            "secondary_product_code": "DSTV.Secondary:HDPVRE36"
        }
    }'

Purchase HTTP Request

POST https://app.ugmart.ug/api/products/purchase

Request Parameters

Parameter Type Required Description
account_code string Required Collection Account code. This can be copied from the dashboard where the account was created. The balance on this account is deducted to effect the purchase. By default, the UGX wallet is used for this procedure.
transaction_id string Required A unique generated string to identify request. If the value is “auto”, the API generates this ID on your behalf
amount integer Required The amount to be paid for the product. In this case, it’s the sum of the main bouquet price and secondary product price, multiplied by the price of the subscription period
msisdn string Required The recipient account number (The DSTV customer number)
product_code string Required The unique identifier for the product. It can be got from the response of the Product Price list endpoint
description string Required Description of the purchase. You could use the product name (obtained from the products list endpoint above)
contact_phone string Required Mobile Phone Number. Purchase SMS will be sent to this number
purchase_mode string Required The choice of purchase for the TV subscription. In this case, Bouquet
period string Required The subscription period code. This is obtained from the secondary price list as described above
feature string Required The decision whether or not the client wishes to purchase a secondary product. In this case, Yes, obtained as described in the sections above
secondary_product_code string Required The unique code of the secondary product obtained from the “Secondary DSTV Product” list

Example success response for DSTV Bouquet subscription with secondary product:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Purchase completed successfully",
    "data": {
        "transaction_id": "1513940716",
        "msisdn": "1025628563",
        "description": "DSTV Multichoice",
        "product_type": "TV",
        "memo": "Account Number 1025628563 topped up successfully : LAWRENCE B",
        "tariff_charge": 0,
        "provider_transaction_id": 5038199359,
        "details": {
            "customer_name": "LAWRENCE B, DUE: 172500 UGX / 11-APR-2018"
        }
    }
}

HTTP Response

Arguments

Parameter Type Description
code integer The HTTP Status Code
status string Response status: SUCCESS or FAILED or INCOMPLETE
message string Descriptive response message
data JSON String Details of the purchase

Bouquet purchase without secondary product

Example purchase request for DSTV bouquet purchase without secondary product

curl "https://app.ugmart.ug/api/products/purchase" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {JWT}" \
  -d '{
      "account_code": "15B0D8D8BE",
      "transaction_id": "auto",
      "amount": 74250,
      "msisdn": "1025628563",
      "product_code": "DSTV.Primary:ACSSE36",
      "description": "DStv Access Bouquet E36 - 33,000 UGX",
      "details": {
            "contact_phone": "0777044237",
            "purchase_mode": "Bouquet",
            "period": "DSTV.Period:1",
            "feature": "No"
        }
    }'

Purchase HTTP Request

POST https://app.ugmart.ug/api/products/purchase

Request Parameters

Parameter Type Required Description
account_code string Required Collection Account code. This can be copied from the dashboard where the account was created. The balance on this account is deducted to effect the purchase. By default, the UGX wallet is used for this procedure.
transaction_id string Required A unique generated string to identify request. If the value is “auto”, the API generates this ID on your behalf
amount integer Required The amount to be paid for the product. In this case, it’s the main bouquet price multiplied by the price of the subscription period
msisdn string Required The recipient account number (The DSTV customer number)
product_code string Required The unique identifier for the product. It can be got from the response of the Product Price list endpoint
description string Required Description of the purchase. You could use the product name (obtained from the products list endpoint above)
contact_phone string Required Mobile Phone Number. Purchase SMS will be sent to this number
purchase_mode string Required The choice of purchase for the TV subscription. In this case, Bouquet
period string Required The subscription period code. This is obtained from the secondary price list as described above
feature string Required The decision whether or not the client wishes to purchase a secondary product. In this case, No, obtained as described in the sections above

Example success response for DSTV Bouquet subscription without secondary product:

{
    "code": 200,
    "status": "SUCCESS",
    "message": "Purchase completed successfully",
    "data": {
        "transaction_id": "1513940716",
        "msisdn": "1025628563",
        "description": "DSTV Multichoice",
        "product_type": "TV",
        "memo": "Account Number 1025628563 topped up successfully : LAWRENCE B",
        "tariff_charge": 0,
        "provider_transaction_id": 5038199359,
        "details": {
            "customer_name": "LAWRENCE B, DUE: 172500 UGX / 11-APR-2018"
        }
    }
}

HTTP Response

Arguments

Parameter Type Description
code integer The HTTP Status Code
status string Response status: SUCCESS or FAILED or INCOMPLETE
message string Descriptive response message
data JSON String Details of the purchase