Application Voucher Purchase

Summary

service: appcode

This web service currently provides Five(5) helper methods and four( 4) main methods: ping, getPrices, requestPin and buy (details in the table 1.0 below).

The main methods are the basic methods required by a Vendor(an agency/company buying and selling code on behalf of the University) to connect, get price list, request to purchase application processing vouchers or [en]coded Personal Identification Numbers (pincodes) and actually buy pin codes for reselling to applicants.

The other helper methods(getLevels, checkPrice, getPin, checkSerial and getserial) 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, programLevel, quantity and serialNo) are CaSE SenSitiVe.

Recommended Testing Kit

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	string	apiKey	The apiKey for authenticating your client. Will be used in ping.[^1]	32422...
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	01234
Method	getLevels
Description	This method fetches available pricing levels
Input	Request	string	token	Token received from ping	01234
Output	Return	string	data	List of program levels for selling pin codes.[^2]	DIP HND, UND
Method	checkPrice
Description	This method fetches the price for a given program level code
Input	Request	string	programLevel	3 letter program level code	HND
		string	token	Token received from ping	01234
Output	Return	string	data	Containing programLevel, levelCode and the related price
Method	requestPin
Description	This method submits a request for pin codes to be generated
Input	Request	string	programLevel	3 letter program level code	HND
		int	quantity	Quantity of codes to generate	100
		string	token	Token received from ping	01234
Output	Return	string	code
Method	getSerials
Description	This method fetches serial numbers for requested pin codes
Input	Request	string	token	Token received from ping	01234
Output	Return	string	data	List of pin codes requested and issued to the vendor.[^2]
Method	buy
Description	This method makes a request to buy a pin code
Input	Request	string	serialNo	Serial number for codes	2001001
		string	token	Token received from ping	8000234
Output	Return	string	data	Pin code and passcode for the provided serial number
Method	getPin
Description	This method fetches previously purchased pin code
Input	Request	string	serialNo	Serial number for codes	2001001
		string	token	Token received from ping	8000234
Output	Return	string	data	Pin code and passcode for the provided serial number[^3]
Method	checkSerial
Description	This method checks if serial number is valid
Input	Request	string	serialNo	Serial number for codes	2001001
		string	token	Token received from ping	8000234
Output	Return	string	message	Message indicating the validity of the serial number

Note

1. [^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. [^2]: If none is available, return an empty array
3. [^3]: Calls to this method are idempotent

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/' \
--form 'userName=<YOUR_USERNAME>' \
--form 'password=<YOUR_PASSWORD>' \
--form 'action=getApiKey' \
--form 'service=appcode'

With the response:

{
    "apiKey": "20158010……....",
    "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: appcode for all admission voucher related methods.

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

curl --location --request POST 'https://TEST/' \
--form 'action=ping' \
--form 'service=appcode' \
--form 'apiKey=20158010808468caa2248c3546dba58fe79b3853c70696d977b1b215469a88e14fbf9eb91331'

With the response below:

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