Skip to content

Basic School Application Voucher Purchase

Summary

service: basicapp

This web service currently provides 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 School) 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. A vendor may also be required to send advice for each transaction to the school.

The other helper methods(getLevels, checkPrice, getPin, checkSerial, getserial, buyDirect, sendAdvice, requestRevoke and requestReinstate) have been added for your convenience.

Quick

  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.
  5. 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.
  6. All request parameter names (userName, password,apiKey, token, schoolLevel, quantity and serialNo) 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.

Web service specification table: 1.0

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] request 32422...
Method ping
Description This method is used to test that connection is alive and and also 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 school levels for selling pin codes.[^2] DCL,KNL,LPL,UPL,JSL,FJL
Method checkPrice
Description This method fetches the price for a given school level code
Input Request string schoolLevel 3 letter school level code JSL
string token Token received from ping 01234
Output Return string data Containing schoolLevel, levelCode and the related price
Method requestPin
Description This method submits a request for pin codes to be generated
Input Request string schoolLevel 3 letter school level code JSL
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 voucher 2001001
string token Token received from ping 8000234
Output Return string data Pin code and passcode for the provided serial number
Method buyDirect
Description This method makes a request to buy a pin code or voucher directly without a serial number.
Input Request string schoolLevel 3 letter school level code JSL
string token Token received from ping 8000234
Output Return string data Pin code, passcode,serial number and School Level code provided
Method getPin
Description This method fetches previously purchased pin code
Input Request string serialNo Serial number for voucher 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 voucher 2001001
string token Token received from ping 8000234
Output Return string message Message indicating the validity of the serial number
Method sendAdvice
Description This method sends advice for each pin code purchase in order to Notify the beneficiary with application instruction
Input Request string serialNo Serial number of voucher 2001001
string payee Payee of the transaction koo foo
string phone Mobile number of beneficiary 05012345678
string email Email of beneficiary koo@mail.com
string transactionNo Unique transaction or reference number 8000234
string token Token received from ping 8000234
Output Return string data smsState and emailState for the provided serial number
smsState Beneficiary sms notification State 200:success, 100:pending
emailState Beneficiary email notification State 200:success, 100:pending
Method requestRevoke
Description This method is used to revoke issued pin code and disable from use by beneficiary
Input Request string serialNo Serial number for voucher 2001001
string token Token received from ping 8000234
Output Return string data serialNo, levelCode and revoke state of the provided serial number
Method requestReinstate
Description This method is used to reinstate revoked voucher and enable it for use by beneficiary
Input Request string serialNo Serial number for voucher 2001001
string token Token received from ping 8000234
Output Return string data serialNo, levelCode and reinstatement state of the provided 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 ENDPOINT>/basicapp/getApiKey/' \
--form 'userName=<YOUR_USERNAME>' \
--form 'password=<YOUR_PASSWORD>'

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: basicapp for all application voucher related methods.

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

curl --location --request POST 'https://<TEST ENDPOINT>/basicapp/ping/' \
--form 'apiKey=20158010808468caa2248c3546dba58fe79b3853c70696d977b1b215469a88e14fbf9eb91331'

With the response below:

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