PEGASUS TECHNOLOGIES

PegPay Utility Payments API

Developer Documentation
Version: 3.2

10/10/16
 Contents
Contents

VERSION HISTORY............................................................................................................................................................. 3
1.​ INTRODUCTION.........................................................................................................................................................4
1.1​Purpose of the Platform.......................................................................................................................................... 4
1.2​Intended Audience and Reading Suggestions......................................................................................................... 5
1.3​Product Scope......................................................................................................................................................... 5
1.3.1​Validate Utilities’ Customer Details.......................................................................................................... 5
1.3.2​Post Utilities’ Customer Transactions....................................................................................................... 5
1.3.2​Get Transaction Details............................................................................................................................ 5
2.​ SYSTEM DESCRIPTION............................................................................................................................................... 6
2.1​Proposed Bill Collection Procedure at Banks...........................................................................................................6
2.2​What is the flow/experience like?...........................................................................................................................6
3.​ SYSTEM FEATURES.....................................................................................................................................................8
3.1​Query Customer Details.......................................................................................................................................... 8
3.1.1​Description.............................................................................................................................................. 8
3.2​Post Transactions Details.......................................................................................................................................15
3.2.1​Description............................................................................................................................................ 15
3.3​Get Transaction Details......................................................................................................................................... 22
3.3.1​Description............................................................................................................................................ 22
3.4​Other Methods/Operations.................................................................................................................................. 27
4.​ DATA DICTIONARY................................................................................................................................................... 30
5.​ FIELD MAPPING.......................................................................................................................................................37
6.​ CODES..................................................................................................................................................................... 39
6.1​Status codes.......................................................................................................................................................... 39
7.​ UTILITY CODES AND TYPES......................................................................................................................................40
7.1​Electricity Payment types...................................................................................................................................... 40
7.2​Electricity Customer types.................................................................................................................................... 40
7.3​(DStv) Customer types...........................................................................................................................................41
7.4​Utility codes.......................................................................................................................................................... 41
7.5​Areas for NWSC..................................................................................................................................................... 41
8.​ SECURITY REQUIREMENTS...................................................................................................................................... 41
 8.1​Authentication/Authorization............................................................................................................................... 41

8.2​Data Integrity........................................................................................................................................................ 42
8.3​Digital Signatures...................................................................................................................................................42
8.4​IP Whitelisting....................................................................................................................................................... 42
9.​ OTHER REQUIREMENTS.......................................................................................................................................... 42
9.1​Digital Signatures...................................................................................................................................................42
9.2​Non-functional requirements................................................................................................................................43
9.2.1​Location of the Test Environment:..........................................................................................................43
9.2.2​Sample Test AccountsNWSC...................................................................................................................44
VERSION HISTORY
Date Description Editor
05/06/2016 Initial document Kasozi Nsubuga
10/10/2016 Document rearrangement Albert Luganga
12/12/2017 Added the changes to the Mayani Edith Martha Amayo
Get transaction Details to
return the required
adjustments by UMEME in
the response
09/11/2021 Changes on Query Mabirizi Ahmed
Customer Details,Get
transaction Details api
methods.
 1.​INTRODUCTION
Pegasus Technologies Ltd is a payments Aggregator/Integrator company with existing
relationships with a number of Banks and Mobile Money Service Providers through which
customers can settle any payments. Pegasus Technologies also has existing relationships with a
number of service providers who would like to have payments for their services settled through
the PegPayAPI Payments Platform that acts as an interface between service providers and
payments handlers.

In the past, any customer of any service provider wishing to make a payment would be required
to walk into any partnering bank or mobile money kiosk and pay for their services. However, this
arrangement has a number of challenges that include the following:

a)​ When making payments, these customers do sometimes supply erroneous account
customer references or tellers capture the supplied references wrongly. This happens
because at the point of posting payments, the tellers have no way of validating these
references to ensure that they are posting against correct customer references or
posting against the correct utility customer. This has led to a number of situations where
customers’ payments are made but not credited due to wrong or insufficient information
from the banks to correctly credit these customers. This in turn has caused a lot of
distress to the customers who get disconnected even after payment has been made. As
for the utility, it creates an ever increasing amount of money on the suspense account
for which cannot easily be reconciled with customer’s payments.
b)​ Sometimes returns from the banks of payments made against customers come in late,
and consequently customers get the services they paid for later than anticipated. In
some cases, customers have their account disconnected as a result of returns not getting
to the utility in a timely manner.

This has caused customers to shun the bank payment option due to the above mentioned
inefficiencies and opt to pay directly at the utility’s cash points.

1.1​Purpose of the Platform

To eliminate the above mentioned challenges, Pegasus Technologies has developed an interface
to all the utilities’ billing systems through which the banks and mobile money companies can be
able to validate the utilities’ customer details in real time and post transactions for utility
payments through to the PegPayAPI Payments platform in real time to have the customer’s
account updated.

1.2​Intended Audience and Reading Suggestions

This document is intended for a more technical audience, such as developers, project managers,
testers, system analysts and architects, consultants and requirements documentation writers.
It’s generally intended for all those intending to implement technical integration between their
systems and the PegPay Payments Platform.

1.3​Product Scope
The PegPayAPI Payments Interface will contain 3 general functionalities:

1.3.1​Validate Utilities’ Customer Details:

This functionality will enable Utilities’ collection agents to validate the details of the
customer intending to make a utility payment. This functionality has to precede the
processing of the payment.
1.3.2​Post Utilities’ Customer Transactions:

This functionality is used by the utilities’ collection agents to post the transactions made
for utility payments through to the PegPay Payments Platform. These payments are
immediately reflected in the billing/payments platforms of the utility companies.

1.3.2​Get Transaction Details:

This functionality is used by the collection agents to get the details of previously posted
transactions. It can be used to confirm whether a request was successfully processed in
the event of a communication error during processing. It can also be used to carry out
auto-reconciliation with the PegPay Payments platform.
 2.​SYSTEM DESCRIPTION
2.1​Proposed Bill Collection Procedure at Banks

QueryCustomerDetails
(CustomerRef,Utilitycode,VendorCode,Password)

Validate VendorCode and Password

QueryCustomerDetailsRequest(CustomerRef)

QueryCustomerDetailsResponse
QueryCustomerDetailsResponse

Display Details To Customer

PostTransactionRequest
(CustomerRef,VendorID,UtilityCode,Amount,DigitalSignature)
Validate and Log Transaction Details

PostTransaction PENDING Response

ernal Processing of transaction

GetTransactionStatusRequest(VendorID,VendorCode,Pas Retrieve Transaction Status

sword)
GetTransactionStatusRespon
se SUCESS or FAILED or
PENDING REASON/UTILITY
RECIEPT

2.2​What is the flow/experience like?

For Prepaid Vendors, the requirement is for the Vendor to first prefund a Pegasus account at the
Bank. When the prefunding is confirmed (for S.I. T’s this step can be skipped), the vendor
account at Pegasus is credited by the equivalent amount that was deposited. This means that
the vendor
and his customers can now transact via the PegPayAPI. However, the vendor’s customers will
only be allowed to transact amounts totaling up to the amount deposited.

1.​ Customer inputs/gives utility’s customer ID (CustomerRef) number to vendor system.

Vendor System sends QueryCustomerDetails request to PegPayAPI. PegPayAPI validates request.

​ If request is valid, PegPayAPI forwards Request to Utility. Utility returns details to

PegPayAPI and PegPayAPI sends details to VendorSystem. VendorSystem is required to

display the details to the customer so customer can verify the account belongs to him.

​ If request fails validation PegPayAPI sends error response with reason back to Vendor

System.

2.​ Customer inputs amount to pay into Vendor System, Vendor System submits a
PostTransactionRequest which includes the Vendor Transaction ID, amount, CustomerRef and a
digital signature to PegPayAPI.
PegPayAPI validates request including verifying digital signature to make sure data has not been
tampered with or altered whilst in transit.

​ If Request is valid PegPayAPI returns PostTransactionResponse to Vendor System which

indicates the transaction is PENDING. PegPayAPI goes ahead to process the request
asynchronously.

​ If request fails validation PegPayAPI sends error response indicating FAILURE along with

reason back to Vendor System

3.​ If Vendor system successfully posted a transaction, Vendor System continuously polls the
PegPayAPI every X seconds (recommended minimum is 2 min) by sending a
GetTransactionStatusRequest which has Vendor Transaction ID among the expected
parameters to the PegPayAPI. PegPayAPI Validates API and retrieves Transaction Status and
Details for Transaction with ID=Vendor Transaction ID before returning a
GetTransactionStatusResponse to the Vendor System.
The GetTransactionStatusResponse has a flag that indicates the transaction status.
 ​ If Transaction Status is FAILED, Vendor System stops polling for transaction status and

notifies customer of failure.

​ If Transaction Status is SUCCESS, Vendor System stops polling for transaction status and

notifies customer of SUCCESS.

If Transaction Status is PENDING, Vendor System continues to poll for transaction status every X
min.

3.​SYSTEM FEATURES
This section aims to give the developer an Overview/basic understanding of how the API works.
It’s not meant to be the final comprehensive document on how accessing each utility will work.
However, based on the basic message structure the developer will know how access to
subsequent utilities will work.

3.1​Query Customer Details

3.1.1​Description
Clients of the PegPay platform will utilize this functionality to generally query partnering
utilities’ customer databases and validate the paying customers’ information before they
proceed to effect any transactions for these customers. By so doing, this will reduce on any
errors that will be introduced into the database by the collecting agents. Errors such as crediting
the wrong account will be eliminated by using this functionality to validate customer data.
3.1.2​ Stimulus/Response
Sequences Stimulus
The agents will supply the utility customer reference and/or the area to which the customer
belongs, the vendor code and the password to the PegPay platform for verification.
Stimulus​ (custRef,​ area,​ UtilityCode,​ vendorCode,​ password,​ DigitalSignature)
The expected QueryCustomerDetailsRequest is expected to look like this
 POST /TestPegPayApi/PegPay.asmx HTTP/1.1
Host: 176.XXX.XXX.XXX
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://PegPayPaymentsApi/QueryCustomerDetails"

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<QueryCustomerDetails​ xmlns="http://PegPayPaymentsApi/">
<query>
<QueryField1>CustomerRef</QueryField1>
<QueryField2>Area(NWSC)/BouquetCode(PAYTV)</QueryField2>
<QueryField4>UtilityCode (NWSC, DSTV, UMEME)</QueryField4>
<QueryField5>VendorCode(REPLACE)</QueryField5>
<QueryField6>Password(REPLACE)</QueryField6>
<QueryField8>XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</QueryField8>
<query>
</QueryCustomerDetails>
</soap:Body>
</soap:Envelope>

Below is the description of the common expected parameters.

Parameter Description
QueryField1 CustomerRef(Utility customerID)
QueryField2 Area (NWSC)/BouquetCode(DSTV).etc.
QueryField4 UtilityCode(NWSC,UMEME,DSTV etc.)
QueryField5 VendorCode
QueryField6 Password
QueryField8 DigitalSignature

Digital Signature

dataToSign = VendorCode + Password + UtilityCode + CustomerRef OR literally

(QueryField5 + QueryField6 + QueryField4 + QueryField1)
A sample of the utilityCode for (NWSC, UMEME)
Below is the description of the common expected parameters.

Parameter Description
QueryField1 31263
QueryField2 Jinja
QueryField4 NWSC
QueryField5 FINCA
QueryField6 83X52IP734
QueryField8 XXXXXXXXXXXXXXXXXXXXX
Below is the description of the common expected parameters.

Parameter Description
QueryField1 205031293
QueryField2 POSTPAID
QueryField4 UMEME
QueryField5 STANBIC
QueryField6 62S44HN420
QueryField6 XXXXXXXXXXXXXXXXXXXXXXXXX

Response
The system will respond by an object of type: Response with the following fields:

✦​ CustRef,

✦​ CustName,

✦​ Area

✦​ OutstandingBalance,

✦​ StatusCode

✦​ StatusDescription

All successful customer queries will return with the StatusCode field as “0” and a
StatusDescription field as “SUCCESS”. In such an event the other fields will be populated with
the customer’s details.
Any query that returns with a different StatusCode than the one mentioned above will be a
failed query and the failure reason will be indicated in the StatusDescription field returned.

Such an error should be relayed back to the teller making the query or the customer.

PegPayAPI response will be in the format below.

 <?xml version="1.0"?>
<QueryCustomerDetailsResponse
​ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
​ xmlns:xsd="http://www.w3.org/2001/XMLSchema">
​ <ResponseField1>CustomerRef</ResponseField1>
​ <ResponseField2>CustomerName</ResponseField2>
​ <ResponseField3>Area/Bouquet</ResponseField3>
​ <ResponseField4>Amount</ResponseField4>
​ <ResponseField5>POSTPAID</ResponseField5>
​ <ResponseField6>0</ResponseField6>
​ <ResponseField7>SUCCESS</ResponseField7>
</QueryCustomerDetailsResponse>

Area/Bouquet is only returned for Utilities like NWSC and DSTV/GOTV

Below is the description of the commonly returned parameter

Parameter Description
ResponseField1 Customer Ref(utility customerID)
ResponseField2 Customer Name
ResponseField3 Area(NWSC)/Tin etc.
ResponseField4 Outstanding Balance/Amount Due
ResponseField5 Customer Type e.g. PREPAID or POSTPAID, DSTV or GOTV etc.
 ResponseField6 Status Code
ResponseField7 Status Description

Sample of Query Customer Details Response

<?xml version="1.0"?>

<QueryCustomerDetailsResponse

​ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

​ xmlns:xsd="http://www.w3.org/2001/XMLSchema">

​ <ResponseField1>206098192</ResponseField1>

​ <ResponseField2>KOMAKECH PETER</ResponseField2>

​ <ResponseField3>Not Always Returned</ResponseField3>

​ <ResponseField4>6596.0800</ResponseField4>

​ <ResponseField5>POSTPAID</ResponseField5>

​ <ResponseField6>0</ResponseField6>

​ <ResponseField7>SUCCESS</ResponseField7>

</QueryCustomerDetailsResponse>
Below is the description of the commonly returned parameters

Parameter Description
ResponseField1 4131263
ResponseField2 WANDERA
ResponseField3 Jinja
ResponseField4 39711
ResponseField6 0
ResponseField7 SUCCESS

3.2​Post Transactions Details

3.2.1​Description
PegPay’s collection agents will utilize this feature to post transactions that have been validated
and made against a utility to the PegPay payments platform.
After validation of customer details has been made, the collection agents will then collect the
payment details of the customer and effect this payment against the customer’s validated
details. The PegPay platform provides a method on its API to have payments posted against the
validated customer details. The method used to make payments is:
PrepaidVendorPostTransaction

3.2.2​ Stimulus/Response
Sequences Stimulus
When posting a payment, the vendor has to wrap the parameters of the transaction in an object
of type: TransactionRequest and pass it over to the PegPayAPI platform for posting.
The parameters posted through this object are described below:

PrepaidVendorPostTransaction (TransactionRequest trans)

The expected PostTransactionRequest is expected to look like this
Below is the description of the common expected parameters.

Parameter Description
PostField1 CustomerRef(Utility CustomerID)
PostField2 Customer Name
PostField21 Customer Type e.g. PREPAID or POSTPAID etc.
PostField3 Area
PostField4 UtilityCode
PostField5 PaymentDate in dd/MM/yyyy e.g. 28/12/2015
PostField7 TransactionAmount
PostField8 TransactionType e.g. CASH,EFT etc.
PostField9 VendorCode
PostField10 Password
PostField11 CustomerTel
PostField12 Reversal (is 0 for Prepaid Vendors)
PostField13 TranIdToReverse(is left blank)
PostField14 Teller e.g. can be customerTel or customer Name
PostField15 Offline (is 0)
PostField16 DigitalSignature
PostField17 ChequeNumber(is left Empty)
PostField18 Narration
PostField19 Email(can be Empty)
PostField20 Vendor Transaction ID
 Post Prepaid Transaction Request
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope​
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<PrepaidVendorPostTransaction xmlns="http://PegPayPaymentsApi/">
<trans>
<PostField1>04235798420</PostField1>
<PostField2>AUSI LUWANO</PostField2>
<PostField4>UMEME</PostField4>
<PostField5>26/06/2016</PostField5>
<PostField6>2</PostField6>
<PostField7>10000</PostField7>
<PostField8>CASH</PostField8>
<PostField9>Micropay</PostField9>
<PostField10>30K12CF236</PostField10>
<PostField11>256750852201</PostField11>
<PostField12>0</PostField12>
<PostField13>
</PostField13>
<PostField14>NONE</PostField14>
<PostField15>0</PostField15>

<PostField16>n3wTmYPhaR0azNQVuMkf7ihbbcIO6mg1D57TNpxF1B0ULYB07LI920OV2PNTqqp1o4
AWGluQsNbS
6fcx9YJrXAVFrCz2v8hGHy/GOXLk4emXuasB5QMH1Ll8kjNkW+X2aKFB7wAwGEX9J1Ngnlt3TyA1
ix4AIS7VXFyG5X7sjbA=
</PostField16>
<PostField17>
</PostField17>
<PostField18>UMEME PAYMENT FOR 04235798420</PostField18>
Below is the description of the common expected parameters.

Parameter Description
PostField1 04235798420
PostField2 AUSI LUWANO
PostField21 PREPAID
PostField4 UMEME
PostField5 26/06/2016
PostField6 2
PostField7 10000
PostField8 CASH
PostField9 Mircopay
PostField10 30K12CF236
PostField11 256750852201
PostField12 0
PostField14 NONE
PostField15 0
PostField18 UMEME PAYMENT FOR 04235798420
PostField19 Email(can be Empty)
PostField20 127003

Response
The system will respond by returning an object of type: PostResponse It will have

✦​ StatusCode

✦​ StatusDescription
✦​ PegpayId

✦​ CompanyPaymentReference
All successful transaction postings will return with the StatusCode field as “0” and a
StatusDescription field as “SUCCESS”. In such an event the PegpayId field will contain the
transaction reference number from PegPay.

Any transaction posting that returns with a different StatusCode than the one mentioned
above will be a failed transaction posting and the failure reason will be indicated in the
StatusDescription field returned.

PegPayAPI response will be in the format below.

Below is the description of the commonly returned parameters

Parmeter Descritpion
 responseField6 Status Code
responseField7 Status Description
responseField8 PegPayID

Sample Of Post Prepaid Transaction Response

Below is the description of the commonly returned parameters

Parmeter Descritpion
responseField6 1000
 responseField7 PENDING
responseField8 80087642

3.3​Get Transaction Details

3.3.1​Description
This method is used by a payment agent to determine if a transaction posted was successfully
effected. It can also be used to retrieve the details of a previously posted transaction by an
agent.
3.3.2​ Stimulus/Response
Sequences Stimulus
The agents will supply the VendorTransactionID, the vendorCode, the password and

the digitalSignature.​ Stimulus (VendorTransactionID, vendorCode, password,

digitalSignature)

The expected GetTransactionStatusRequest is expected to look like this

 Below is the description of the common expected parameters.

Parameter Description
QueryField5 VendorCode
QueryField6 Password
QueryField10 Vendor Transaction Id(Unique ID from Vendor System)

QueryField8 Digital Signature

Digital Signature
dataToSign = VendorCode + Password + VendorTransactionId OR literally
(QueryField5 + QueryField6 + QueryField10)

Sample of a Get Transaction Details Response

<GetTransactionDetailsResponse xmlns="http://PegPayPaymentsApi/">
<GetTransactionDetailsResult>
<ResponseField4>BANK REFERENCE</ResponseField4>
<ResponseField6>STATUS CODE</ResponseField6>
<ResponseField7>STATUS DESCRIPTION</ResponseField7>
<ResponseField8>UTILITY REFERENCE/ PREPAID TOKEN</ResponseField8>
<ResponseField13>NUMBER OF UNITS</ResponseField13>
<ResponseField14>SERVICE FEE</ResponseField14>
<ResponseField15>PAY ACCOUNT</ResponseField15>
<ResponseField16>DEBT RECOVERY</ResponseField16>
<ResponseField17>UMEME RECEIPT NUMBER</ResponseField17>
<ResponseField18>FOREX ADJUSTMENT</ResponseField18>
<ResponseField19>FUEL ADJUSTMENT</ResponseField19>
<ResponseField20>INFLATION ADJUSTMENT</ResponseField20>
<ResponseField21>PURCHASE BREAK DOWN (LIFELINE)</ResponseField21>
<ResponseField22>VAT</ResponseField22>
<ResponseField23>TOKEN VALUE</ResponseField23>
</GetTransactionDetailsResult>
</GetTransactionDetailsResponse>

Below is the description of the common expected parameters:

Parameter Description
ResponseField4 BANK REFERENCE
ResponseField6 STATUS CODE
ResponseField7 STATUS DESCRIPTION
ResponseField8 UTILITY REFERENCE/ PREPAID TOKEN
ResponseField13 NUMBER OF UNITS
ResponseField14 SERVICE FEE
ResponseField15 PAY ACCOUNT
ResponseField16 DEBT RECOVERY
ResponseField17 UMEME RECEIPT NUMBER
ResponseField18 FOREX ADJUSTMENT
ResponseField19 FUEL ADJUSTMENT
ResponseField20 INFLATION ADJUSTMENT
ResponseField21 PURCHASE BREAK DOWN (LIFELINE)
ResponseField22 VAT
ResponseField23 TOKEN VALUE

3.1​Get Account Balance

3.1.1​Description
This method is used by a payment agent to query for the balance on their Liquidation vendor
account at Pegasus.
3.1.2​ Stimulus/Response
Sequences Stimulus
The agents will supply the vendorCode and the password.

Stimulus (vendorCode, password, digitalSignature)

The expected GetAccountBalanceRequest is expected to look like this

Sample of a Get Account Balance Request

 Below is the description of the common expected parameters.

Parameter Description
QueryField5 VendorCode
QueryField6 Password
QueryField8 Digital Signature

Digital Signature

dataToSign = VendorCode + Password OR literally

(QueryField5 + QueryField6)

Sample of a Get Account Balance Response

PegPayAPI response will be in the format below.
Below is the description of the commonly returned parameters
Below is the description of the commonly returned parameters

3.4​Other Methods/Operations
3.4.1​GetPayTvBouquetDetails

Use this method to get bouquet names, prices and other details offered by different pay TVs
PegPayAPI response will be in the format below.
 4.​DATA DICTIONARY
In this section, we describe the fields in the PegPay API with the following parameters:

✦​ Field Name (FN)

✦​ Description (Desc)

✦​ Type (Type)

✦​ Constraints (Const)

✦​ Applicable Utility (AU)

FN: CustomerRef/ CustRef

Desc: The reference number of the Company/Utility Customer
Type: string
Const: 3 to max characters
AU: ALL

FN: CustomerName
Desc: The name of the Company/Utility’s customer
Type: string
Const: 1 to 100 characters
AU: ALL

FN: OutstandingBalance
Desc: The balance outstanding for the utility customer
Type: big integer
Const: big integer
AU: Water and Electricity

FN: VendorCode
Desc: The code supplied to the agent by PegPay to be used to identify them in the PegPay system.
Type: string
Const: 4 characters
AU: ALL
FN: PaymentDate
Desc: The date when a transaction was made
Type: string
Const: dd/mm/yyyy
AU: ALL

FN: transactionAmount
Desc: The amount of money received from the customer.
Type: big integer Const:
1 to 999,999,999 AU:
ALL

FN: transcationType
Desc: The type of transaction e.g. cash, cheque, direct debit, EFT, etc.
Type: string
Const: 1 to 50 characters
AU: ALL

FN: VendorTransactionID
Desc: The transaction reference from the agent’s system.
Type: string
Const: 1 to 30 characters
AU: ALL

FN: CustomerTel
Desc: The phone number of the customer/ person who has made the payment.
Type: string
Const: 1 to 25 characters
AU: ALL

FN: Narration
Desc: This is a narrative that the agent wishes to relay back to the utility e.g. incase a cheque
bounced, the vendor might want to accompany the posting of the bounced cheque with a
narrative about it.
Type: string
Const: 1 to max characters
AU: ALL
FN: StatusCode
Desc: A code that is returned after every request from PegPay indicating the status of the
transaction. The list of status codes and their descriptions are given in the status codes table
below.
Type: string
Const: 1 to 3 characters
AU: ALL

FN: StatusDescription
Desc: This is the description of the status code returned by the system. In the event there is an
error returned during validation or posting, the description of the error will be passed through
this field. A list of the descriptions is provided for in the status codes table.
Type: string
Const: 1 to 200 characters
AU: ALL

FN: Password
Desc: This password will be used together with the vendor code to authenticate every
transaction on the interface.
Type: alphanumeric string
Const:
AU: ALL

FN: Teller
Desc: This field is passed by the bank indicating the name or id of the teller who handled the
transaction.
Type: string
Const: 1 to max characters
AU: ALL

FN: TranIdToReverse
Desc: When a transaction is a reversal, the ID being reversed is passed in this field. This is the
VendorTranId of the transaction being reversed
Type: string
Const: 1 to 30 characters
AU: ALL
FN: PaymentType
Desc: This is the type of transaction(payment) being made by the customer. A list of these
transactions is provided for in the payment types table.
Type: string
Const: 1 to 100 characters
AU: ALL

FN: CustomerType
Desc: The type of customer making the payment. They can either be POSTPAID or PREPAID
customers for (Electricity). The customer types and their codes are stated in this table.
Type: string
Const: 1
AU: KCCA/UMEME

FN: Reversal
Desc: A flag that indicates whether the transaction being posted is a reversal or not. The code is
1 if it’s a reversal or 0 if it’s a normal credit transaction.
Type: string
Const: 1
AU: ALL

FN: ReceiptNumber
Desc: the receipt number issued by the company/utility in the event a transaction is successfully
posted into the utility’s payment platform through the PegPay Interface.
Type: string
Const: 1 to 30 characters
AU: Electricity

FN: PegpayQueryId
Desc: The reference number of a transaction or a query from the PegPay system
Type: string
Const: 1 to 30 characters
AU: ALL
FN: DigitalSignature
Desc: The data being posted to the PegPay System has to be digitally signed by the agent to
ensure that the data is coming from whoever the agent claims to be.
Type: string
Const: Base64String
AU: ALL

FN: Offline
Desc: A flag that indicates whether the transaction being posted was made in offline mode or
not. The code is 1 if it’s an offline transaction or 0 if it’s not.
Type: string
Const: 1
AU: ALL

FN: PayAccount
Desc: a prepaid token field that indicates how much of the account arrears are to be deducted
off the token payment.
Type: string
Const: 1 to 15 characters
AU: Electricity

FN: DebtRecovery
Desc: This is a prepaid token field that indicates how much of the (Electricity) debt accrued is to
be deducted off the token payment.
Type: string
Const: 1 to 15 characters
AU: Electricity

FN: MeterNumber
Desc: This is the meter number for which a token payment is being made
Type: string
Const: 11 characters
AU: Electricity

FN: Units
Desc: A prepaid token field that indicates how many units of power the customer will get from
the prepaid meter payment he has made.
Type: string
Const: 1 to 15 characters
AU: UMEME

FN: TokenValue
Desc: A prepaid token field that indicates how much the value of the token is in the currency
used to purchase the token.
Type: string
Const: 1 to 15 characters
AU: Electricity

FN: Inflation
Desc: This is a prepaid token field that indicates how much of the payment amount has been
deducted or added due to inflation.
Type: string
Const: 1 to 15 characters
AU: Electricity

FN: Tax
Desc: A prepaid token field that indicates how much of the payment amount has been deducted
due to tax.
Type: string
Const: 1 to 15 characters
AU: Electricity

FN: Fx
Desc: A prepaid token field that indicates how much of the payment amount has been deducted
or added due to foreign exchange
Type: string
Const: 1 to 15 characters
AU: Electricity

FN: Fuel
Desc: A prepaid token field that indicates how much of the payment amount has been deducted
or added due to fuel.
Type: string
Const: 1 to 15 characters
AU: Electricity
FN: TotalAmount
Desc: A prepaid token field that indicates total value of the prepayment token inclusive of all
deductions
Type: string
Const: 1 to 15 characters
AU: Electricity

FN: PrepaidToken
Desc: A prepaid token field that contains the actual token purchased
Type: string
Const: 20 characters
AU: Electricity

FN: Area
Desc: The area to which the (Water) customer belongs. It has to be supplied when querying for
customer details and also when making water payments. A list of the applicable areas is given in
here.
Type: string
Const: 30 characters
AU: Water

FN: UtilityCode
Desc: The code that identifies the company/utility in the PegPay system for which a payment is
being made
Type: string
Const: 10 characters
AU: ALL

FN: TIN
Desc: The Tax Identification Number for the paying customer.
Type: string
Const: 15 characters
AU: ALL
 5.​FIELD MAPPING

Query Request Fields Populated Applicable Company

CustomerReference QueryField1 ALL
Area/Tin QueryField2 Water(NWSC)

UtilityCode QueryField4 ALL

VendorCode QueryField5 ALL
Password QueryField6 ALL
ReserveField1 QueryField7
ReserveField2 QueryField8
ReserveField3 QueryField9
ReserveField4 QueryField10

Response Fields Populated Applicable Company

CustomerReference ResponseField1 ALL
CustomerName ResponseField2 (Electricity & Water), GOTV,DSTV
Area/TIN ResponseField3 (Water)
OustandingBalance ResponseField4 (Electricity & Water), GOTV

CustomerType ResponseField5 (Electricity), GOTV,DSTV

StatusCode ResponseField6 ALL
StatusDescription ResponseField7 ALL
PegPayTranId ResponseField8 ALL
CompanyPaymentReference ResponseField9 (Electricity)
ReserveField1 ResponseField10 GOTV,DSTV
ReserveField2 ResponseField11 GOTV,DSTV
ReserveField3 ResponseField12
ReserveField4 ResponseField13

TransactionRequest FieldPopulated Applicable Company

Custref PostField1 ALL
Custname PostField2 (Electricity & Water)
Area/Tin PostField3 (Water)
UtilityCode PostField4 ALL
CustomerTel PostField11 ALL
Email PostField19
CustomerType PostField21 (Electricity)
ChequeNumber PostField17 ALL
TransactionType PostField8 ALL
PaymentType PostField6 (Electricity)
TransactionAmount PostField7 ALL
PaymentDate PostField5 ALL
VendorTransactionID PostField20 ALL
DigitalSignature PostField16 ALL
VendorCode PostField9 ALL
Password PostField10 ALL
Narration PostField18 ALL
Teller PostField14 ALL
Reversal PostField12 ALL
TranIdToReverse PostField13 ALL
Offline PostField15 ALL
DigitalSignature PostField16 ALL
ChequeNumber PostField17 ALL
Narration/Reason PostField18 ALL
Email PostField19 ALL
VendorTransactionRef/ PostField20 ALL/
ReversalTransactionId PREPAID VENDORS
CustomerType PostField21 ALL
BranchCode PostField23 URA
BankCode PostField24 URA
Status PostField25 URA
ReserveField1 PostField30 GOTV,DSTV
ReserveField2 PostField31 GOTV,DSTV
ReserveField3 PostField32
ReserveField4 PostField33
ReserveField5 PostField34
ReserveField6 PostField22
 6.​CODES
6.1​Status codes
Status Code Status Description
0 SUCCESS
1 /100/200 INVALID CUSTOMER REFERENCE
2 INVALID PEGPAY VENDOR CREDENTIALS
3 INVALID TRANSACTION AMOUNT
4 INVALID PAYMENT DATE
5 INVALID TRANSACTION TYPE
6 INVALID CUSTOMER TELEPHONE
7 INVALID PAYMENT TYPE
8 TELLER DETAILS REQUIRED
9 TRANSACTION DETAILS ALREADY RECEIVED
10 GENERAL ERROR AT Utility
11 VENDOR CREDENTIALS HAVE BEEN DEACTIVATED.PLEASE CONTACT PEGASUS TECHNOLOGIES
12 INVALID PHONE NUMBER
13 CUSTOMER NAME NOT SUPPLIED
14 TRANSACTION TYPE NOT SUPPLIED. EG CASH,EFT
15 PAYMENT TYPE NOT SUPPLIED. EG 2,3,4
16 VENDOR TRANSACTION REFERENCE NOT SUPPLIED
17 TELLER DETAILS NOT SUPPLIED
18 SIGNATURE NOT VALID AT PEGPAY
19 SIGNATURE NOT PROVIDED
20 DUPLICATE VENDOR REFERENCE AT PEGPAY
21 SUSPECTED DOUBLE POSTING AT PEGPAY
22 ORIGINAL VENDOR TRANSACTION REFERENCE NOT SUPPLIED
23 TRANSACTION NARATION IS REQUIRED
24 INVALID ORIGINAL VENDOR TRANSACTION REFERENCE
25 INVALID TRANSACTION REVERSAL STATUS SUPPLIED. EG 0 or 1
26 AMOUNT TO REVERSE DOES NOT MATCH WITH AMOUNT REVERSING
27 INVALID PAYMENT CODE
28 INVALID CUSTOMER TYPE EG POSTPAID or PREPAID
29 UTILITY CREDENTIALS NOT SET
30 UNABLE TO CONNECT TO UTILITY
31 PEGPAY DB UNAVAILABLE
 32 GENERAL ERROR AT PEGPAY
33 TRANSACTION DOESN'T EXIST IN PEGPAY
34 INVALID TIN
35 PLEASE SUPPLY AN AREA FOR (Water) PAYMENTS
41 INSUFFICIENT VENDOR ACCOUNT BALANCE
101 GENERAL ERROR AT PEGPAY
100 UNKNOWN URA PAYMENT TYPE
INVALID BOUQUET FOR DSTV
INVALID UTILITY REFERENCE NUMBER
FAILED TO GET BOUQUET DETAILS

NB: Due to an enormous number of status descriptions under the code 100, It is set forth here
that the status code 100 always implies a failure usually to find requested data.

7.​UTILITY CODES AND TYPES

7.1​Electricity Payment types
Payment Code Payment Type
2 Energy Payment
5 Reconnection Fee
14 Inspection Fee
1 Security Deposit
4 Capital Contribution
3 Bounced Cheque Fine
6 Rechargeable Works Order
7 Meter Test Fee
9 Fine General
10 Non Refund Tender Deposit

7.2​Electricity Customer types

Customer Type Type Code
Postpaid POSTPAID
Prepaid PREPAID
7.3​(DStv) Customer types
Customer Type Type Code
Gotv GOTV
Dstv DSTV

7.4​Utility codes
Utility Type Utility Code
WATER NWSC
ELECTRICITY UMEME
GOTV GOTV
DSTV DSTV
AIRTIME AIRTIME

7.5​Areas for NWSC

-Kampala

-Entebbe

-​Jinja

-​Mukono

-​Iganga

-​Lugazi

-Kawuku

-​Kajjansi

-​Others

8.​SECURITY REQUIREMENTS
The PegPayAPI Payments Platform will have four levels of security:

8.1​Authentication/Authorization:
Every request and transaction performed on the system will be authenticated
using username (VendorCode) and a Password to ensure that the requestor of the
service is authorized to perform transactions on the service and ask for the
request from the service.

This username and password will also be used to authenticate users of the system. This will
ensure that only authorized requests and transactions are processed by the interface.
If for any reason the username and/or password assigned to the vendor are entered
incorrectly more than three times, the vendor’s account to the platform will be deactivated
and the vendor will have to contact Pegasus Technologies to have it reactivated.
8.2​Data Integrity:
Communication between the PegPay API and its several clients will be performed over Secure
Sockets Layer (SSL) using 128-bit encryption. This will ensure that data transmitted to and from
the interface will be encrypted.

The onus will be on the client of the interface to ensure that it can handle and manipulate
certificates issued by Pegasus Technologies.

8.3​Digital Signatures:
Data transmitted for posting is digitally signed and the digital signature from the agent
validated by the PegPay API before this request for posting is processed. In the event the
signature is invalid, the data will be rejected by the interface as it will most likely have come
from an imposter of the agent. This will ensure that only data from authorized agents is
processed by the PegPay Platform.

8.4​IP Whitelisting:
On production, all data processed by the PegPay API platform will only be
processed when its coming from IPs of known agents that have been whitelisted.
Data from other unknown IPs will be rejected by PegPay.

9.​OTHER REQUIREMENTS
9.1​Digital Signatures
All transactions posted to the PegPay Payments Platform have to be digitally
signed and the digital signature is posted as one of the parameters when posting a
successful transaction. The purpose of the digital signature is to ensure that the
transactions are received from agents who claim to be who they are.
When signing the data, the agent will combine the following fields as indicated
below, sign them and pass the digital signature as one of the parameters when
posting the transaction. Before granting credentials to the PegPay system, vendors
will have to issue Pegasus Technologies with a public certificate (.cer) with which
all digital signatures will be verified.

When signing the data, the agent will combine the following fields as indicated
below, sign them and pass the digital signature as one of the parameters when
posting the transaction. dataToSign (CustRef + CustName + CustomerTel +
VendorTransactionID + VendorCode + Password + PaymentDate + Teller +
TransactionAmount + Narration + TransactionType;) OR literally

(PostField1 + PostField2 + PostField11 + PostField20 + PostField9 + PostField10 +

PostField5 + PostField14 + PostField7 + PostField18 + PostField8)
To sign the data, the vendor will have to use a combination of SHA1 and RSA to generate the
digital signature. Steps for signing the data are described below

​ Compute sha1 hash of concatenated string

​ Use RSA to encrypt hash with private Key

​ Convert encrypted text into base64 string The base 64 string is the

digital signature.

9.2​Non-functional requirements
9.2.1​Location of the Test Environment:

The PegPay Payments API is a SOAP XML web service that will be shared with the vendor
one creation
The URL is wrapped round SSL and the service will issue an SSL certificate that will be usedby
the client to encrypt all communication between the client and the service.
9.2.2​ Sample Test
Accounts NWSC
CustomerRef – 11111, Area – Kampala
UMEME
Prepaid
CustomerRef – 04237341583
Post Paid
CustomerRef – 201959568
DSTV
CustomerRef – 4261353579 BouquetCode – PREW4
GOTV
CustomerRef - 2009458460 BouquetCode - GOTVPLS
URA
UAL001F
KCCA
UAT500B