Airtime API (Data and Airtime)

Easily order and receive Vodacom, Cell C, MTN and Telkom Airtime or Data in real time from one source.

Freepaid’s API provides seamless, real time access to a wide range of pinned and pinless prepaid products at our transparent, competitive prices. This state-of-the-art programming interface does all the heavy lifting for you. It puts the programming power into your hands, freeing you to put your energy into your own development. Its clean, simple structure cuts down on implementation times and support queries. And once integrated, your application will be supported by unprecedented speed and reliability. Access fee is R99.00 per month plus VAT.

API Overview

You can order PINLESS airtime (direct recharge) or data through this API or you can order a PINNED airtime voucher which is sent to you in the form of a PIN number.

To get started you will need to register an account. During registration, we send a ‘user number’ to your Mobile phone via SMS and it will be needed in all future API calls on the Live Server.

Once logged in there be sure to go to EDIT MY DETAILS and complete your company information. The information you enter will be used to populate your Tax Invoices (which are also available online).

Then add FREEPAID as a beneficiary on your bank account and deposit funds into the FREEPAID bank account at FNB using only the MOBILE NUMBER that you registered with as the reference number. If you put your Company name or anything else as the reference it will cause a delay since your funds to go to a suspense account and this will have to get rectified manually later.

However, if the reference number is inserted correctly on the EFT then the funds will be allocated to your wallet within seconds of reaching the FREEPAID bank account. This is an automated process and works 24/7. Note that transfers from banks other than FNB can take longer to reach us.

Once the credit is available (we send SMS notification) you can then proceed to order airtime at the wholesale rate via the API. The dealer cost price of each voucher will be deducted from your balance as you transact and the remaining balance in your wallet will be returned with every webservice call.

API Specification

We use a SOAP API

The full WSDL is here: https://ws.freepaid.co.za/airtimeplus/?wsdl

The full documentation is here https://ws.freepaid.co.za/airtimeplus/

Step 1: Register on the Live server

Register on the Live Server http://services.freepaid.co.za and use your live credentials to start testing.

You will receive a OTP (one time pin) via SMS. Save the 7 digit number in that SMS as it will be required in each webservice call when ordering from the Live server. The password (which must also be included in each request) will be the one you entered into the Live website during registration.

Once you have done this, send an email to apisupport@freepaid.co.za with the following subject:
Freepaid | the number you registered with | Sandbox API

We will then allocate money so you can test your calls on the LIVE server.

Step 2: Setting up your environment

FREEPAID uses PHP, but you're free to use whatever you're comfortable with. We also use a modified PHP NuSOAP library which you can find here. It has been modified to make sure it works with PHP 7

On Live use the Live api endpoint: https://ws.freepaid.co.za/airtimeplus/

To fetch the balance you will use a call like this:

            require_once( "nusoap.php" );
              $client = new nusoap_client( "https://ws.freepaid.co.za/airtimeplus/" );
              $err = $client->getError( );
              if( $err ){
                print "<p><b>Constructor error: ".$err."</b></p>";
              }
              else {
                $request = array(
                  "user" => "USERXXXX",  # USER number, NOT cell number
                  "pass" => "PASSXXXX",
                );
                $result = $client->call( "fetchBalance", array( "request" => $request ) );
                if( $client->fault ){
                  print "<p><b>Error: <pre>";
                  print_r( $result );
                  print "</pre></b></p>";
                }
                else {
                  $err = $client->getError( );
                  if( $err ){
                    print "<p><b>Error: ".$err."</b></p>";
                  }
                  else {
                    print "<pre>";
                    print_r( $result );
                    print "</pre>";
                  }
                }
              }

Step 3: Getting to understand the process flow.

The API gives you the ability to order two kinds of vouchers, PINNED and PINLESS.

A PINNED voucher means you can deliver an airtime value by means of a 12 digit PIN which you can deliver electronically or print or send by SMS or whatever.

PINLESS relies on a direct top up of the MSISDN of your customer or client at Network level. In addition data bundles can be delivered as well. This saves the consumer the hassle of converting airtime to a data bundle which is a confusing process for many people.

We prefer pinless for security and other reasons.

Airtime vouchers are available in PINNED or PINLESS format. When you order PINNED vouchers you can only order vouchers that exist on the list of denominations that the Networks have chosen to create.

Below are some common values you may be familiar with...

            CELLC R10.00
            CELLC R25.00
            CELLC R35.00

            MTN R10.00
            MTN R15.00
            MTN R30.00

            VODACOM R10.00
            VODACOM R12.00
            VODACOM R29.00
            

However the PINLESS method for ordering Airtime allows orders from R2.00 all the way to R999.00 so you can order very specific values like Vodacom R2.35 or MTN R111.76.

While data is also PINLESS (it is a direct recharge) it too can only be ordered if it appears on the list of denominations that the Networks has chosen to create.

Process Flow: PINNED Vouchers

For PINNED you will first issue a fetchProducts call to get the available product list then you will issue a placeOrder call to place the order, you will receive an order number in the repsonse which you will use in the fetchOrder call. The response (subject to funds being available in your wallet) will be the PIN and serial number of the chosen voucher.

Process Flow: PINLESS Vouchers

For PINLESS Airtime or Data you will issue a fetchProducts call to get the product list then you will issue a placeOrder call to place the order. FREEPAID will respond with an order number and you will then use this order number to query the status of the PINLESS recharge using the queryOrder call. This will return ‘Success’ or ‘Failure’.

So in short:

PINLESS:

• Fetch Product List ( PINLESS vouchers will be p-network example p-vodacom)
• Place PINLESS Order

              "user" => "USERXXXX",  # USER number, NOT cell number
              "pass" => "PASSXXXX",
              "refno" => "TESTXXXX", # Your own refno
              "network" => "p-vodacom",  # PINLESS vodacom
              "sellvalue" => "2.44",
              "count" => "1",  # ONLY 1 is accepted here for PINLESS
              "extra" => "CELLXXXX",  # CELL number to be recharged
              

• Query PINLESS Order

              "user" => "USERXXXX",  # USER number, NOT cell number
              "pass" => "PASSXXXX",
              "orderno" => "ORDERXXX",
              

The steps are

• Place the order
• Receive back an order number
• Use that order number to query the status of the order.

Note: Do not query the status more than once per minute and after five attempts, once per hour. Any failures that we receive from the Network will be adjusted on your account automatically.

For PINNED Airtime vouchers you will use placeOrder to place the order, but then you will use the order number (given in our response) to fetch the actual PINNED order. The response will be a PIN number and the serial number for the voucher, with cost price and remaining balance. (You can also use the order number to re-order old vouchers, for example if you need to do a reprint).

FAQ

Does the API work with cents?

Yes, you can only order PINLESS AIRTIME in values like R2.50, R3.20 etc. Please make sure to use a decimal point and NOT a comma. R4.55 is correct. R4,55 is not correct.

What is the correct API URL to use?

On the Live Server use https://ws.freepaid.co.za/airtimeplus/ note the "https".

What are the error codes for the API?

define( "airtimeOKAY", "000" );
define( "airtimePENDING", "001" );
define( "airtimeEMPTYORDER", "100" );
define( "airtimeINVALIDUSER", "101" );
define( "airtimeINVALIDLAST", "102" );
define( "airtimeINVALIDPASS", "103" );
define( "airtimeINVALIDNETWORK", "104" );
define( "airtimeINVALIDSELLVALUE", "105" );
define( "airtimeFUNDSEXCEEDED", "106" );
define( "airtimeOUTOFSTOCK", "107" );
define( "airtimeINVALIDCOUNT", "108" );
define( "airtimeINVALIDREFNO", "109" );
define( "airtimeINVALIDREQUEST", "110" );
define( "airtimeSTILLBUSY", "111" );
define( "airtimeINVALIDORDERNUMBER", "112" );
define( "airtimeINVALIDEXTRA", "113" );
define( "airtimeINTERNAL", "197" );
define( "airtimeTEMPORARY", "198" );
define( "airtimeUNKNOWN", "199" );
            

Can I order PINNED Airtime vouchers, PINLESS airtime and data bundles using the same API?

Yes, provided you use the correct calls and values you can do so.

What is my USER number and where do I find it?

The USER number is in fact the number associated with your account in our system, which is in turn associated with the mobile number used during registration.

The Live USER number is contained in the first SMS which we sent to you during registration on the Live site. If you have already deleted the SMS then login at services.freepaid.co.za, click on Reports, then SMS log, and find the first SMS in the report.

Or call 087 073 6555 during office hours for assistance.

Sample Code

Please feel free to send us sample code and snippets, currently only sample code in PHP is available, but it will be good to expand this section to include other languages.

fetch balance

  require_once( "nusoap.php" );
  $client = new nusoap_client( "https://ws.freepaid.co.za/airtimeplus/" );
  $err = $client->getError( );
  if( $err ){
    print "<p><b>Constructor error: ".$err."</b></p>";
  }
  else {
    $request = array(
      "user" => "USERXXXX",  # USER number, NOT cell number
      "pass" => "PASSXXXX",
    );
    $result = $client->call( "fetchBalance", array( "request" => $request ) );
    if( $client->fault ){
      print "<p><b>Error: <pre>";
      print_r( $result );
      print "</pre></b></p>";
    }
    else {
      $err = $client->getError( );
      if( $err ){
        print "<p><b>Error: ".$err."</b></p>";
      }
      else {
        print "<pre>";
        print_r( $result );
        print "</pre>";
      }
    }
  }

fetch product list

  require_once( "nusoap.php" );
  $client = new nusoap_client( "https://ws.freepaid.co.za/airtimeplus/" );
  $err = $client->getError( );
  if( $err ){
    print "<p><b>Constructor error: ".$err."</b></p>";
  }
  else {
    $request = array(
      "user" => "USERXXXX",  # USER number, NOT cell number
      "pass" => "PASSXXXX",
    );
    $result = $client->call( "fetchProducts", array( "request" => $request ) );
    if( $client->fault ){
      print "<p><b>Error: <pre>";
      print_r( $result );
      print "</pre></b></p>";
    }
    else {
      $err = $client->getError( );
      if( $err ){
        print "<p><b>Error: ".$err."</b></p>";
      }
      else {
        print "<pre>";
        print_r( $result );
        print "</pre>";
      }
    }
  }

place PINNED order

require_once( "nusoap.php" );
  $client = new nusoap_client( "https://ws.freepaid.co.za/airtimeplus/" );
  $err = $client->getError( );
  if( $err ){
    print "<p><b>Constructor error: ".$err."</b></p>";
  }
  else {
    $request = array(
      "user" => "USERXXXX",  # USER number, NOT cell number
      "pass" => "PASSXXXX",
      "refno" => "TESTXXXX",
      "network" => "vodacom",
      "sellvalue" => "2",
      "count" => "10",
      "extra" => "",
    );
    $result = $client->call( "placeOrder", array( "request" => $request ) );
    if( $client->fault ){
      print "<p><b>Error: <pre>";
      print_r( $result );
      print "</pre></b></p>";
    }
    else {
      $err = $client->getError( );
      if( $err ){
        print "<p><b>Error: ".$err."</b></p>";
      }
      else {
        print "<pre>";
        print_r( $result );
        print "</pre>";
      }
    }
  }

fetch PINNED order

require_once( "nusoap.php" );
  $client = new nusoap_client( "https://ws.freepaid.co.za/airtimeplus/" );
  $err = $client->getError( );
  if( $err ){
    print "<p><b>Constructor error: ".$err."</b></p>";
  }
  else {
    $request = array(
      "user" => "USERXXXX",  # USER number, NOT cell number
      "pass" => "PASSXXXX",
      "last" => "",  # only works 1st time; use the returned order number for next call
    );
    $result = $client->call( "fetchOrderLatest", array( "request" => $request ) );
    if( $client->fault ){
      print "<p><b>Error: <pre>";
      print_r( $result );
      print "</pre></b></p>";
    }
    else {
      $err = $client->getError( );
      if( $err ){
        print "<p><b>Error: ".$err."</b></p>";
      }
      else {
        print "<pre>";
        print_r( $result );
        print "</pre>";
      }
    }
  }

place PINLESS order

  require_once( "nusoap.php" );
  $client = new nusoap_client( "https://ws.freepaid.co.za/airtimeplus/" );
  $err = $client->getError( );
  if( $err ){
    print "<p><b>Constructor error: ".$err."</b></p>";
  }
  else {
    $request = array(
      "user" => "USERXXXX",  # USER number, NOT cell number
      "pass" => "PASSXXXX",
      "refno" => "TESTXXXX",
      "network" => "p-vodacom",  # PINLESS vodacom pd-network = data
      "sellvalue" => "2",
      "count" => "1",  # ONLY 1 is accepted here for PINLESS
      "extra" => "CELLXXXX",  # CELL number to be recharged
    );
    $result = $client->call( "placeOrder", array( "request" => $request ) );
    if( $client->fault ){
      print "<p><b>Error: <pre>";
      print_r( $result );
      print "</pre></b></p>";
    }
    else {
      $err = $client->getError( );
      if( $err ){
        print "<p><b>Error: ".$err."</b></p>";
      }
      else {
        print "<pre>";
        print_r( $result );
        print "</pre>";
      }
    }
  }

query PINLESS order

  require_once( "nusoap.php" );
  $client = new nusoap_client( "https://ws.freepaid.co.za/airtimeplus/" );
  $err = $client->getError( );
  if( $err ){
    print "<p><b>Constructor error: ".$err."</b></p>";
  }
  else {
    $request = array(
      "user" => "USERXXXX",  # USER number, NOT cell number
      "pass" => "PASSXXXX",
      "orderno" => "ORDERXXX",
    );
    $result = $client->call( "queryOrder", array( "request" => $request ) );
    if( $client->fault ){
      print "<p><b>Error: <pre>";
      print_r( $result );
      print "</pre></b></p>";
    }
    else {
      $err = $client->getError( );
      if( $err ){
        print "<p><b>Error: ".$err."</b></p>";
      }
      else {
        print "<pre>";
        print_r( $result );
        print "</pre>";
      }
    }
  }

Our Products