Aerapay API

Introduction

The reference documentation below should be all that is needed to enable the integration of aerapay into your application or web page. If there are any questions feel free to email us

Offline documentation is under construction

Contents

  1. Authentication
  2. REST Resources
    1. Customer
    2. Account
    3. Product
    4. Invoice
    5. Broadcast
    6. Balance
    7. SMS
    8. Payment
  3. Examples in source
    1. PHP
    2. ASP
    3. ASP.NET

Authentication

Aerapay uses HTTP/Basic authentication over SSL to provide the most open yet secure method

REST Resources

Note: the base URI for the web services is given on sign up

Customer

Description

Represents the collection of customers that have been entered into the system.

To retrieve individual customer details append the ID of the customer to the GET REST url e.g /api/customer/346

To update individual customer details append the ID of the customer to the POST REST url

Methods

customer
URL : /api/customer
HTTP Method : GET
Authentication required : Yes
Parameters : none
Response:
<?xml version==1.0" encoding="UTF-8"?>
<customers>
	<total>1</total>
	<customer>
		<id>346</id>
		<reference>DEMO</reference>
		<start_date>2010-02-03 01:41:17</start_date>
		<firstname>Test</firstname>
		<lastname>Demo</lastname>
		<address>PO Box 1</address>
		<state>Qld</state>
		<zip>4000</zip>
		<mobile>6111111111</mobile>	
		<home></home>
		<email>info@sueldo.me</email>
		<active>1</active>
		<username></username>
		<password></password>
	<customer>;
</customers>

URL : /api/customer
HTTP Method : POST
Authentication required : Yes
Parameters :
  • reference : string
  • firstname : string
  • lastname : string
  • address : string
  • mobile : number
  • state : string
  • zip : string
  • home : number
  • email : string
  • card_type : string
  • card_number : number
  • card_exp : number (optional)
  • card_pin : number
  • token : string (optional)
  • username : string (optional)
  • password : string (optional)

Response:
HTTP Codes: 
  • 200 OK
  • 500 Server problem
  • 406 missing arguments

search
URL : /api/customer/search/<search_string>
HTTP Method : GET
Authentication required : Yes
Parameters : none
Response:
<?xml version="1.0" encoding="UTF-8"?>
<customers>
	<total>1</total>
	<customer>
		<id>346</id>
		<reference>DEMO</reference>
		<start_date>2010-02-03 01:41:17</start_date>
		<firstname>Test</firstname>
		<lastname>Demo</lastname>
		<address>PO Box 1</address>
		<state>Qld</state>
		<zip>4000</zip>
		<mobile>6111111111</mobile>
		<home></home>
		<email>info@sueldo.me</email>
		<active>1</active>
	</customer>
</customers>

history
URL : /api/customer/history/<user_id>
HTTP Method : GET
Authentication required : Yes
Parameters : none
Response:
<?xml version="1.0" encoding="UTF-8"?>
<entries>
	<name>Mr Customer</name>
	<number>611111111</number>
	<entry>
		<type>outgoing</type>
		<hit>2010-06-25 10:03:27</hit>
		<message>The Password you entered is<br> incorrect</message>
	</entry>
	<entry>
		<type>outgoing</type>
		<hit>2010-06-25 10:01:33</hit>
		<message>The item you have requested is valid</message>
	</entry>
	<entry>
		<type>incoming</type>
		<hit>2010-06-25 10:01:33</hit>
		<message>HEIN</message>
	</entry>
	<entry>
		<type>outgoing</type>
		<hit>2010-05-25 11:32:55</hit>
		<message>Your receipt code is 014511349913.</message>
	</entry>
	<entry>
		<type>payment</type>
		<hit>2010-05-25 11:32:55</hit>
		<message>Transaction Successful</message>
	</entry>
</entries>

Account

Description

Methods

email configuration
URL : /api/account/emails
HTTP Method : POST
Authentication required : Yes
Parameters :
  • register_email_body : string
  • register_email_subject : string
  • purchase_email_body : string
  • purchase_email_subject : string

Response:
HTTP Codes: 
  • 200 OK
  • 500 Server problem
  • 406 missing arguments

messages configuration
URL : /api/account/messages
HTTP Method : POST
Authentication required : Yes
Parameters :
  • cancel : string
  • stop : string
  • confirm : string
  • complete : string
  • invalid : string
  • error : string
  • wrong_pin : string
  • welcome : string
  • purchase_email_subject : string

Response:
HTTP Codes: 
  • 200 OK
  • 500 Server problem
  • 406 missing arguments

Product

Description

Interact with the product resources, add to the catalog, editing details

Methods

add a product
URL : /api/product
HTTP Method : POST
Authentication required : Yes
Parameters :
  • message : string
  • description : string
  • topup : 0 / 1
  • code : string
  • cost : number

Response:
HTTP Codes: 
  • 200 OK
  • 500 Server problem
  • 406 missing arguments

retrieve all products
URL : /api/product
HTTP Method : GET
Authentication required : Yes
Parameters :
  • message : string

Response:
<?xml version="1.0" encoding="UTF-8"?>
	<products>
		<total>1</total>
		<product>
		<id>1</id>
		<code>VEGE</code>
		<topup>0</topup>
		<unit_cost>10.99</unit_cost>
		<description>Hot Pizza</description>
		<message>[CODE] for [DESCRIPTION]</message>
	</product>
</products>

Invoice

Description

Interact with the product invoice resources, add to the catalog, see paid data etc

Methods

add an invoice
URL : /api/invoice
HTTP Method : POST
Authentication required : Yes
Parameters :
  • message : string
  • code : string
  • cost : number xx.xx
  • due_date : date YYYY-MM-DD
  • description : string
  • customer : customer ID (optional)
  • number : mobile number (this or customer ID) needs to be set

Response:
HTTP Codes: 
  • 200 OK
  • 500 Server problem
  • 406 missing arguments

view invoices
URL : /api/invoice
HTTP Method : GET
Authentication required : Yes
Parameters :
Response:

<?xml version='1.0' encoding='UTF-8'?>
<invoices>
<total>1</total><invoice>
	<lastname>xxxx</lastname>
	<firstname>yyy</firstname>
	<reference>ref</reference>
	<id>1</id>
	<code>INV1</code>
	<customer>1</customer>
	<unit_cost>43.00</unit_cost>
	<description>Consultancy Work (12hrs)</description>
	<message>Please pay [COST] for [Description]</message>
	<due_date>2010-08-01</due_date>
	<paid>1</paid>
	<paid_date>2010-07-14</paid_date>
</invoice>
</invoices>

check an invoice
URL : /api/invoice/check/<code>
HTTP Method : GET
Authentication required : Yes
Parameters :
Response:
<invoice>
	<id>19</id>
	<code_type>invoice</code_type>
	<msisdn>61418754101</msisdn>
	<customer>1</customer>
	<description>Shopping Cart</description>
	<unit_cost>10.00</unit_cost>
	<active>1</active>
	<message>Text [CODE] to pay [DESCRIPTION]</message>
	<due_date>2010-11-01</due_date>
	<sent_date></sent_date>
	<paid_date>2010-10-04</paid_date>
	<paid>1</paid>
</invoice>

Broadcast

Description

Used to send an message to all of your customers

Methods

broadcast a general message
URL : /api/broadcast
HTTP Method : POST
Authentication required : Yes
Parameters :
  • message : string

Response:
HTTP Codes: 
  • 200 OK
  • 500 Server problem
  • 406 missing arguments

advertise a specific product or offer
URL : /api/broadcast/<product_id>
HTTP Method : POST
Authentication required : Yes
Parameters :
  • message : string

Response:
HTTP Codes: 
  • 200 OK
  • 500 Server problem
  • 406 missing arguments

Balance

Description

Used to interact with the customers microredemption balance

Methods

balance
URL : /api/balance/<user_id>
HTTP Method : GET
Authentication required : Yes
Parameters : none
Response:
HTTP Codes: 
  • 200 OK
  • 500 Server problem
  • 406 missing arguments

spend
URL : /api/balance/spend/<user_id>
HTTP Method : POST
Authentication required : Yes
Parameters :
  • amount : integer

Response:
HTTP Codes: 
  • 200 OK
  • 500 Server problem
  • 406 missing arguments

SMS

Description

Used to send SMS messages with arbitrary to / from addresses

Methods

sms
URL : /api/sms
HTTP Method : GET
Authentication required : Yes
Parameters : none
Response:
<?xml version='1.0' encoding='UTF-8'?>
<sent_sms>
    <sms>
         <id>43</id>
         <client>1</client>
         <message>API test</message>
         <from>614XX194147</from>
         <to>614XX194147</to>
         <entered_date>2010-08-06 19:29:43</entered_date>
         <gateway_message_id>6101102920469278</gateway_message_id>
         <last_update_date></last_update_date>
         <status></status>
         <error_code></error_code>
         <sent>1</sent>
     </sms>
</sent_sms>

URL : /api/sms
HTTP Method : POST
Authentication required : Yes
Parameters :
  • to : international number
  • from : international number
  • message : string

Response:
HTTP Codes: 
  • 200 OK
  • 418 Billing
  • 500 Server problem

Payment

Description

Used to process card payments and view previous transactions

Methods

payment
search
onetime

Use this method to process a single transaction

URL : /api/payment/onetime
HTTP Method : POST
Authentication required : Yes
Parameters :
  • card_num : card number string
  • card_exp : MMYY expiry string
  • reference : string
  • name : name on the card string
  • amount : number

Response:
<response>
<error>0</error>
<text>Transaction Successful</text>
<receipt>101111564011</receipt>
<error_msg>Approved</error_msg>
</response>
					

Examples

The source given below is show without warranty.

PHP


curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postfields);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_exec($ch);			
			

ASP


Set objWinHttpToken = Server.CreateObject("WinHttp.WinHttpRequest.5.1")
objWinHttpToken.SetTimeouts 0, 60000, 60000, 60000
objWinHttpToken.Open method, url, False
objWinHttpToken.SetRequestHeader "Content-Type", "application/x-www-form-urlencoded"
objWinHttpToken.Send sendData
			

ASP.Net