ABC AGENCY BANKING PROJECT

Extra Services Technical Flow Document

Definition of Terms
The below acronyms are used throughout the document with the following meanings:

ABC Agent Banking Company

ANM Agency Network Manager

API Application Programming Interface

FT Funds Transfer

IB Internet Banking

IP Internet Protocol

MB Mobile Banking

NSSF National Social Security Fund

POS Point of Sale (device)

SABS Shared Agency Banking System

UBA Uganda Bankers’ Association

Revision History
Version Date Author Brief description
1.0 1​st​ Jul, 2020 Kelvin K. Kinyunye Prepared the initial draft.
1.1 2​nd​ Jul, 2020 Billy Owire Reviewed the initial draft.
1.2. 15​th​ Jul, 2020 Kelvin K. Kinyunye Added process flows for remittance,
school pay
1.2 16​th​ Jul, 2020 Billy Owire Reviewed version 1.2 for correctness
Purpose
This document contains the technical flow for the new proposed services through the Shared Agent
Banking System (SABS). The SABS is the middleware which connects the ABC channels i.e. POSs,
mobile applications, internet banking, etc to various member banks and to the 3​rd​ party providers.

Intended Audience
• All UBA member banks joining the SABS Platform

• SABS Integrators and aggregators on the web service Interface.

Objective and Scope

• To provide sufficient technical details for a seamless integration to the SABS Platform. This
document version will cover the following transactions:

4
Contents
Definition of Terms 2

Revision History 3

Purpose 4

Intended Audience 4

Objective and Scope 4

Contents 5

NSSF Payment (OBUL as Aggregator) 7

Walk-in Customers 7
Card Customers (OBUL-issued Cards) 7

NSSF Payment (ABC as Aggregator) 9

Walk-in Customers 9
Card Customers (OBUL-issued Cards) 9

Local Remittance/Transfers 11
Token Generation 11
Token Redemption 13

School Fees Payment (via SchoolPay) 15

Walk-in Customers 15
Card Customers (OBUL-issued Cards) 15

Bill/Utility Payment (OBUL as Aggregator) 16

Walk-in Customers 16
Card Customers (OBUL-issued Cards) 16

Bill/Utility Payment (ABC as Aggregator) 18

Walk-in Customers 18
Card Customers (OBUL-issued Cards) 18

Funds Transfer 20
Intra-bank Transfer (Agency Channel Only) 20
Inter-bank Transfer (OBUL as Issuing Bank) 20
Inter-bank Transfer (OBUL as Beneficiary) 20

5
 Appendix A: NSSF Report Format 21

Appendix B: Acceptable Identification for Remittance Customers 23

Appendix C: Required Details of Remittance Sender 24

Appendix D: Required Details of Remittance Recipient 25

6
NSSF Payment (​OBUL as Aggregator)
In this scenario, OBUL shall be responsible for integrating with NSSF and daily sharing with them a
report/statement of all transactions that happened through the agency-banking channel to NSSF’s collection
account at OBUL. (Refer to ​Appendix A​ for a format of the report that the bank should send to NSSF)

ABC shall be responsible for verifying the payee’s NSSF account details before sending the request to OBUL to
perform the accounting entries.

Walk-in Customers
The transaction shall flow as follows:

1. A payee submits their details to an agent who initiates a payment transaction.

2. SABS first sends a request to NSSF to verify the payee’s NSSF account details.
3. SABS lets the agent and payee confirm that the details as fetched from NSSF are correct.
4. Agent confirms details of the transaction and optionally continues to the next step.
5. SABS sends a transaction request to OBUL for accounting entries.
6. The bank performs the following entries, for the principal amount:

DR Agent Float A/c

CR NSSF Collection A/c

and, for the fee:

DR Agent Float A/c

CR ABC Commission Settlement A/c

7. The bank responds to SABS with either a success or failure. In case of success, go to step 8. In case of
failure go to step 10.
8. In case of success, SABS sends a notification to NSSF that a transaction was completed successfully at
OBUL.
9. SABS sends a success response back to the POS which prints a receipt for both the agent and the
customer.
10. In case of failure, SABS sends a failure response back to the POS which prints a receipt for both the agent
and the customer.

Card Customers (OBUL-issued Cards)

The transaction shall flow as follows:

1. A payee submits their card & NSSF details to an agent who initiates a payment transaction.
2. SABS first sends a request to NSSF to verify the payee’s NSSF account details.
3. SABS lets the agent and payee confirm that the details as fetched from NSSF are correct.
4. Agent confirms details of the transaction and optionally continues to the next step.
5. SABS sends a transaction request with customer’s card details to OBUL for accounting entries.
6. The bank performs the following entries, for the principal amount:

DR Customer A/c

7
 CR NSSF Collection A/c

and, for the fee:

DR Customer A/c

CR ABC Commission Settlement A/c

7. The bank responds to SABS with either a success or failure. In case of success, go to step 8. In case of
failure go to step 10.
8. In case of success, SABS sends a notification to NSSF that a transaction was completed successfully at
OBUL.
9. SABS sends a success response back to the POS which prints a receipt for both the agent and the
customer.
10. In case of failure, SABS sends a failure response back to the POS which prints a receipt for both the agent
and the customer.

8
NSSF Payment (ABC as Aggregator)
In this scenario, OBUL shall only be responsible for performing its requisite accounting entries.

ABC shall be responsible for verifying the payee’s NSSF account details before sending the request to OBUL to
perform the accounting entries. Further, ABC shall be responsible for notifying both NSSF and its primary
collection bank of any payments.

Walk-in Customers
The transaction shall flow as follows:

1. A payee submits their details to an agent who initiates a payment transaction.

2. SABS first sends a request to NSSF to verify the payee’s NSSF account details.
3. SABS lets the agent and payee confirm that the details as fetched from NSSF are correct.
4. Agent confirms details of the transaction and optionally continues to the next step.
5. SABS sends a transaction request to OBUL for accounting entries.
6. The bank performs the following entries, for the principal amount:

DR Agent Float A/c

CR ABC Settlement A/c

and, for the fee:

DR Agent Float A/c

CR ABC Commission Settlement A/c

7. The bank responds to SABS with either a success or failure. In case of success, go to step 8. In case of
failure, go to step 11.
8. In case of success, SABS notifies NSSF’s primary collection bank to perform the following entries:

DR ABC Settlement A/c

CR NSSF Collection A/c

9. In case step 8 succeeded, SABS sends a notification to NSSF that a transaction was completed successfully
at NSSF’s primary collection bank. Otherwise, SABS sends a reversal advice to OBUL and skips to step 11.
10. SABS sends a success response back to the POS which prints a receipt for both the agent and the
customer.
11. In case of failure, SABS sends a failure response back to the POS which prints a receipt for both the agent
and the customer.

Card Customers (OBUL-issued Cards)

The transaction shall flow as follows:

1. A payee submits their card and NSSF details to an agent who initiates a payment transaction.
2. SABS first sends a request to NSSF to verify the payee’s NSSF account details.
3. SABS lets the agent and payee confirm that the details as fetched from NSSF are correct.

9
 4. Agent confirms details of the transaction and optionally continues to the next
step.
5. SABS sends a transaction request including customer’s card data to OBUL for accounting entries.
6. The bank performs the following entries, for the principal amount:

DR Customer A/c

CR ABC Settlement A/c

and, for the fee:

DR Customer A/c

CR ABC Commission Settlement A/c

7. The bank responds to SABS with either a success or failure. In case of success, go to step 8. In case of
failure, go to step 11.
8. In case of success, SABS notifies NSSF’s primary collection bank to perform the following entries:

DR ABC Settlement A/c

CR NSSF Collection A/c

9. In case step 8 succeeded, SABS sends a notification to NSSF that a transaction was completed successfully
at NSSF’s primary collection bank. Otherwise, SABS sends a reversal advice to OBUL and skips to step 11.
10. SABS sends a success response back to the POS which prints a receipt for both the agent and the
customer.
11. In case of failure, SABS sends a failure response back to the POS which prints a receipt for both the agent
and the customer.

10
Local Remittance/Transfers
Token Generation
This transaction shall flow as follows (see diagram below):

1. An unbanked customer goes to a SABS agent belonging to OBUL.

2. The customer provides the following to the agent:
a. personal identification document(s) (see ​Appendix B​)
b. the details of the recipient (see ​Appendix C​)
c. the principal amount to be sent in cash
d. the fee amount for sending the principal amount
3. The agent fills in the details as provided and initiates the transaction.
4. SABS sends a request to OBUL to perform the following entries:

DR Agent Float A/c

CR ABC Settlement A/c

and, for the fee:

DR Agent Float A/c

CR ABC Commission Settlement A/c

5. OBUL responds with either a successful or failure response. In case of success, go to step 6. In case of
failure, go to step 9.
6. In case of a successful response, SABS sends a request to ABC’s remittance collector bank to perform the
following entries:

DR ABC Settlement A/c

CR Remittance Collection A/c

7. In case of a failure in the previous step, a reversal advice is sent to OBUL.

8. In case of a successful response from step 6, SABS does the following:
a. Generate and store a secure remittance withdrawal token with a fixed validity period.
b. Send the withdrawal token to the sender via SMS.
c. Send a notification to the remittance recipient to inform them to request for the withdrawal
token from the sender.
d. Send a success response back to the POS which prints a receipt for both the agent and the
remitting customer.
9. In case of a failure response, SABS sends a failure response back to the POS which prints a receipt for
both the agent and the customer.

11
12
 Token Redemption
This transaction shall flow as follows (see diagram below):

1. An unbanked, remittance-recipient customer walks to a SABS agent belonging to OBUL.

2. The customer provides the following to the agent:
a. personal identification document(s) (see ​Appendix B​)
b. their details (see ​Appendix D​)
c. the remittance withdrawal token privately and securely forwarded to them by the sender e.g. via
SMS.
3. The agent fills in the details as provided and initiates the transaction.
4. SABS validates the token and other details provided by the recipient.
5. If details are incorrect, the transaction fails and a failure response is sent to the POS for the agent and
customer to see. A retrial counter is also incremented so that the token can be invalidated in case of
excessive incorrect tries.
6. Else, SABS sends a request to the ABC remittance sponsor bank to perform the following entries:

DR Remittance Escrow A/c

CR ABC Settlement A/c

7. If SABS receives a failed response, the transaction fails and a failure response is sent to the POS for the
agent and customer to see.
8. Else, SABS sends a request to OBUL to perform the following entries:

DR ABC Settlement A/c

CR Agent Float A/c

9. If SABS receives a failed response, the transaction fails and a failure response is sent to the POS for the
agent and customer to see. SABS also sends reversal advice to the sponsor bank.
10. Else, SABS marks the token as already withdrawn and sends a success response back to the POS which
prints a receipt for both the agent and the remittance recipient customer.

13
14
School Fees Payment (via SchoolPay)
In this scenario, OBUL shall only be responsible for performing its requisite accounting entries.

ABC shall be responsible for verifying the payee’s SchoolPay details before sending the request to OBUL to
perform the accounting entries. Further, ABC shall be responsible for notifying SchoolPay of all successful
payments.

Walk-in Customers
The transaction shall flow as follows:

1. A payee submits their details to an agent who initiates a payment transaction.

2. SABS first sends a request to SchoolPay to verify the payee’s SchoolPay details and outstanding fee
balance.
3. SABS lets the agent and payee confirm that the details as fetched from SchoolPay are correct.
4. Agent confirms details of the transaction and optionally continues to the next step.
5. SABS sends a transaction request to OBUL for accounting entries.
6. The bank performs the following entries, for the principal amount:

DR Agent Float A/c

CR SchoolPay Collection A/c

and, for the fee:

DR Agent Float A/c

CR ABC Commission Settlement A/c

7. In case step 6 succeeded, SABS sends a notification to SchoolPay that a transaction was completed
successfully at OBUL. Otherwise, skip to step 9.
8. SABS sends a success response back to the POS which prints a receipt for both the agent and the
customer.
9. In case of failure, SABS sends a failure response back to the POS which prints a receipt for both the agent
and the customer.

Card Customers (OBUL-issued Cards)

The transaction shall flow as follows:

1. A payee submits their card and SchoolPay details to an agent who initiates a payment transaction.
2. SABS first sends a request to SchoolPay to verify the payee’s SchoolPay details and outstanding fee
balance.
3. SABS lets the agent and payee confirm that the details as fetched from SchoolPay are correct.
4. Agent confirms details of the transaction and optionally continues to the next step.
5. SABS sends a transaction request including customer’s card data to OBUL for accounting entries.
6. The bank performs the following entries, for the principal amount:

15
 DR Customer A/c

CR SchoolPay Collection A/c

and, for the fee:

DR Customer A/c

CR ABC Commission Settlement A/c

7. In case step 6 succeeded, SABS sends a notification to SchoolPay that a transaction was completed
successfully at OBUL. Otherwise, skip to step 9.
8. SABS sends a success response back to the POS which prints a receipt for both the agent and the
customer.
9. In case of failure, SABS sends a failure response back to the POS which prints a receipt for both the agent
and the customer.

16
Bill/Utility Payment (​OBUL as Aggregator)
This scenario shall apply if OBUL has an integration with the biller or has any integration that allows the bank to
fulfill the bill (and/or notify the biller) after performing the necessary accounting entries.

Walk-in Customers
The transaction shall flow as follows:

1. A payee submits their bill details to an agent who initiates a payment transaction.
2. SABS first sends a request to the biller to verify the payee’s billing account details.
3. SABS lets the agent and payee confirm that the details as fetched from NSSF are correct.
4. Agent confirms details of the transaction and optionally continues to the next step.
5. SABS sends a transaction request to OBUL for accounting entries.
6. The bank performs the following entries, for the principal amount:

DR Agent Float A/c

CR Biller’s Collection A/c

and, for the fee:

DR Agent Float A/c

CR ABC Commission Settlement A/c

7. The bank notifies the biller and then responds to SABS with either a success or failure. In case of success,
go to step 8. In case of failure go to step 9.
8. SABS sends a success response back to the POS which prints a receipt for both the agent and the
customer.
9. In case of failure, SABS sends a failure response back to the POS which prints a receipt for both the agent
and the customer.

Card Customers (OBUL-issued Cards)

The transaction shall flow as follows:

1. A payee submits their card & bill details to an agent who initiates a payment transaction.
2. SABS first sends a request to the biller to verify the payee’s billing account details.
3. SABS lets the agent and payee confirm that the details as fetched from the biller are correct.
4. Agent confirms details of the transaction and optionally continues to the next step.
5. SABS sends a transaction request with customer’s card details to OBUL for accounting entries.
6. The bank performs the following entries, for the principal amount:

DR Customer A/c

CR Biller’s Collection A/c

and, for the fee:

DR Customer A/c

17
 CR ABC Commission Settlement A/c

7. The bank notifies the biller and responds to SABS with either a success or failure. In case of success, go to
step 8. In case of failure go to step 9.
8. SABS sends a success response back to the POS which prints a receipt for both the agent and the
customer.
9. In case of failure, SABS sends a failure response back to the POS which prints a receipt for both the agent
and the customer.

18
Bill/Utility Payment (​ABC as Aggregator)
This scenario shall apply when OBUL needs ABC to fulfil the bill and/or notify the biller itself.

Walk-in Customers
The transaction shall flow as follows:

1. A payee submits their bill details to an agent who initiates a payment transaction.
2. SABS first sends a request to the biller to verify the payee’s billing account details.
3. SABS lets the agent and payee confirm that the details as fetched from the biller are correct.
4. Agent confirms details of the transaction and optionally continues to the next step.
5. SABS sends a transaction request to OBUL for accounting entries.
6. The bank performs the following entries, for the principal amount:

DR Agent Float A/c

CR ABC Settlement A/c

and, for the fee:

DR Agent Float A/c

CR ABC Commission Settlement A/c

7. The bank responds to SABS with either a success or failure. In case of success, go to step 8. In case of
failure, go to step 11.
8. In case of success, SABS notifies the biller’s primary collection bank to perform the following entries:

DR ABC Settlement A/c

CR Biller’s Collection A/c

9. In case step 8 succeeded, SABS sends a notification to the biller that a transaction was completed
successfully at the biller's primary collection bank. Otherwise, SABS sends a reversal advice to OBUL and
skips to step 11.
10. SABS sends a success response back to the POS which prints a receipt for both the agent and the
customer.
11. In case of failure, SABS sends a failure response back to the POS which prints a receipt for both the agent
and the customer.

Card Customers (OBUL-issued Cards)

The transaction shall flow as follows:

1. A payee submits their card and bill details to an agent who initiates a payment transaction.
2. SABS first sends a request to the biller to verify the payee’s billing account details.
3. SABS lets the agent and payee confirm that the details as fetched from the biller are correct.
4. Agent confirms details of the transaction and optionally continues to the next step.
5. SABS sends a transaction request including customer’s card data to OBUL for accounting entries.

19
 6. The bank performs the following entries, for the principal amount:

DR Customer A/c

CR ABC Settlement A/c

and, for the fee:

DR Customer A/c

CR ABC Commission Settlement A/c

7. The bank responds to SABS with either a success or failure. In case of success, go to step 8. In case of
failure, go to step 11.
8. In case of success, SABS notifies the biller’s primary collection bank to perform the following entries:

DR ABC Settlement A/c

CR Biller’s Collection A/c

9. In case step 8 succeeded, SABS sends a notification to the biller that a transaction was completed
successfully at the biller’s primary collection bank. Otherwise, SABS sends a reversal advice to OBUL and
skips to step 11.
10. SABS sends a success response back to the POS which prints a receipt for both the agent and the
customer.
11. In case of failure, SABS sends a failure response back to the POS which prints a receipt for both the agent
and the customer.

20
Funds Transfer
The scope of funds transfers facilitated through SABS include:

● Intra-bank & Inter-bank FTs initiated from agency banking POS devices
● Inter-bank FT initiated from OBUL’s MB channels
● Inter-bank FT initiated from OBUL’s IB channels
● Bulk inter-bank FT initiated from other internal systems at OBUL’s

All the above scenarios shall be made possible by having OBUL integrate with ABC to enable SABS to perform the
following transactions.

ABC requires OBUL to provide it with transaction types that SABS can send to perform the entries as listed on the
following table (refer to the blue column under ​Accounting Entries ​column).

Intra-bank Transfer (Agency Channel Only)

This transaction shall be initiated by an agent for a customer who comes with a card and wants to transfer money
from their bank account to another beneficiary account in the same bank as the customer. The flow of this
transaction shall be as follows:

1. A customer presents their card and beneficiary account details to an agent who initiates a transfer
transaction.
2. SABS lets the agent and customer confirm the transaction details including the charge details.
3. Agent confirms details of the transaction and optionally continues to the next step.
4. SABS sends a transaction request to OBUL for accounting entries.
5. The bank performs the following entries, for the principal amount:

DR Customer A/c

CR Beneficiary A/c

and, for the fee:

DR Customer A/c

CR ABC Commission Settlement A/c

6. The bank responds to SABS with either a success or failure.

7. In case of failure, SABS sends a failure response back to the POS which prints a receipt for both the agent
and the customer.
8. Else, SABS sends a success response back to the POS which prints a receipt for both the agent and the
customer.

Inter-bank Transfer (OBUL as Issuing Bank)

This transaction shall be initiated from:

● A POS by an agent for a customer with OBUL-issued card

● OBUL’s MB channels
● OBUL’s IB channels

21
 ● Other internal systems at OBUL (NB: bulk file transfer supported)

Inter-bank Transfer (OBUL as Beneficiary)

This transaction shall be initiated from:

● A POS by an agent for a customer with another bank’s card sending money to a/an OBUL beneficiary
account
● Another bank’s MB channels for a beneficiary account at OBUL
● Another bank’s IB channels for a beneficiary account at OBUL
● Another bank’s internal systems for beneficiary account(s) at OBUL (NB: bulk file transfer supported)

22
NOTE: Assume OBUL = Bank X for all scenarios. Additionally, Bank Y represents any
other distinct SABS member bank that could also be involved in an FT transaction.

ABC-SABS FUNDS TRANSFER SPECIFICATION (HIGH-LEVEL)

ISSUING
BENEFICIARY
(CARD OWNER'S) ACCOUNTING ENTRIES
BANK
BANK
PRINCIPAL:
DR Card A/c
NOTES:
CR Beneficiary A/c

BANK X BANK X N/A Amount Settlement

COMMISSION:
-- Issuing Bank to
DR Card A/c
Beneficiary Bank (if
CR Commission
different)
Settlement A/c
PRINCIPAL: For agent acquired
DR Card A/c transactions, the
CR Settlement A/c commission shall be
PRINCIPAL:
BANK X BANK Y DR Settlement A/c split amongst:
COMMISSION: -- Acquiring Bank
CR Beneficiary A/c
DR Card A/c -- Issuing Bank (if
CR Commission different from
Settlement A/c Acquiring Bank)
PRINCIPAL: -- ABC
DR Card A/c -- Agent
CR Beneficiary A/c
PRINCIPAL:
BANK Y BANK X DR Settlement A/c
COMMISSION:
CR Beneficiary A/c
DR Card A/c
CR Commission
Settlement A/c

23
Appendix A: NSSF Report Format
If the bank wishes to hold the NSSF collection account, the bank has to send a report with the following
information to NSSF every day.

24
25
Appendix B: Acceptable Identification for Remittance Customers
The following are the valid identification documents for remittance customers:

1. National ID
2. Passport
3. Driving Licence
4. Phone Number (i.e. possession of token)

26
Appendix C: Required Details of Remittance Sender
1. National ID number (optional)
2. Mobile Number

27
Appendix D: Required Details of Remittance Recipient
1. National ID Number (optional)
2. Mobile Number
3. Name

28