Point-of-sale Airtime
 
 

API Help

Getting started:

The purpose of the interface is to provide a common platform that is language independent and allows programmers to draw Airtime stock in real time without having to learn any new code. Drop a txt file into the Request folder and see the results in the Result folder. It's that simple.
Place a file in the Request folder called Request.txt (C:\Airtime_API\Request)

The Request.txt file is a pipe | delimited file and must contain the following sequence of information:
  • Supplier
  • Voucher Face Value
  • Quantity vouchers
  • XXX (Your own unique reference number for this order) 
Example:

vodacom|2|10| XXX|

is a (first) order for 10 X vodacom R2.00 vouchers (Note the BLANK after YOUR unique reference number in the VERY FIRST order only)
 

The Result:
 

.txt file

Any results from the Request will be found in the Result folder.

The name of the file will be xxx.txt (where xxx is the Order Number (date and timestamp) of the file being received). This is the received file but AFTER decryption.

This .txt file will contain the following relevant information:

Header record

H|Order Number


Detail Records

D|Supplier|FaceValueinRands|Serial Number|Pin Number|Cost Price incl vat


Balance Record (OpenToBuyValue)

B|28526.95
 

So a typical received file will look like this (after decryption):


H|2011070513100898|
D|vodacom|2|8108019420|165947081740|1.82|
D|vodacom|2|3149459421|985422406765|1.82|
D|vodacom|2|064224075|838930024176|1.82|
D|vodacom|2|4648267647|838328164053|1.82|
D|vodacom|2|1501673618|828196093187|1.82|
D|vodacom|2|8189661468|613784177907|1.82|
D|vodacom|2|988365109|114165017122|1.82|
D|vodacom|2|541194818|594788171136|1.82|
D|vodacom|2|8318167416|536516289505|1.82|
D|vodacom|2|156353944|186011156194|1.82|
B|28526.95


ERROR.txt file

The Result folder could also contain an ERROR.txt file in the following format:

xxx|Error description (Where xxx is an error code of 3 characters)


The API Server will not activate an order if ERROR.txt remains in the Result folder.

It is therefore the user's responsibility to act on the error, delete the error.txt file and re- submit the request.


After receiving the very first order you will need to add the last order number that you received successfully, to the next request. So the next file will contain the following sequence of information:
  • Supplier
  • Voucher Face Value
  • Quantity vouchers
  • Your unique reference for this order
  • Last Order Number
Example:

vodacom|110|5| ABX|2011070419253036


Other notes:

The request.txt file will always be deleted after a result.

The result will reflect as a successful order OR as an error.

Error Codes (internal)

Comms Failure 17

Critical Error in received file 200 (decryption/ numerics/checksum error, missing info etc)

Error Codes (Received back from Airtime supplier)

nError:whiteINVALIDUSER equate(101)
nError:whiteINVALIDLAST equate(102)
nError:whiteINVALIDPASS equate(103)
nError:whiteINVALIDNETWORK equate(104)
nError:whiteINVALIDSELLVALUE equate(105)
nError:whiteFUNDSEXCEEDED equate(106)
nError:whiteOUTOFSTOCK equate(107)
nError:whiteINVALIDCOUNT equate(108)
nError:whiteTEMPORARY equate(198)
nError:whiteUNKNOWN equate(199)

Notes:
  • When ordering, only the first line of the request file is looked at.
  • In order to fetch vouchers from a particular point in time onwards, omit all other ordering info and put 4 pipes and the Last Order Number only.
i.e.

||||2011070419253036

(Will fetch vouchers from this Last Order Number and will present them in the Result file)

Network Stock
Voucher types we sell must be selected from the list below. Kindly review the pricing and voucher values on the website. Use the voucher name in lower case letters as below. Note that ordering branson will deliver a Virgin voucher and ordering heita will deliver a 8.ta voucher.

Supported: vodacom, mtn,cellc,branson,telkom,worldchat,neotel,worldcall,heita,eskom.