Pay TV Open API Uganda – DSTV, GOTV, ZUKU, STARTIMES

Pay TV Open API Uganda

Pay TV Open API Uganda – EasyPay provides an easy Restful API that makes the process of paying your cable tv a breeze. This api supports the following providers in Uganda; Gotv, DSTV, Startimes and ZUKU.

API stands  for application programming interface. It can be interfaced by developers of all kinds of apps or systems to pay the cable tv bills within Uganda.

Open Pay TV Bill Payment Requirements

 

  1. Easypay account; First things first, you need to register for an easypay account. registration is free and painless. Register for an easypay account. Once you have registered and signed in, you will have to enable your API from within the app, so as you can get your credentials in real time.  The process is explained in detail below.
  2. The API is very simple and live so there is no sandbox environment. This helps you get integrated in a matter of minutes,test and get the feel of the API. The Gotcha.  By default all api accounts are limited to bill payments worth 100USD/month for the purpose of testing. To remove this limitation, you will have to contact us with your company details (KYC) and fill in the API application form we provide.

 

Enable Pay TV Bill Payments API within Easypay Wallet

Enable Mobile Money API for MTN, Airtel, Africell and UTL m-sente Uganda 1. Go to https://www.easypay.co.ug/v3/ and create an account.

2. Sign in and tap the API button shown on the home screen as shown in the image to the left.

3. The enable API screen will load up and offer you a green button to enable API. Tap this button and we proceed to creating and enabling API services for your account.

 

Open Mobile Money API

Step 1 – Fill in your Information

  • Name – This can be your brand or company name.
  • Description – Please describe why you need the API and what you will be using it for.
  • website – The URL to your website
  • IPN URL – Whenever a transaction is confirmed, this is the url that will be posted to with transaction details. IPN – stands for Instant Payment Notification. You will have to provide us a callback (ipn) url to notify your system when payments are made.
  • PIN – Please enter your easypay PIN to confirm enabling your API.

Using instant payment notification model, all your transactions should be marked as pending and only be marked as confirmed from this notification. It is also known as the callback url.

After you click save, your API will be enabled and live. You will be given a client Key and client Password that you will need for authenticating the API functions below.

 

 

Easypay Bill API Endpoint

URL – This is the url you will call to access the API. It is also known as the api entry point or end-point. https://www.easypay.co.ug/api/

Please make sure your have an SSL certificate installed before calling above URL. Your origin must be https.

Anatomy of Request

The API expects a POST request with a JSON encoded string of request. Every call to the API must have at least the format below. Some methods require extra fields depending on the call.

Payload

{
"username": "clientId",
"password": "clientSecret",
"action":"paybill",
"provider":"startimes",
"phone":"078....",
"amount":"1000",
"account":"2114....."
}

username

This is the API clientId that you are given within app after you enable API. see above

password

This is the API secret that you are given within app after you enable API. see above

action

This is the API method being called. In this case it will always be paybill

provider

This is the service provider in this case it can be dstv, gotv, startimes or zuku

 

Anatomy of Response – Pay TV API Uganda

 

A success response comes in the following JSON format . You have to test the success field to either 1 for success or 0 for failed.

Successful Response

{
"success": 1,
"data": string,
"details":object
}

success This is an integer describing response. 1 for success, 0 for failed transaction
data Human friendly formatted string containing transaction details.
details Object containing transaction details like receipt number, date etc

Failed Response

{
"success": 0,
"errormsg": "error message here describing failure"
}

Pay TV API Uganda – Process Flow

 

  1. Get package bundles and ask the user to pick his/her desired package. This can be done will paybillbundles method. This step only applies for gotv and dstv. Startimes and zuku just skip to step 2.
  2. Request account number – This process involves asking the user to provide their pay tv account number.
  3. Validate Customer – This process checks with tv biller system if the provided account is a valid account. If successful it returns  customer name, any outstanding amounts etc. Using api you can use the paybilladvice method to return these details.
  4. Pay Bill – This process does the actual bill payment.

 

Pay TV API Uganda – API methods

 

paybillbundles

This method returns a list of tv package bundles supported by the service provider. You are supposed to display these to the user giving him a choice to choose his/her desired package.

POST URL: https://www.easypay.co.ug/api/

Payload
{
"username": "Your clientId",
"password": "Your Secret",
"action":"paybillbundles",
"provider":"gotv"
}
  • action – This leave as ‘paybillbundles’
  • provider – This this the provider you are quering. In this case, can be gotv or dstv.

Success Result

{"data":[{"label":"GOTV Lite (UGX 11,000)","description":"GOTV Lite (Monthly - 11000)","id":"21546","price":11000,"isForex":0},{"label":"GOtv Lite 12 Months (UGX 70,000)","description":"GOtv Lite 12 Months (70,000)","id":"215466","price":70000,"isForex":0},{"label":"GOtv Value (UGX 16,000)","description":"GOtv Value (16000)","id":"21554","price":16000,"isForex":0},{"label":"GOtv Plus (UGX 28,000)","description":"GOtv Plus (28,000/=)","id":"21555","price":28000,"isForex":0}],"success":1}}

Failure Result

{
"success": 0,
"errormsg": "This method is not supported by this provider"
}

paybilladvice

This method is called when a user wants to check and validate the users provided account number.

POST URL: https://www.easypay.co.ug/api/

Payload
{
"username": "Your clientId",
"password": "Your Secret",
"action":"paybilladvice",
"provider":"gotv",
"account":"2014xxxx"
}
  • action – This leave as ‘paybilladvice’
  • provider – This this the provider you are quering. In this case can be either startimes, zuku, gotv or dstv.
  • account – dstv, gotv, zuku or startimes account number

Success Result

{"success":1,"data":{"TransactionRef":"BOU|Web|3T...","Biller":"Multichoice","CustomerId":"2014...","CustomerName":"SSEMUDDU J","inTxId":545032}}

Failure Result

{
"success": 0,
"errormsg": "INVALID CUSTOMER REFERENCE"
}

paybill

This method is called when a user wants to pay the actual bill.

POST URL: https://www.easypay.co.ug/api/

Payload
{
"username": "Your clientId",
"password": "Your Secret",
"action": "paybill",
"provider": "gotv",
"phone": "0787....",
"amount": "1000",
"account": "211.....",
"bundleId":"21546",
"reference":"your order id"
}
  • action – This leave as ‘paybill’
  • provider – This this the provider you are quering. In this case can be gotv, dstv, startimes and zuku.
  • account – gotv, dstv, startimes and zuku account number
  • amount – The amount you wish to pay. Incase of gotv or dstv, this is the price of bundleId; {"label":"GOTV Lite (UGX 11,000)","description":"GOTV Lite (Monthly - 11000)","id":"21546","price":11000,"isForex":0}
  • phone – This is the phone number where your receipt will be sent.
  • bundleId – This is the package Id. It is the id of selected bundle eg below is a sample selected gotv bundleId ; {"label":"GOTV Lite (UGX 11,000)","description":"GOTV Lite (Monthly - 11000)","id":"21546","price":11000,"isForex":0}
  • reference – Your order reference. it will be returned in successful results and can be used for reconciliation later on. This value must be unique.

Success Result

{
"success": 1,
"details": {
"phone": "0787.....",
"account": "2114...",
"amount": "1000",
"easypayId": "5345351",
"transferCode": "20024xxx-GOTV834561",
"type": "",
"reference":"Your order ref",
"date": "2018-10-27 13:10:28"
},
"data": "Your payment of Gotv has been accepted. Customer Ian K.... Account: 2114... Tel: 0787... Amount: UGX 11,000 "
}

Failure Result

{
"success": 0,
"errormsg": "Insufficient balance"
}

paybillstatus

This method is called when a user wants to pay find out the current status of bill against the reference they provided above. It can be used for auto-reconciliation. In response take note of the status property. It tells you the status of order. Incase of ‘Success’ it also return order receipts.

POST URL: https://www.easypay.co.ug/api/

Payload
{
"username": "Your clientId",
"password": "Your Secret",
"action": "paybillstatus",
"provider": "gotv",
"reference":"your order id"
}
  • action – This leave as ‘paybillstatus’
  • provider – This this the provider you are quering. In this case can be gotv, dstv, zuku or startimes
  • reference – Your order reference.

Success Result

{
"success": 1,
"data": {
"status": "Success",
"data": {
"data": "837761XX",
"transferCode": "0424XXX-NWSC8463157",
"charge": 330,
"success": 1,
}
}
}

Failure Result

{
"success": 0,
"errormsg": "Cannot find reference provided"
}

Other methods worth looking into;

checkbalance

This method is called you want to know your current balance at easypay. You can use this method to notify you that your balance is running low. That way you can ensure you do not run out of float.

POST URL: https://www.easypay.co.ug/api/

Payload
{
"username": "Your clientId",
"password": "Your Secret",
"action": "checkbalance"
}

Success Result

{
"success": 1,
"data": "14129.9",
"currencyCode": "UGX"
}

Failure Result

{
"success": 0,
"errormsg": "something went wrong"
}

 

Pay TV Commissions

The listing below is the standard Pay TV payment commissions. If you have sufficient volume then they can be modified on a case by case scenario.

 

Provider Commission Percentage
dstv 1.12%
gotv 1.12%
startimes 2.40%
zuku 1.12%

Was this article helpful?

Related Articles