API Function: pin_input
API Function Application: Send details of pin top-up to your server
API Function Request Type: HTTP Request is sent from Cloud9 to your server.
API Function Status: Requires enablment by Cloud9 before use.
API Function Examples: Click Here to view online examples.


The pin_input function enables you to receive pin top-up requests as and when they are used by your
subscribers. This feature is ONLY available to resellers who's balance is NOT held by Cloud9.
When a pin is received into our network from your subscriber we send a HTTP post to
your server like so:

 

http://api.yourdomain.net/pin.asp?timestamp=2008-08-15%2018:27:01&imsi=234180000000000&transactionid=123456&msisdn=%2B447700000000&mcc=310&mnc=26
&request_type=pin_input&pin=123000000000000&pin_status=1&pin_value=10.00&carrierid=1

IMPORTANT: The string we send you will be URL encoded.

 

The URL is made up of the following variables:

 

REQUEST_TYPE

This variable will be set to PIN_INPUT.

TIMESTAMP

The date and time the HTTP request was created in yyyy-mm-dd HH:mm:ss format. This time stamp is used for the API CDR records.

TRANSACTIONID

This variable will be set to a numerical value by our system. The ID is used to track the HTTP request through the Cloud9 system.

CARRIERID

This variable will contain the carrier ID that has been assigned to you for use with our API.

MCC

This variable will contain (if the data is available) the MCC country code of where the subscriber is located. For example 234 for the UK.

MNC

This variable will contain (if the data is available) the MNC operator code (The network name that the subscriber is logged onto). For example 18 for the Wire9 Network.

IMSI

This variable will contain the IMSI of the subscriber who has made the pin request.

MSISDN

This variable will contain the MSISDN of the subscriber who has made the pin request.

PIN

This variable will contain the pin that the subscriber used.

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.

 

When a PIN_INPUT function request is sent your server is required to respond like so:

 

<?xml version="1.0" ?>

<PIN_response>

<message>Your account has now been topped up. New balance 50.00</message>

<request_status>1</request_status>

</<PIN_response>

The XML output is made up like so:

<PIN_RESPONCE>

The <CDR_response> tag is required so our system can detect your server’s XML reply.

<REQUEST_STATUS></REQUEST_STATUS>

This variable must either 0 (zero) or 1 (one). If 0 then the top-up request failed, if 1 then the top-up request was successful.

<DISPLAY_MESSAGE></DISPLAY_MESSAGE>

The display message tag needs to contain the message that you want displayed on the subscribers handset. You can use characters 0-9, a-z, A-Z '. , < > " () . The display message has a maximum limit of 64 characters. You must populate this field regardless of the request_status or routing tag settings.

</PIN_RESPONCE>

The </CDR_response> tag is required so our system can detect your server’s XML reply.

 

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

Privacy Statement | HTTP/XML System API © 2010 Cloud9 Mobile International Ltd. All Rights Reserved.