Scribd
Upload
123 views9 pages

Pinless Airtime API V 1.1.2

This document provides details on using the True African pinless airtime API, including: 1. The prerequisites, request URL, and general request format including required HTTP headers and XML structure. 2. The specific parameters required for each API method, including purchaseAirtime, checkStatus, and checkBalance. 3. The response formats for each API method, including required fields like responseId, status, and code.

Uploaded by

kalibattarichard
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
123 views9 pages

Pinless Airtime API V 1.1.2

This document provides details on using the True African pinless airtime API, including: 1. The prerequisites, request URL, and general request format including required HTTP headers and XML structure. 2. The specific parameters required for each API method, including purchaseAirtime, checkStatus, and checkBalance. 3. The response formats for each API method, including required fields like responseId, status, and code.

Uploaded by

kalibattarichard
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 9

True African

Pinless Airtime API

This document contains Trade Secrets, Commercial, Financial Information or other proprietary information of True African and is Privileged & Confidential. It is considered
exempt from disclosure under the provisions of the Freedom of Information Act and/or other applicable statutes. This information is not to be copied or distributed to persons
outside the evaluation process without the prior written consent of True African
Table of Contents

Contents
1.0 Document History ................................................................................................................................... 3
2.0 Using the API ........................................................................................................................................... 4
2.1 Prerequisites ....................................................................................................................................... 4
2.2 Request URL ........................................................................................................................................ 4
2.3 Request Format................................................................................................................................... 4
2.3.1 HTTP Headers ............................................................................................................................... 4
2.3.2 XML Request Format .................................................................................................................... 4
2.4 Method specific parameters ............................................................................................................... 5
2.4.1 purchaseAirtime method ............................................................................................................. 5
2.4.2 checkStatus method ..................................................................................................................... 6
2.4.3 checkBalance method .................................................................................................................. 6
2.5 Response Format................................................................................................................................. 6
2.5.1 purchaseAirtime ........................................................................................................................... 6
2.5.2 checkStatus .................................................................................................................................. 7
2.5.3 checkBalance................................................................................................................................ 8
3.0 Error Codes.............................................................................................................................................. 9
1.0 Document History

Revision Date Comments Reviewer


6th January 2013 Initial drafting of document Simon Gatonye
9th January 2013 Modified check status method Opad Yusuf
9th January 2013 Changed the request URL Opad Yusuf
11th January 2013 Modified and added error codes and descriptions Simon Gatonye
14th Febuary 2013 Modified and transaction parameter Opad Yusuf
12th March 2013 Opad Yusuf
21st March 2013 Added Mobile Banking requesting phone number Opad Yusuf
06th April 2015 Added Check Pinless Balance Elly Businge
2.0 Using the API

2.1 Prerequisites
To use the API, you must have a username and password which are provided by True
African.

2.2 Request URL


All requests must be submitted to the URL below:
http://169.254.0.100/airtime/pinless/

2.3 Request Format

2.3.1 HTTP Headers


All requests must be submitted in plain XML. Therefore, the
following HTTP headers are required in all XML requests. If these
headers are not present, the request may fail.
Content-Type: text/xml
Content-transfer-encoding: text

2.3.2 XML Request Format


The following is the general format of the XML request. The parameters
below are required for all requests.

Parameter Description
Username This is the username which, together with the password
below, maps your request to your account.
Password This is the password which, together with the username
above, maps your request to your account.
Method This parameter identifies the type of request you are
making.
Below is a sample request to the platform:
<?xml version="1.0" encoding="UTF-8"?>
<request>
<username>sampleUser</username>
<password>samplePassword</password>
<method>purchaseAirtime</method>
</request>

2.4 Method specific parameters


Some methods require specific parameters as part of the request and this
section defines those parameters for these methods.

2.4.1 purchaseAirtime method


In addition to the general parameters required by all methods, this method
requires the following specific parameters:

Parameter Description Example Required


msisdn Specifies the phone number to be 256772744288 Mandatory
recharged
msisdn2 Specifies the phone number that 256782744288 Optional
made the request for recharge
network This specifies the network for MTN Optional
which airtime is being purchased.
value This specifies the value of the 5438 Mandatory
airtime you wish to purchase.

Transaction This specifies a Unique transaction 66544325 Mandatory


id from requesting system.

Below is a sample request to the platform for the purchaseAirtime method:


<?xml version="1.0" encoding="UTF-8"?>
<request>
<username>sampleUser</username>
<password>samplePassword</password>
<method>purchaseAirtime</method>
<msisdn>256772744288</msisdn>
<transaction>455555</transaction>
<msisdn2>256772744288</msisdn2>
<network>MTN</network>
<value>5150</value>
</request>

2.4.2 checkStatus method


In addition to the general parameters required by all methods, this method may
accept the following parameters:

Parameter Description Example Required


msisdn This specifies the phone number 256111111111 Mandatory
for which the airtime purchase
request was made.
requestId This specifies ID returned when a 12345 Mandatory
purchaseAirtime request is made.

Below is a sample request to the platform for the checkStatus method:


<?xml version="1.0" encoding="UTF-8"?>
<request>
<username>sampleUser</username>
<password>samplePassword</password>
<method>checkStatus</method>
<requestId>12345</requestId>
<msisdn>2561111111111</msisdn>
</request>

2.4.3 checkBalance method


This method only requires the general parameters. Below is a sample request to
the platform for the checkBalance method:
<?xml version="1.0" encoding="UTF-8"?>
<request>
<username>sampleUser</username>
<password>samplePassword</password>
<method> checkBalance </method>
</request>

2.5 Response Format


The response format will vary depending on the method invoked by the client.

2.5.1 purchaseAirtime

This method is used to reload/purchase airtime for specified phone numbers from the
True African pinless airtime platform. The returned XML will contain the following
parameters:

Parameter Description Example


responseId This specifies the unique ID provided to 123455
the airtime purchase request.
status Specifies if a request has been Success
successfully received for
processing. The response could
either be Failed or Success

Code Specifies the response code for 300


the response

Below is a sample response from the purchaseAirtime method:

<?xml version="1.0" encoding="UTF-8"?>


<Response>
<responseId>12345</responseId>
<status>Success</status>
<code>00300</code>
</Response>

2.5.2 checkStatus
This method is used to check if a request previously sent has been successfully
processed by the MNO and the subscriber’s phone has been successfully recharged

Parameter Description Example


responseId This specifies the unique ID 1234567
provided to the airtime purchase
request.
status Specifies if a request has request Success
has been successfully processed by
MNO and subscriber phone
recharged. The response could
either be Failed, Pending or Success
Code Specifies the response code for the 300
response
Below is a sample response for the checkStatus method:
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<responseId>123487</responseId>
<status>Success</status>
<code>00300</code>
</Response>

2.5.3 checkBalance
This method is used to check the remaining balance on a pinless account.

Parameter Description Example


balance This specifies the amount 1267
remaining on pinless account.

status Specifies if a request has request Check balance status: Success


has been successfully processed by
MNO and subscriber phone
recharged. The response could
either be Failed, Pending or Success
Code Specifies the response code for the 403
response

Below is a sample response for the checkBalance method:


<?xml version="1.0" encoding="UTF-8"?>
<Response>
<code>403</code>
<status>Check balance status: Success</status>
<balance>4743</balance>
</Response>
3.0 Error Codes

If there is an error with a request to the API, an error will be returned with two fields:
 Code – This is a 3 digit numeric identifier of the error type.
 Status – This field contains details about the error message.

The following are the codes that can be returned by the


system as well as their corresponding messages.

Error Codes Table


Error Code Description
101 Access Violation: Invalid username,
password, source IP combination
102 Method Error: Non Existent method
201 Check Status Response: (Custom
message from network)
202 Airtime Purchase Received for
Processing
203 Duplicate transaction id
301 Status Check Error: Invalid transaction
Id, phone number combination
302 Get Voucher Error: Non Existent
network or Invalid MSISDN specified
303 Insufficient funds in wallet
304 Check Status Response: An error
occurred during recharge.
403 Check balance status: Success

You might also like