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

HTTP/XML/SS7 System API V2.3

Email page

Print page

Tuesday, September 07, 2010 00:09:34

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: update_user_balance
API Function Application: Update a user account balance
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.

To update a user account balance simply use the 'update_user_balance' function and send a URL string like so:
Please Note: This function is only to be used when Cloud9 hold the user account balance. If your system holds the
user balance then this function will not add or deduct from the user balance.

http://api.wire9.com/api.cgi?transaction_id=1000&request_type=update_user_balance
&carrier_id=1&password=test&timestamp=2007-03-08%2023:43:43
&query=%2B447700000000&topup_amount=50.00

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	The transaction ID your system assigned to the UPDATE USER BALANCE request.
REQUEST_TYPE	This variable must be set to update_user_balance.
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.
QUERY	This variable must contain the MSISDN or IMSI of the subscriber of who's balance you wish to query. If passing a MSISDN may use the following formats: 07xxx, 447xxx or +447xxx.
TOPUP_AMOUNT	This variable must contain the amount to top the subscribers account up by. The amount must be supplied in 0.00 format. The amount can be a positive value or a negative value. If you supply a negative value then the account balance will be deducted from.

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

When a valid update_user_balance 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>

<NEW_BALANCE>50.00</NEW_BALANCE>

<OLD_BALANCE>0.00</OLD_BALANCE>

<TOPUP_AMOUNT>50.00</TOPUP_AMOUNT>

<CURRENCY>Pounds</CURRENCY>

<IMSI>234180000000000</IMSI>

<MSISDN>+447700000000</MSISDN>

<REQUEST_STATUS>1</REQUEST_STATUS>

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

<TRANSACTION_ID>1000</TRANSACTION_ID>

</STATUS_Response>

</Wire9_data>

The XML output is made up like so:

OLD_BALANCE	This variable contains the balance prior to the topup in 0.00 format.
NEW_BALANCE	This variable contains the balance after to the topup in 0.00 format.
TOPUP_AMOUNT	This variable contains the amount the account was topped up by or deducted by in 0.00 format.
CURRENCY	This variable contains the currency of the subscribers balance (Pounds, Dollars or Euros)
IMSI	This variable will contain the IMSI of the subscriber.
MSISDN	This variable will contain the MSISN of the subscriber.
REQUEST_STATUS	This variable will contain the request status responce. Options: 0 = Request Failed 1 = Request Successful
TIME_STAMP	The returned TIMESTAMP that you passed within the HTTP request string.
TRANSACTION_ID	The transaction ID your system assigned to the IMSI Status request.

If your server is unable to process the request or a system error occurs 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