Skip to content

Basic School Fee Payment Notification

Summary

service: basicfees

This web service currently provides two (2) helper methods and two (2) main methods: (details in the table 1.0 below).

The main methods are the basic methods required by a Vendor(bank/agency/company receiving school fees on behalf of the University) to connect, get student Invoice send and check notification of payment.

Other helper methods have been added for your convenience.

Note

  1. There is a token which will be returned to you after a successful handshake using the ping method. Please use this token for all subsequent calls to the API until it expires.
  2. You can always get another token using your API Key to call ping without passing the token. Authentication is done at host level. It is expected that each request will come from a limited set of known hosts in order to limit access to only known hosts and therefore increase reliability. Your remote ip address will therefore be logged and authenticated by the system each time you make a request to our system.
  3. Encryption is based on http over secure service layer.
  4. The LIVE and TEST endpoints have been communicated with your service integeration team. The maximum length of time you can expect data you generate to persist on the test server is at most one week from the latest Friday.
  5. All request parameter names (userName, password, apiKey, token and invoiceNo) are CaSE SenSitiVe*.

Postman

  1. The service is currently running on the endpoint so you can test once you have received a valid API Key. It is recommended that you familiarise yourself with the integration
  2. If you have any issues, please don’t hesitate to use the contact information above.
METHOD/FIELD TYPE Parameter REMARKS Example
Method getApiKey
Description This method is used to fetch an API Key for establishing connection with the server
Input Request string userName The username associated with your vendor account koo
string password The password associated with your vendor user *****
Output Return JSON object Response object with data property.1 See example section for structure
Method ping
Description This method is used to test that connection is alive and fetch token
Input Request string apiKey Your API Key from getApiKey 32422...
Output Return string Token for subsequent communication 1234567890
Method getInvoice
Description This method fetches unpaid fees invoiced to student. If none available, returns empty array
Input Request string token Token received from ping 1234567890
string studentNo Valid student number 2016000000
string currency Optional: 3-char Currency codes (ISO 4217). Defaults to Ghana Cedi (GHS) GHS/ USD
Output Return JSON object
boolean success
integer recordCount Count of records retrieved
Array items Array of unpaid student invoices
string invoiceState Condition of invoice Invoiced/ Partly Paid
string invoiceNo Unique code used to reference each student invoice
string studentNo Valid student number
string amount Invoiceded amount
string currency 3-char Currency codes (ISO 4217). Defaults to Ghana Cedi (GHS)
string school School level associated with reference invoice
string academicYear Academic year of reference invoice
string fullName Full name of student
Method advice
Description This method sends a notification on payment of fees made by a student
Input Request string token Token received from ping CND1234567
string invoiceNo Number on the selected student invoice received from calling getInvoice
string studentNo Valid student number
float amount
string transactionNo Unique transaction number
string currency Optional: 3-char Currency codes (ISO 4217). Defaults to Ghana Cedi (GHS) GHS/ USD
string stateCode Optional: 3-char State codes2. Defaults to Cleared (CLR) CLR/ ACT
Payee Info Optional If not provided, information from Invoice will be used
string name
string phone
string email
string address
Output Return JSON Object statusCode
message
Method updateState
Description This method updates the state of a previous notification of fee payment
Input Request string transactionNo The transaction number of the advice for which you want to update the state 32422...
Input string stateCode Optional: 3-char State codes2. Defaults to Cleared (CLR) CLR/ ACT
Input string token Token received from ping 1234
Output Return JSON Object statusCode
message
Method reversal
Description This method sends notification of a transaction reversal
Input Request string transactionNo A new transaction number generated for uniquely identifying the reversal ABC1200...
Input string revTransactionNo The transaction number of the advice for which you want to reverse DEF3400...
Input string token Token received from ping 1234567890
Output Return JSON Object statusCode
message

Examples

All requests to the server are made as POST requests. An example of making your first call to get the API key to the test server. For example, using the TEST server:

curl --location --request POST 'https://<TEST ENDPOINT>/basicfees/getApiKey/' \
--form 'userName=<YOUR_USERNAME>' \
--form 'password=<YOUR_PASSWORD>'

With the response:

{
    "code": 1,
    "message": "",
    "records": 1,
    "data": {
        "apiKey": "201604629514a88fc3....",
        "message": "API Key generated successfully!"
    }
}

NB: Each of the methods described in the table will be passed as a value for action with the service: fees for all school fee payment related methods.

Another example of pinging the server with the retrieved API key is as follows:

curl --location --request POST 'https://<TEST ENDPOINT>/basicfees/ping/' \
--form 'apiKey=20158010808468caa5...'

With the response below:

{
    "code": 1,
    "message": "You have pinged!",
    "records": 1,
    "data": {
        "message": "Login Successful",
        "token": "<THE_RETURNED_TOKEN_HERE>"
    }
}

  1. This call returns a new apiKey each time it is called. Be sure to save your key to be used in future communications. ↩

  2. The following are the possible transaction state that can be passed with an advice

    1. ACT: This transaction is currently active and has not completed its lifecycle
    2. CLR: Transaction has been cleard. Not likely to receive any further updates
    3. FLD: Transaction failed
    4. COM: Transaction has completed but is not yet cleared

    ↩↩