Anonymous User Identification API

Overview

Anonymous User Identification (AUID) is a feature of the MX Telecom Charge To Account Gateway which enables you to retrieve information about end users visiting a WAP/XHTML site.

In the US, the information which can be retrieved depends on the carrier.

For each user, you may be able to determine:

the wireless carrier on which they are a subscriber
which billing mechanisms are available to charge the user
a list of identifiers for their active Charge To Account Gateway subscriptions with you
a unique user identifier, which is also returned when a user is successfully charged or starts a subscription

See the Carrier Differences table for details.

AUID workflow
Making requests using HTTP
Format of response from server
Receiving notifications
Notification parameters
Example requests and notifications
- Basic query
- Extended query

AUID workflow

In order to identify the user, their WAP or XHTML session needs to be temporarily redirected via the Charge To Account Gateway. To achieve this, your application makes an HTTP request to the gateway. In the response, the gateway provides a URL to which the user should be redirected.

The overall process works as follows:

Anonymous User Identification with the Charge To Account Gateway

The gateway redirects the end user straight back to your site following identification. As far as the user is concerned, the only noticeable effect of the AUID request is that your WAP/XHTML page takes slightly longer to load.

To ensure a good user experience, your server must respond to the notification in a timely manner.

Making requests using HTTP

The Charge To Account Gateway exposes an HTTPS interface for making requests for details about a user. The endpoint for these HTTP requests is:

https://cta.mxtelecom.com/api

This URL accepts both GET and POST requests.

The parameters you use to make an AUID request are:

Parameter	Required?	Meaning	Values allowed
username	Yes	Username for access to the gateway
password	Yes	Password for access to the gateway
action	Yes	The type of request. This determines the amount of information returned by the request.	basicuserquery - Returns limited information extendeduserquery - Returns extended information
brand	No	The brand identity of the merchant site that the end user is browsing. Use this parameter to enable the CTA Gateway to deliver the notification to the URL specified for the brand. See branding for information about brands. Default: the default brand set for your account.	Specific to the account—the brand ID is pre-provisioned for accounts supporting multiple brands.
responseFormat	No	The desired response format	plain - Plain text format (default) xml - XML format

Format of response from server

The possible outcomes along with their corresponding HTTP response codes are:

outcome	HTTP Response Code	Request Accepted?	Description
rejected	403	No	The request was rejected
userinputrequired	200	Yes	The request was accepted but additional user information and/or confirmation is required (ie the user must visit the URL hosted by MX Telecom)

The body of the HTTP response contains name/value pair parameters in either plain text (name:value) or XML (<name>value</name>) format depending on the responseFormat specified.

The following parameters are always returned for Anonymous User Identification requests:

Parameter	Meaning	Values
outcome	Result of the request	rejected, userinputrequired
outcomeReasonId	Code defining the reason for the outcome of the request	four-digit integer e.g. 3002 See the status codes documentation for more details.
outcomeReasonText	Natural language description of the outcome	string
queryId	A unique identifier for this particular AUID query	64-bit unsigned integer e.g. 2443071
redirectUrl	URL which the user must visit to enable collection of details	e.g. http://mxpay.net/3/6PXQnZIHTh

This is an example of a plain-text response to an AUID request from the gateway:

outcome:userinputrequired
outcomeReasonId:2002
outcomeReasonText:Missing information that requires user input.
redirectUrl:http://mxpay.net/3/1e1RDTiI5aB5N88Np3CcY0T-pdpy7LOSW1W-bgHL4ps
queryId:2443071

This is an example of an XML response to an AUID request from the gateway:

<response>
<outcome>userinputrequired</outcome>
<outcomeReasonId>2002</outcomeReasonId>
<outcomeReasonText>Missing information that requires user input.</outcomeReasonText>
<redirectUrl>http://mxpay.net/3/mZ6i_rkLrjP6eDn9X7m-DBVr4Nw7viNgW1W-bgHL4ps</redirectUrl>
<queryId>7696619</queryId>
</response>

Receiving notifications

Once the end user has visited the redirectUrl, you will receive details about them as an HTTP notification from the gateway to a server you control.

The URL to which the notification HTTP requests are made is configured on a per-account basis, and is the same URL used for transaction and subscription notifications.

Your server should respond with an HTTP 200 response with a fulfilment URL in the HTTP body. The fulfilment URL should be in plain text, prefixed with fulfilmentUrl: and no longer than 255 characters in length. For example:

fulfilmentUrl:http://merchant.example.com/view?productId=foo

This response should be given in a timely manner (under 10 seconds). Currently, the gateway will not abandon a request (stop waiting for the HTTP response) until 60 seconds have passed, but this might be reduced in future.

To ensure the authenticity of the HTTP requests you should only accept requests from the following MX Telecom IP addresses:

83.166.68.0/23 (ie 68.0 -> 69.255)

The HTTP endpoint can be an HTTPS (SSL) URL to protect the data whilst in transit.

Notification parameters

Once the relevant data has been collated, an HTTP GET request will be made to your server with the following parameters:

Parameter	Always present?	Query Type	Meaning	Values
queryId	Yes	Basic & Extended	The unique ID of the query	64-bit unsigned integer
requirefulfilmentUrl	Yes	Basic & Extended	Indicates whether or not the Charge To Account Gateway requires a URL where the end user will continue their browsing session. This is always yes for an AUID request.	yes
availableBillingMechanisms	No	Basic & Extended	A list of billing mechanisms definitely available for this user (comma-separated list)	URL-encoded comma-separated list At present the only possible value is MOBILE
potentiallyAvailableBillingMechanisms	No	Basic & Extended	A list of billing mechanisms which may be available for this user	URL-encoded comma-separated list At present the only possible value is MOBILE
subscriptionIds	No	Basic & Extended	A list of subscriptionId values uniquely identifying the user's active subscriptions (including subscriptions which are in the process of being set up) See Subscriptions documentation for a detailed guide to subscriptions	URL-encoded comma-separated list of subscriptionId values
network	No	Basic & Extended	The mobile network of the end user	See table of network codes
uniqueUserIdentifier	Yes	Basic & Extended	Unique user identifier (if the MSISDN is available).	URL-encoded string, maximum 47 characters long

Example requests and notifications

Basic query

This is the format of a request to anonymously identify a user with basic information.

https://cta.mxtelecom.com/api?username=yourname&password=yourpass&action=basicuserquery

The Charge To Account Gateway would respond to this request with a redirect URL. Once the end user had visited the redirect URL on their mobile browser, the gateway would send a notification similar to this:

http://merchant.example.com/mxpay?queryId=123456&requirefulfilmentUrl=yes&availableBillingMechanisms=MOBILE&subscriptionIds=47240732%2C83689195&network=VIRGINUS&uniqueUserIdentifier=567481235f5d2vg3sdf22

This indicates that the end user:

has a mobile account which can accept billing (so you could charge the end user)
has two active subscriptions maintained in the Charge To Account Gateway, with subscriptionId values of 47240732 and 83689195 respectively (the %2C separating the two values is a URL-encoded comma)
is a Virgin Mobile USA subscriber
has the unique identifier of 567481235f5d2vg3sdf22—this is the same uniqueUserIdentifier returned by the gateway when this user is successfully charged or starts a subscription; your application can use it to track a user's history of transactions and visits

Extended query

This is the format of a request to anonymously identify a user with extended information.

https://cta.mxtelecom.com/api?username=yourname&password=yourpass&action=extendeduserquery

The Charge To Account Gateway would respond to this request with a redirect URL as before. Once the end user had visited the redirect URL on their mobile browser, the gateway would send a notification similar to this:

http://merchant.example.com/mxpay?queryId=123457&requirefulfilmentUrl=yes&availableBillingMechanisms=MOBILE&subscriptionIds=99689295&network=VIRGINUS&uniqueUserIdentifier=567481235f5d2vg3sdf22