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:27

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_status
API Function Application: Check the status of a top-up 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_status function enables you to query an assigned top-up pin. To query a pin 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_status

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 pin code that has been assigned to you by our system that you with to query. Top-up pin codes can be created within your user login area.
REQUEST_TYPE	This variable must be set to PIN_STATUS. This setting tells our system that you wish to carry out a pin check 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_STATUS 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>

<DATE_ACTIVATED>2008-05-23 12:05:14</DATE_ACTIVATED>

<DATE_REDEMEED>1900-01-01 00:00:00</DATE_REDEMEED>

<IMSI>0</IMSI>

<MSISDN>0</MSISDN>

<PIN>10000000000000</PIN>

<PIN_STATUS>1</PIN_STATUS>

<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:

DATE_ACTIVATED	The date the pin was created in yyyy-mm-dd HH:mm:ss format.
DATE_REDEEMED	The date the pin was redeemed. If the pin has not been redeemed the value in this field will be 1900-01-01 00:00:00 Field format yyyy-mm-dd HH:mm:ss
IMSI	This variable contains the IMSI of the subscriber who redeemed the pin. If the pin has not been redeemed then this field will contain 0 (zero)
MSISDN	This variable contains the MSISDN of the subscriber who redeemed the pin. If the pin has not been redeemed then this field will contain 0 (zero)
PIN	This variable will contain the pin that you have quiried
PIN_STATUS	This variable will contain the status of the pin. 1 = Unredeemed 2 = Redeemed
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