ETAX

e-Payment
Technical Proposal

Baseline v1.6

03/Nov/2009

This document describes the Technical details of the e-Payment concept to be implemented in ETax.
It has developed after consultation with the stakeholder banks. Take note that this document is
controlled and unauthorized access, copying, replication or usage for a purpose other than for which
it is intended, is prohibited.
 Release Note:
This is a managed document. For identification of amendments, each page contains a release
number and a page number. Changes will only be issued as a new document version. Superseded
versions shall be destroyed immediately.
This document is authorized for release once all signatures have been obtained.

Name Organization Title Signature Date

Moses Kajubi Commissioner Domestic
Taxes, Project Owner DTMP
Edna Rugumayo AC-Finance
Henry Saka Project Manager DTMP

Version and Configuration Management

Version Date Summary of Author
Changes
1.0 Jun 22, 2009 First Draft TCS
1.2 Jul 6,2009 Second Draft James Kizza
1.3 Aug 21, 2009 Third Draft Chirag Chaudhary
1.4 Aug 24,2009 Fourth Draft James Kizza
1.5 Aug 25, 2009 Fifth Draft Chirag Chaudhary
1.6 Nov 03,2009 Baseline James Kizza
 Table of Contents

1. Summary of Changes Version 1.6 ....................................................................................... 5

1.1 Assumptions Made......................................................................................................... 5
1.2 Bank Account field.......................................................................................................... 5
1.3 CSV File Name Format exchanged .................................................................................. 5
1.4 Codes for dishonored cheques ....................................................................................... 5
1.5 Secure FTP Acknowledgement to be done via status logging .......................................... 5
1.6 Daily bank of Uganda file ................................................................................................ 5
1.7 End of Day files............................................................................................................... 5
1.8 Https acknowledgement field changes ........................................................................... 5
1.9 Status Clarification ......................................................................................................... 6
1.10 Others ........................................................................................................................ 6
2. Introduction ....................................................................................................................... 7
2.1 Assumptions................................................................................................................... 7
3. Over the Counter Payment ................................................................................................. 8
3.1 Payment Registration Data Interface .............................................................................. 8
3.1.1 Batch Details........................................................................................................... 8
3.1.1.1 Data Elements .................................................................................................... 8
3.1.1.2 File Format ......................................................................................................... 8
3.1.1.3 Other details ....................................................................................................... 9
3.1.1.4 Example .............................................................................................................. 9
3.2 Payment Verification .................................................................................................... 10
3.2.1 Status Check ......................................................................................................... 10
3.2.1.1 Available – A/ Cancelled – C .............................................................................. 10
3.2.1.2 Transacted – T .................................................................................................. 10
3.2.1.3 Expired – X ........................................................................................................ 10
3.2.2 Payment Registration Details Check ...................................................................... 10
3.3 Payment Transaction Details ........................................................................................ 11
3.3.1 Batch Details......................................................................................................... 11
3.3.1.1 Data Elements .................................................................................................. 11
3.3.1.2 File Format ....................................................................................................... 12
3.3.1.3 Other Details .................................................................................................... 12
3.3.1.4 Example ............................................................................................................ 12
3.4 Transmission and Acknowledgement Details ................................................................ 12
3.4.1 Transmission Frequency ....................................................................................... 13
3.4.2 End of Data Exchanges .......................................................................................... 13
3.4.2.1 Payment Registration End of Day File ................................................................ 13
3.4.2.2 Payment Transaction End of Day File ................................................................ 13
3.4.2.3 Bank of Uganda Transfer File ............................................................................ 14
3.4.2.3.1 Data Elements .................................................................................................. 14
3.4.2.4 Example ............................................................................................................ 14
3.4.3 HTTPS based Transmission & Acknowledgement .................................................. 14
3.4.3.1 Channel ............................................................................................................ 14
3.4.3.2 URL ................................................................................................................... 15
3.4.3.3 Acknowledgement by bank of Payment Registration batches from URA............ 15
3.4.3.3.1 Data Elements of Acknowledgements .............................................................. 15
3.4.3.4 Acknowledgement by URA of payment transactions received from Bank .......... 16
3.4.4 Secure FTP based Transmission & Acknowledgement ........................................... 16
3.4.4.1 Channel ............................................................................................................ 16
3.4.4.2 URL ................................................................................................................... 17
 3.4.4.3 Acknowledgement by Bank of Payment Registration Batches from URA ........... 17
3.4.4.4 Data Elements .................................................................................................. 17
3.4.4.4.1 Example ........................................................................................................... 18
3.4.4.5 Acknowledgement by URA of Payment Transactions from Banks ...................... 18
3.4.4.6 Data Elements .................................................................................................. 19
3.4.4.6.1 Example ........................................................................................................... 19
3.5 Exception Cases............................................................................................................ 20
3.5.1 Transmission Failure ................................................................................................. 20
3.5.1.1 HTTPS Transmission Failure .................................................................................. 20
3.5.1.2 Secure FTP Transmission Failure ........................................................................... 20
3.5.2 Acknowledgement Failure ........................................................................................ 20
3.5.2.1 HTTPS Acknowledgement Failure.......................................................................... 20
3.5.2.2 Secure FTP Acknowledgement Failure................................................................... 20
3.5.3 System Failure .......................................................................................................... 21
3.5.4 Network failures ....................................................................................................... 21
3.5.5 Encryption ................................................................................................................ 21
4. Online Payment using Net Banking ................................................................................... 22
4.1 Request redirection to the Net Banking Solution with Payment Details ........................ 22
4.2 Payment Details Confirmation ...................................................................................... 23
4.3 Payment Transaction Status ......................................................................................... 24
4.4 Request redirection to the URA system with Payment Transaction Details ................... 24
4.5 Other Details ................................................................................................................ 24
4.6 Exception Cases............................................................................................................ 24
5. Requirements from the Bank ........................................................................................... 26

4 Version 1.6
1. Summary of Changes Version 1.6
This is a baseline release of the Technical proposal and this section gives a summary of
noteworthy changes that have been made to v1.5.

1.1 Assumptions Made

Lists the assumptions that have formed the basis of this implementation proposal section 2.1

1.2 Bank Account field

Removed “Bank Account” due to the confusion it is creating in the registration process –
Section 3.1.1.1.

1.3 CSV File Name Format exchanged

In order to have the files managed easily if arranged by name the date part of batch filename
for both payment registration and payment transaction has been changed to from DDMMYY
to YYYYMMDD Section 3.1.1.2 and 3.3.1.2

1.4 Codes for dishonored cheques

The cheque Number and Reason for dishonoured cheques has been added as fields to the
payment transaction batch submitted to URA. Section 3.3.1.3
1-Insufficient Funds
2-Wrong signatory
9-Other>

1.5 Secure FTP Acknowledgement to be done via status logging

Renaming files in the FTP environment poses a security risk since such permissions will is
requires one to be given full control. Instead of implementing notification via a rename of the
files as proposed earlier, two log files will be created daily. One will be used by the bank to
record the success status of the uploaded files and the second will be used by URA to record
the success status of the files sent by the bank. Details can be found in sections 3.4.4.3, 3.4.3.5

1.6 Daily bank of Uganda file

In order to complete the business around payments, a batch file is required for notification of
the amount of money that has been remitted to the consolidated fund from the accounts
held. Section 3.4.2.3

1.7 End of Day files

3.4.2.1 – Registration and Transaction End of day files added to include all registrations
created by URA and transactions handled by the bank respectively

1.8 Https acknowledgement field changes

3.4.3.3.1 – Added Field “ErrorDesc” to Data acknowledgements in https communication
3.4.3.4. – Added Field “FileType to distinguish between, batch, End of Day and BOU file and
“ErrorDesc” to Data acknowledgements in https communication
 3.4.4.4. – Added Field “FileType to distinguish between batch and End of Day registration files
and “ErrorDesc” to Data acknowledgements in https communication

1.9 Status Clarification

3.1.1.3. – Note on Status... X and T will be set by the bank and “transaction” changed to
record. Net banking registrations will be included in the batches created by URA
RTGS comment added
3.2.1.3 – Section added to explain the Expiry Status

1.10 Others

3.5.4 – Note on raising reliability of the communication

3.5.5 – Note on Encryption of files in the SFTP Communication

6 Version 1.6
2. Introduction
The payment solution will offer features to enable the payment of taxes to URA. It involves
having payment registrations shared with the bank, the bank receiving and verifying the payment
and then the bank notifying URA of payment transactions completed. Currently two payment
methods have been considered viz - over the counter payment and Net-banking.

The sections below describe the two payment methods starting with over the counter. They
detail the data formats involved, transmission and how acknowledgement of data exchanges are
to be achieved. Transmissions of data shall be through either Secure FTP or HTTPS, as described
in the over the counter method, to which a bank shall choose one.

Listed below are the assumptions that have been used when coming up with this proposal

2.1 Assumptions

1. Against any payment registration, the taxpayer can pay only once.

2. Against any payment registration, taxpayer can use only ONE instrument for payment
(either CASH or CHEQUE)

3. A single Instrument such as a cheque can be used to pay for multiple payment
registrations

4. The bank will Expire unclaimed transactions using the expiry date provided and they will
be made unavailable for further processing

5. If taxpayer is paying through cheque then he can use only one cheque not multiple
cheques. If he wants to pay through multiple cheques he has to register separate
payment registration for each cheque.

6. For reconciliation we are considering only the amount declared by taxpayer during
payment registration and the payment amount received in Till Sheets against that
payment registration. If these amounts match payment record shall get reconciled
automatically, else payment reconciliation authority has to confirm with bank (he can
also modify the amount as per feedback received from bank) and manually reconcile the
payment record in eTax.

7. In Till sheet, if we receive the record for some payment registration which has already
been reconciled in eTax, it shall be ignored i.e. the process shall be idempotent. However
if the amounts are different, which should be rare, it shall be notified as an exception for
further action and the system will not take any action given its implications on the
accounting. This will trigger a root-cause analysis activity by URA staff with the
concerned bank for remedial action

7 Version 1.6
 3. Over the Counter Payment
The taxpayer can make a registered payment over the bank counter. The taxpayer goes to the
bank office with the Payment Registration Acknowledgement he obtained at the time of
payment registration from either URA web portal or URA office or MDA office.

3.1 Payment Registration Data Interface

The Payment Registration data generated by URA for a specific bank, during the time interval
stated in the transmission frequency, is organized into a batch and subsequently sent to the Bank
specific URL. This information enables the bank verify the registrations and accept payments
being made by these clients. The details of the Payment Registration batch and its data elements
are given below.

3.1.1 Batch Details

3.1.1.1 Data Elements

Mandatory / Conditional /
Data Element Description Data Type Max Length
Nullable
PRN Payment Registration Number Alphanumeric 15 Mandatory
Taxpayer Identification
Number (If the taxpayer is
registered with URA this would
TIN Alphanumeric 15 Conditional
be provided else only the
taxpayer name would be
provided)
Taxpayer Name Taxpayer Name Alphanumeric 300 Mandatory
Numeric
Amount Amount (without 15 Mandatory
decimal)
Date
PR Date Payment Registration Date 10 Mandatory
(dd/mm/yyyy)

A - Available (in case of new

PRN record, it is available for
payment transaction)
Status Alphanumeric 1 Mandatory
X – Expired
C – Cancelled
T – Transacted

Date
Expiry Date Expiry Date 10 Mandatory
(dd/mm/yyyy)

3.1.1.2 File Format

 The format of the file shall be .CSV (Comma Separated Value)

 The file name format : <ura bank short code > <date(yyyymmdd)> <counter -3 digits>
o e.g. WFG20090624001.CSV
 URA will maintain the bank short code. In the above WFG is short code for Wells Fargo Bank.

 At payment registration, the taxpayer shall select a bank where he will make payments; URA
shall then generate bank specific batch files containing Payment Registration information to
be sent to that bank.

3.1.1.3 Other details

 In the data elements, Status indicates the status of the record. If it is “A” then, the bank
shall allow the transaction on that record and “C” then that Payment Registration record is
cancelled. ”X” and “T”, which stand for expired and Transacted respectively, have been
added to complete the list of possible values but will never appear in records sent by URA.
The bank will maintain these and update them appropriately after transacting or when the
expiry date is realized before the registration is claimed. Against these the bank should not
allow processing as well.

 Batches shall be created to contain payment registration transactions generated during the
frequency interval configured in the transmission i.e. each Batch file should have the
incremental registration. Blank batches will not be created

 The batch file may contain the records for the new payment registration as well as the
status updates for the existing payment registration records. In case of new payment
registration, banks would need to insert them in their local database. In case of existing
payment registration record, banks would need to update the status detail for that payment
registration record in their database.

 At the time of Payment Registration, the taxpayer shall be asked about the mode of
payment which can be either “Bank Counter” or “Net Banking”. In case of “Net Banking”
based payment, the payment registration data will be included in the Payment Registration
Batch files and the bank should ensure the upload system is idempotent to avoid
duplication of the records. If it is expected that RTGS will be used for payment, the taxpayer
will indicate so and a payment registration specific for such wire transfers will be created by
the system having the required details.

 The 3-digit counter in the file name format will reset every day.

3.1.1.4 Example

The file “WFG20090624001.CSV” shall contain data as below.

2090000000500,0000002345,Smith John, 1000,01/06/2009,A,22/06/2009

2090000000601,0000005678,ABC Corporation, 2000,02/06/2009,C,23/06/2009
2090000000815,0000003593,XYZ Firm, 3000,04/06/2009,X,25/06/2009

9 Version 1.6
3.2 Payment Verification

The bank has to verify the status of data before transacting against any Payment
Registration Number. Verification process involves entering the PRN which retrieves
details stored at the bank and then confirming that they tally with the physical
document presented in every aspect.

3.2.1 Status Check

3.2.1.1 Available – A/ Cancelled – C

“A” and “C” are the only two possible values that will appear in the status field of the
payment registration record generated by URA. Subsequent processing is only
permissible for records have status “A” ONLY. The Cancelled status is provided for the
bank to change the status of an existing record to “C” so that it becomes unavailable for
processing.

3.2.1.2 Transacted – T

This status is set by the Bank. Once a payment registration has been transacted at the ,
its status should be changed to “T” so that the bank does not allow another transaction
on that record.

3.2.1.3 Expired – X

This is set by the Bank using the expiry date supplied in the payment registration record.
At the start of every day (mid night) a process should be put in place that will expire all
records for which the date is concluded by changing the status to “X”. No further
processing is permissible against such records.

3.2.2 Payment Registration Details Check

Whenever the Taxpayer appears to make a payment for a payment registration

acknowledgement, the bank teller has to check and verify all details on the document
presented against the details that were received from URA. The details to be verified
are.

o Payment Registration Number

o TIN (if applicable)
o Taxpayer Name
o Amount
o Payment Registration Date
o Taxpayer Account Number (if applicable)
o Validity

10 Version 1.6
 3.3 Payment Transaction Details

After receiving from the taxpayer, payment against Payment Registration

acknowledgement, the bank has to prepare Data on Payment Transaction Details into
batch files and have them transmitted to URA at the rate stated frequency interval of the
transmission.

3.3.1 Batch Details

The batch data will be sent to URA by the bank on regular basis at the stated frequency
interval specified in the transmission section. In addition, after midnight, the bank shall
prepare a consolidated file for all payment transactions (Over the Counter, Net-banking or
otherwise) for the day and have them submit to URA. The details about the data element
of the batch files shall be as below.

3.3.1.1 Data Elements

Mandatory / Conditional /
Element Description Data Type Max Length
Nullable
PRN Payment Registration Number Alphanumeric 15 Mandatory
Taxpayer Identification Conditional (Depends on Tax
TIN Alphanumeric 15
Number Type code)

Amount Paid Paid Amount Numeric 15 Mandatory

Date
Date Paid Paid Date 10 Mandatory
(dd/mm/yyyy)
Date
Value Date Value Date 10 Mandatory
(dd/mm/yyyy)
R – Received (Cheque)
C– Credited the Amount (Cash,
Status Realization in case of Cheque) Alphanumeric 1 Mandatory
D –Dishonored

Bank Branch Code (As assigned

Bank Branch Code by Bank of Uganda – Assumed Alphanumeric 20 Mandatory
to contain the BOU Bank code)
Bank Transaction
Bank Transaction Number Alphanumeric 20 Mandatory
Number
Cheque Number for
ChequeNumber Alphanumeric 15 Conditional(Status==D)
dishonored cheque
Reason in case of Dishonored
Reason Numeric 1 Conditional(Status==D)
check

11 Version 1.6
 3.3.1.2 File Format

 The format of the file shall be .CSV (Comma Separated Value)

 The file name format : URA<ura bank short code> <date(yyyymmdd)> <counter -3 digits>
o e.g. URAWFG20090624001.CSV

3.3.1.3 Other Details

 In the data elements, Status indicates the status of the payment against the record. If the
bank has received the payment (in case of Cheque) then the status will be “R”. If the bank
has credited the amount for the payment received through cash or through the Cheque
deposited earlier or EFT or Cheque of same bank or Banker’s Cheque, or Demand Draft,
then the status will be “C”. If the cheque is dishonored, then the status will be “D”.
 Bank has to ensure that if the payment is accepted against any Payment Registration
Number its status is changed appropriately so that another transaction cannot be done
again against that Payment Registration Number.
 The 3-digit counter in the file name format will reset every day.
 All batch files transmitted by the bank should have the payment transactions transacted
over the bank counter and through Net Banking.
 Bank is also required to send an End of Day file created after midnight containing of all
transactions (Over the Counter and Net Banking) during the day. The format of the End of
Day file would be similar to the batch files.
 Each Batch file should have the incremental payment transaction records except for the End
of Day file which should have the all payment transaction records for the day.
 A Cheque number is required when it has been dishonored. In the data elements, Reason
applies in the case where a cheque has been dishonored i.e. status = “D”. If the cause is
“insufficient funds”, the reason will have 1. If the cause is “wrong signatures” then the
reason will be is 2. All other reasons which have not been classified elsewhere will be 9.

3.3.1.4 Example

2090000000500,0000002345,1000,20/06/2009,20/06/2009,R,<BOUBankBranchCode1>,BANKTRNS0000001
2090000000601,0000005678,2000,20/06/2009,20/06/2009,C,<BOUBankBranchCode1>,BANKTRNS0001234
2090000000815,0000003593,3000,21/06/2009,21/06/2009,D,<BOUBankBranchCode2>,BANKTRNS0004567

3.4 Transmission and Acknowledgement Details

These two go hand in hand and deserve special treatment because of its dependant on the
method chosen. A bank can choose to use secure FTP or HTTPS to achieve transmission of
the batch file and their subsequent acknowledgement. Specific implementations are
detailed in the sub sections that follow.

12 Version 1.6
 3.4.1 Transmission Frequency

 The frequency interval for transmitting the file will be every 5 minutes

 Each file would contain the incremental data over the last file.

 If there is no incremental data over the specified interval since the last
transmission, the empty batch file shall not be sent.

 The exception is the “End of the Day” and “BOU Transfer” which will be
transmitted once at the end of day.

3.4.2 End of Data Exchanges

There shall be two End of Day file and a Bank of Uganda transfer file that will be
exchanged at the end of the day.

3.4.2.1 Payment Registration End of Day File

Created by URA after midnight, this file will be used by the Bank system for to confirm
that it received all payment registration created during the day. Any omissions will be
identified by the system after going through this file will be uploaded into the Banks
Database. URA will in the same format as that used for the payment registration batch
files(section 3.1.1.1), prepare a consolidated file of all registrations that were notified
during the day.

It is suggested that this file shall be created after midnight to take care of online
payments that may come in after working hours.

The file name format shall be

REGEOD_<3 digit ura supplied bank short code><YYYYMMDD>.CSV
e.g. REGEOD_WFG20090623.CSV

3.4.2.2 Payment Transaction End of Day File

Created by the bank after midnight, this file will be used by the URA system for
reconciliation purposes. Any omissions will be identified by the system after going
through this file. The bank will in the same format as that used for the payment
transaction files (Section 3.3.1.1), prepare a consolidated file of all transactions that
were notified during the day.

It is suggested that this file shall be created at midnight to take care of online payments
that may come in after working hours.

The file name format shall be

TXNEOD_<3 digit ura supplied bank short code><YYYYMMDD>.CSV
e.g. TXNEOD_WFG20090623.CSV

13 Version 1.6
 3.4.2.3 Bank of Uganda Transfer File
At some point as determined by the agreement, funds have to be transferred to the
consolidated account in bank of Uganda. In order to completely take care of the various
scenarios under payment management, the bank will create this file on the day transfers
are made. The file will potentially contain one record unless you have previous payment
transactions that were not remitted on time

This file should be made as soon as a transfer has been completed and please note that
the collections are remitted T+2 (i.e. with a lag of one day between collection and
remittance)

The file name format shall be

BOU_<3 digit ura supplied bank short code><YYYYMMDD>.CSV
e.g. BOU_WFG20090623.CSV

3.4.2.3.1Data Elements

Mandatory / Conditional /
Element Description Data Type Max Length
Nullable
Value date in the Consolidated Date
BOUValueDate 10 Mandatory
fund (dd/mm/yyyy
Date when that revenue was
Collection Value Date
received in the collection 10 Mandatory
date (dd/mm/yyyy
account
SourceAccountNu Account Number from which the
Alphanumeric 15 Mandatory
mber funds are being transferred

Amount Total amount transferred Numeric Mandatory

3.4.2.4 Example

24062009,22062009,0100110083800,16000000000
24062009,21062009,0100110083800,6000000000

3.4.3 HTTPS based Transmission & Acknowledgement

3.4.3.1 Channel
 The transmission channel shall be HTTPS (Hyper Text Transfer Protocol
Secure).
 Type of HTTPS request: POST.
 HTTPS Request Version: HTTP 1.1 and SSL 3.0

14 Version 1.6
 3.4.3.2 URL

The Bank shall provide the URL for the Payment Registration data the be transmitted to.
The format of URL can be as below.

https://bankdomain/subdomain

URA will provide the URL for receiving Acknowledgement and Payment Transaction Data
that the bank will transmit. The format of URL shall be.

https://uradomain/subdomain

3.4.3.3 Acknowledgement by bank of Payment Registration batches from URA

The Bank shall send an Acknowledgement of Payment Registration batches received from
URA by acknowledging each batch. If an acknowledgement for a batch is not received
within the interval stated in the transmission frequency, URA will assume the batch was
not successful and it shall be retransmitted. The bank should ensure that the upload
process is idempotent and avoid creating duplicates.

The medium of communicating this acknowledgement shall be through the request

parameter of the HTTPS request at the given bank specific URL. Details of the data
elements are provided below.

3.4.3.3.1Data Elements of Acknowledgements

Mandatory / Conditional /
Element Description Data Type Max Length
Nullable
R – Payment Registration Batch
FileType Alphanumeric 1 Mandatory
E – End of Day
Name of the file sent to Bank
FileName by URA containing Payment Alphanumeric 20 Mandatory
Registration details
BankCode Bank Code Alphanumeric 8 Mandatory
“ACK” – This status should be
sent when the file is received
Status “ERR” – This status should be Alphanumeric 5 Mandatory
sent when the bank has
detected error in the file.
Description of error
ErrorDesc encountered while uploading Alphanumeric 500 Conditional (Status=”ERR”)
the batch file

15 Version 1.6
 3.4.3.4 Acknowledgement by URA of payment transactions received from Bank

On receipt of the payment transactions file from the Bank, URA shall send an
acknowledgement to the bank in the request parameter of the HTTPS request at the given
Bank URL. The bank should retransmit the batch if it does not receive the
acknowledgement within the stated interval of the transmission frequency. The data
element are listed below

Mandatory / Conditional /
Element Description Data Type Length
Nullable
T – Payment Transaction
FileType E – End of Day Alphanumeric 1 Mandatory
B – Bank of Uganda Transfer
Name of the file sent by Bank
FileName to URA containing Payment Alphanumeric 20 Mandatory
Transaction details
“ACK” – This status should be
sent when the file is received
Status “ERR” – This status should be Alphanumeric 5 Mandatory
sent when the bank has
detected error in the file.
Description of Error
ErrorDesc Encountered while uploading Alphanumeric 500 Conditional(Status==”ERR”)
the batch file

3.4.4 Secure FTP based Transmission & Acknowledgement

URA will provide a secure FTP Server that will be configured with bank specific folders
to be accessed through user name and password. It is recognized that renaming files in
the sFTP environment as previously suggested poses a security risk since such
permissions requires one to be assigned Full control. Instead, notification will be
achieved via log files to be created daily by the party making the notification; one will
be created and updated by the bank to record the success status of the uploaded files;
and the second to be created and used by URA to record the success status of all the
files sent by the bank.

3.4.4.1 Channel

 The transmission channel shall be SFTP (Secure File Transfer Protocol).

 There shall be folders for each participating bank on the SFTP server.
 Each bank participating would be given access to their respective folders.
 Bank specific folder would have two folders
o “Payment_Registration” folder, where URA would place all batch files of
Payment Registration data.
o “Payment_Transaction” folder, where the Bank would upload their batch
files of Payment Transaction and the end of day file.

16 Version 1.6
 3.4.4.2 URL

URA would provide the SFTP URL as well as the user name and password for getting
authenticated to the URA SFTP Server

3.4.4.3 Acknowledgement by Bank of Payment Registration Batches from URA

The Bank will create an acknowledgement log file at the start of each day and
upload it in the Payment_Transaction folder of the URA’s SFTP server.

Banks shall communicate the upload status of each Payment Registration batch file
in this log file immediately after the upload is completed. Banks will have the write
access to the Payment_Transaction folder and E-TAX would have the read.

The format of the log file shall be CSV format and its naming will be in the form:

<3 digit ura supplied bank short code>REGSTATUS_<yyyymmdd>LOG.CSV

e.g. WFGREGSTATUS_20090622LOG.CSV

In this file the bank will append statuses relating to the transmission and upload of
the batch files that will have been attempted. Note that records written prior will
should not be replaced. The format of the record is described in the data elements
section below

3.4.4.4 Data Elements

Mandatory / Conditional /
Element Description Data Type Max Length
Nullable
Time stamp <HHMM> in 24hr when
Time Alphanumeric 4 Mandatory
this record is written
R – Payment Registration Batch
FileType Alphanumeric 1 Mandatory
E – End of Day
Name of batch file to which this
FileName Alphanumeric 15 Mandatory
status relates
Resulting status after download or
upload has been tried
Status Alphanumeric 3 Mandatory
ACK – Successful Acknowledgement
ERR – Error encountered
Optional(applicable when
ErrorDesc Error description Alphanumeric 500
errors are encountered)

17 Version 1.6
 3.4.4.4.1Example
Assume we have Wells Fargo Bank, WFG, batches being received, the sample file
contents may look like:
0931,WFG20090622001,ACK,
1230,WFG20090622002,ACK,
1240,WFG20090831009,ERR,”End of file not found”

The details are described below.

 If the Bank successfully copies the file off/from URA SFTP server, then bank has to append a
record to the log file with status ACK.

 If the Bank identifies some error while uploading the batch file records in their system, then
bank should append a record to the log file with status “ERR” and error message where possible

 When URA system reads a record from the log file with status “ACK” then the file would be
archived for it is assumed that the bank has copied that file into their system.

 When URA system reads a record from the log file with status “ERR” then URA would copy the
correct file and archive the error file.

3.4.4.5 Acknowledgement by URA of Payment Transactions from Banks

URA shall create a bank specific log file at the start of every day at 00:00. The format
of file shall be CSV. This file will be located on the URA SFTP server in the
“Payment_Registration” folder. URA will communicate the upload status of the
Payment Transaction batch files in this log file by appending a record of the status of
each file for which an upload attempt into the system will have been made. E-TAX
would have the write access to the Payment_Registration folder and Banks would
have the read access.

The log file name format for this file will be

<3 digit ura bank short code>TXNSTATUS_<yyyymmdd>LOG.CSV
e.g. WFGTXNSTATUS_20090622LOG.CSV

The same log file will be used for the Payment Transaction, End of day and Bank of
Uganda transfer file and a type field has been introduced to help with the
distinction.

In this file URA system will append statuses relating to the upload status of the batch
files that will have been attempted. The format of the record is described in the data
elements section below

18 Version 1.6
 3.4.4.6 Data Elements

Mandatory / Conditional /
Element Description Data Type Max Length
Nullable
Time Time stamp <HHMM> in 24hr Alphanumeric 4 Mandatory
T – Payment Transaction
FileType E – End of Day Alphanumeric 1 Mandatory
B – Bank of Uganda Transfer
FileName Batch file to which this status relates Alphanumeric 15 Mandatory
Resulting status after upload or
download was tried
Status Alphanumeric 3 Mandatory
ACK – Successful Acknowledgement
ERR – Error encountered
Optional(applicable when
ErrorDesc Error description Alphanumeric 500
errors are encountered)

3.4.4.6.1Example
0931,T,WFG20090622001,ACK,
1001,B,BOU_WFG20090623,ACK,
1246,T,WFG20090622002,ERR,EOF not found
2401,E,EODWFG20090622,ACK,ERR,Error reading file

 If the URA system successfully uploads the records in the batch file placed by the
bank on the URA SFTP server, then it will append a record to the log file with
status ACK.

 If the URA system identifies some error while uploading the batch file records in
the system, a record will be appended to the log file with status “ERR” and the
error message.

 When bank system reads a record from the log file with status “ACK” then the
bank would assuming that the URA system has successfully uploaded that file.

 When bank system reads a record from the log file with status “ERR” then bank
shall copy the correct file again.

 URA system shall archive the files once they are uploaded in URA system or an
error has been reported in the log file.

19 Version 1.6
3.5 Exception Cases

3.5.1 Transmission Failure

3.5.1.1 HTTPS Transmission Failure

 Whenever transmission failure occurs during sending the Payment Registration

Data from URA to bank, URA will maintain the status of each batch and re-send
the failed batch files in the subsequent batch.
 Whenever transmission failure occurs during sending the Payment Transaction
Data from bank to URA, the bank has to maintain the status of each batch and
re-send the failed batch files in the subsequent batch.

3.5.1.2 Secure FTP Transmission Failure

 If the Banks fail to upload the batch files containing Payment Transaction Data
to URA SFTP server, the bank has to maintain the status of each batch and re-
upload the failed batch files in the subsequent batch.

3.5.2 Acknowledgement Failure

3.5.2.1 HTTPS Acknowledgement Failure

 If URA does not get acknowledgment from Bank for the batch file of Payment
Registration data within the stated transmission frequency period, URA will re-
send those files until the acknowledgement is received from the Bank’s system.
If the system fails to get the acknowledgement of all batch files transmitted to
the bank, the End of Day file would need to be sent by Email to an agreed email
address.
 If Bank does not get acknowledgment from URA for the batch file of Payment
Transaction data within the stated transmission frequency period, Bank will re-
send those files until the acknowledgement is received from the URA’s system. If
the Bank fails to get the acknowledgement of all batch files transmitted to URA,
the End of Day file would need to be sent by Email to an agreed email address.


3.5.2.2 Secure FTP Acknowledgement Failure

 If URA does not get acknowledgment from Bank for the batch file of Payment
Registration data within the stated transmission frequency period, URA will keep
those files on the SFTP server until the acknowledgement is received from the
Bank’s system. If the system fails to get the acknowledgement of all batch files

20 Version 1.6
 uploaded on the SFTP server, the End of Day file would need to be sent by Email
to an agreed email address.
 If Bank is not able to upload the batch file of Payment Transaction data on the
URA SFTP server within the stated transmission frequency period, Bank will re-
upload those files in the subsequent batch. If the Bank fails to upload all batch
files to URA SFTP server, the End of Day file would need to be sent by Email to
an agreed email address.

3.5.3 System Failure

 If there is a network failure or system failure at URA, URA will provide the Payment
Registration Data manually on any of the preferred media (CD, DVD, Magnetic Tapes,
etc.).
 Similarly if there is a network failure or system failure at Bank, Bank would need to
provide the Payment Transaction Data manually on any of the preferred media (CD,
DVD, Magnetic Tapes, etc.).

3.5.4 Network failures

The public network is currently considered as the medium of communication and could
be unavailable at certain times. Section 3.5.3 provides manual fall back mechanisms. It is
envisaged that in the next release consideration should be given to the possibility of
setting up point to point leased lines to guarantee the reliability and performance of the
Communication.

3.5.5 Encryption
SFTP file encryption has not been considered and will be the subject of the next release
after the pilot phase. It is proposed that we explore the use of Advanced Encryption
Standard (AES) and develop procedures around creation and exchange of the required
keys.

21 Version 1.6
 4. Online Payment using Net Banking

The taxpayer will open the URA portal and can make payment online using Net Banking.

4.1 Request redirection to the Net Banking Solution with Payment Details

1. The taxpayer will open the DTD portal and will submit the information of the payment
and he will be provided the list of the banks through which he can make the payment.
2. After clicking the bank, he will be redirected to the Login Page of Bank’s Net Banking
Solution with the Payment Registration Data.

3. HTTPS Request Type: POST

4. HTTPS Request Version: HTTP 1.1 and SSL 3.0
5. For redirecting the taxpayer to bank, the bank has to provide HTTPS URL.
6. The list of request parameters passed in the HTTPS request are as given in the table
below:
Max Mandatory
Sr. Parameter Name Label Name (Description) Data format
Length / Nullable
Payment Registration
1 PRN Alphanumeric 15 Mandatory
Number
Date
2 PR_Date Payment Registration Date 10 Mandatory
(dd/mm/yyyy)
Taxpayer Identification
Number (If the taxpayer is
registered with URA this
3 TIN Alphanumeric 15 Nullable
would be provided else
only the taxpayer name
would be provided)
4 Taxpayer_Name Name of Taxpayer Alphanumeric 300 Mandatory
Numeric
5 Amount Amount (without 15 Mandatory
decimal)
Payment Registration
Status (The status of the
Payment Registration
would always be “A”, i.e.
when the taxpayer is
redirected to the Bank’s
6 Status Alphanumeric 1 Mandatory
Net Banking System. In
case of other status the
URA system would not
allow the taxpayer to be
redirected to the Bank’s
Net Banking system.)

7 Bank_Account_Number Bank Account Number Alphanumeric 20 Optional

Payment Registration
8 Expiry_Date Date 10 Mandatory
Expiry Date

22 Version 1.6
 4.2 Payment Details Confirmation

o After redirecting to Bank Portal, taxpayer shall be required to provide the Net
Banking user name and password on the login page.
o If the taxpayer is authenticated successfully Bank’s Net Banking Solution shall display
the following Payment Registration details on a web page:
 Payment Registration Number
 Payment Registration Date
 TIN
 Taxpayer Name
 Amount

Prototype of the Screen to be displayed:

Name of Taxpayer

Payment Registration Number

Payment Registration Date

Taxpayer Identification Number

Amount

o Bank shall provide option for various accounts if applicable. e.g. Savings, Current,
etc.
o Bank can provide the level of authorization in its portal (transaction password).
o In cases where the bank has multiple level of authorization and it cannot be
completed in real time, bank would need to send the notification of the final
authorization of the net banking transaction and crediting of the payment in URA’s
account through the batch files.
o If the Payment Registration has expired before the final level of authorization, the
bank’s system should not allow the payment to be transacted.

23 Version 1.6
 4.3 Payment Transaction Status

o After the confirmation of payment, Bank has to provide the transaction status of
that payment as well as the Bank Receipt of the transaction. Referenced at (Payment
Transaction Details)

4.4 Request redirection to the URA system with Payment Transaction Details

1. After doing the payment by the taxpayer, the bank shall redirect the taxpayer to the
given HTTPS URL of URA portal with the Payment Transaction data.

a. Type of HTTPS Request: POST

b. HTTPS Request Version: HTTP 1.1 and SSL 3.0

2. For the redirecting the URL to URA, URA will provide HTTPS URL.
3. The details on the HTTPS request parameters for the Payment Transaction data are
given below:

Max Mandatory /
Sr. Parameter Name Description Data format
Length Nullable
Payment Registration
1 PRN Alphanumeric 15 Mandatory
Number
Numeric
2 Amount_Paid Amount (without 15 Mandatory
decimal)
Date Mandatory
3 Date_Paid Payment Date 10
(dd/mm/yyyy)
Bank Branch Code Mandatory
4 Bank_Branch_Code (Assumed to include Alphanumeric 20
Bankcode)
Bank Transaction Mandatory
5 Bank_Tr_No Alphanumeric 20
Number
Payment Status Flag (S
6 Status Alphabetic 1 Mandatory
– Success, F – Fail)

4.5 Other Details

1. Banks would be required to send the Payment Transaction details for the Net Banking
transactions along with the counter payment transactions in the batch file.

4.6 Exception Cases

 If the user is able to successfully complete the payment registration but the network
breaks down while redirecting to the Bank’s Net Banking System URL
 Taxpayer should also be provided the link against each Payment Registration record
to traverse to the Bank’s Net Banking System’s URL. In such a case taxpayer can

24 Version 1.6
 again click on the link for e-Payment against the Payment Registration record to go
to the Bank’s Net Banking System.
 If the payment registration has expired, cancelled or transacted, then the URA
system should disable the link for traversing to the Bank’s Net Banking system.

 If the user is successfully redirected to the Bank’s Net Banking System URL but he is not
able to complete the payment transaction on Net Banking System due to network
problem
 Taxpayer should be required to go to his login account in URA Web Portal and click
on the e-Payment link against the respective Payment Registration record to again
go to the Bank’s Net Banking System.
 If the payment registration has expired, cancelled or transacted, then the URA
system should disable the link for traversing to the Bank’s Net Banking system.

 If the user has successfully completed the payment transaction but the link breaks down
while redirecting the user to URA Web Portal
 The payment notifications would come to URA in batch files from bank, and the
taxpayer account maintained by URA would be updated with the payment
information whenever it is received from the bank.

25 Version 1.6
5. Requirements from the Bank

 Destination HTTPS URL of Staging Environment and Production Environment for

o Transmitting Payment Registration Details
o Transmitting acknowledgement for Payment Transaction File
o Net Banking System

 Guidelines for testing on Staging Environment

 Dummy Bank Account Number with Net Banking user name and password on Staging
Environment

 Encryption Libraries (JAR files) and symmetric key for encryption to encrypt the data
transmitted over the network.

 Payment receipt with unique Bank payment transaction number.

 Reprint option for Payment Receipt in case of network failure.

 Payment Registration Verification

o Only one transaction on a payment registration number.
o No transaction against expired and cancelled payment registration records.
o Amount should be equivalent to acknowledgement
 Bank/Branch Codes with Description.

26 Version 1.6