Cloud9 HTTP/XML/SS7 GSM System API - Function 'pin

HTTP/XML/SS7 System API V2.3

Email page

Print page

Tuesday, September 07, 2010 00:09:37

Balance Functions

DDI Mapping

CDR Functions

IMSI Control Functions

Inbound Call Functions

MSRN Functions

Outbound Call Functions

Pin Functions

Routing Functions

SMS Functions

USSD Functions

Voicemail Functions

API Function: pin_topup
API Function Application: Top-up a subscribers account by pin
API Function Request Type: HTTP Request is sent from your server to our server.
API Function Status: Available as standard
API Function Examples: Click Here to view online examples.

The pin_topup function enables you to top-up a subscribers account via the pin top-up system. To update a subscribers account
balance send a HTTP request like so:
Please note that Cloud9 must hold your user balances and you must have valid pin codes created and assigned
to your account for this function to work.

http://api.wire9.com/api.cgi?transaction_id=1003&pin=10000000000000&carrier_id=1&password=test&timestamp=2007-03-08%2023:43:43&request_type=pin_topup&query=%2B447700000000

IMPORTANT: You must URL Encode your HTTP string. URL Encoding replaces unsafe ASCII characters with "%" followed by their hex equivalent. Safe characters are defined in RFC2396. For example a '+' will become '%2B'

The URL is made up of the following variables:

URL	http://api.wire9.com/api.cgi
TRANSACTION_ID	This variable must be set to a numerical value by your system. The ID is used to track the HTTP request through the Wire9 system. The data returned by our system will contain the ID that you assign. The transaction ID can be assigned a value from 0 – 999999.
PIN	This variable must contain a system assigned pin code that you with to query. Top-up pin codes can be created within your user login area.
QUERY	This variable must contain the MSISDN or IMSI of the subscriber who's account you wish to top-up. If passing a MSISDN you may use the following formats: 07xxx, 447xxx or +447xxx.
REQUEST_TYPE	This variable must be set to PIN_TOPUP. This setting tells our system that you wish to carry out a pin top-up request.
CARRIER_ID	This variable must contain the carrier ID that has been assigned to you for use with our API. Please contact support@cloud9-mobile.co.uk if you do not have your API carrier ID.
PASSWORD	This variable must contain the password that has been assigned to you for use with our API. Please contact support@cloud9-mobile.co.uk if you do not have your API password.
TIMESTAMP	This variable is set by your system. It should contain a valid date and time in yyyy-mm-dd HH:mm:ss format. This time stamp is used for the API CDR records.

Please Note: All of the above variables are required within the HTTP request string.
The request will fail if the required variables are not passed in the correct format.

When a valid PIN_TOPUP request is made the Cloud9 system will return a standard XML (version 1 tree)
which your system must then phase through and pull out the required data:

<?xml version="1.0" ?>

<Wire9_data>

<STATUS_Response>

<IMSI>234180000000000</IMSI>

<MSISDN>+447700000000</MSISDN>

<OLD_BALANCE>10.00</OLD_BALANCE>

<NEW_BALANCE>20.00</NEW_BALANCE>

<PIN>10000000000000</PIN>

<PIN_VALUE>10.00</PIN_VALUE>

<REQUEST_STATUS>1</REQUEST_STATUS>

<TIME_STAMP>2007-03-08 23:43:43</TIME_STAMP>

<TRANSACTION_ID>1003</TRANSACTION_ID>

</STATUS_Response>

</Wire9_data>

The XML output is made up like so:

IMSI	This variable contains the IMSI of the subscriber of who's account the pin has been redeemed against.
MSISDN	This variable contains the MSISDN of the subscriber of who's account the pin has been redeemed against.
OLD_BALANCE	This variable will contain the subscribers balance prior to top-up in 0.00 format.Please note the currency used will be your system default currency.
NEW_BALANCE	This variable will contain the subscribers balance after the top-up in 0.00 format.Please note the currency used will be your system default currency.
PIN	This variable will contain the pin that you used to carry out the top-up.
PIN_VALUE	The variable will contain the value of the pin in 0.00 format. Please note the currency used will be your system default currency.
REQUEST_STATUS	Options: 0 = Fail 1 = Success
TIME_STAMP	The returned TIMESTAMP that you passed within the HTTP request string.
TRANSACTION_ID	The transaction ID your system assigned to the PIN_STATUS request.

If our server is unable to process the request or a system error occurs we will send back a formatted XML
error message like so stating what error occurred within the <Error_Message></Error_Message> tag:

<? xml version="1.0" ?>

<Error>

<Error_Message>Error: Unknown user </Error_Message>
</Error>

ERROR_MESSAGE

This variable will contain information to why the request could not be processed by our system.

Top of page Email page Print page

Last Review 16/08/2008 @ 21:08:19