Anonymous User Identification API

Overview

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

The PayForIT rules mean that a user's mobile number (MSISDN) is only available to your application after they make a payment or subscribe to a service.

By using the AUID API, you can both uniquely identify and retrieve details about an end user without needing to know their MSISDN. For each user, you can determine:

the mobile network on which they are a subscriber (if available)
their age-verified status (if available)
what billing mechanisms are available to charge the user
a list of any active Charge To Account Gateway subscriptions they have with you
a unique identifier for this user, which is also returned when a user is successfully charged or starts a subscription (if available)

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 a secure HTTP 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
responseFormat	No	The desired response format	plain - Plain text format (default) xml - XML format
action	Yes	The type of request	basicuserquery - Returns limited information extendeduserquery - Returns extended information

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 - e.g.:

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	Extended	The mobile network of the end user	See table of network codes
uniqueUserIdentifier	No	Extended	Unique user identifier (if the MSISDN is available).	URL-encoded string, maximum 47 characters long
ageVerified	No	Extended	Whether or not the user has been age verified as adult. If no parameter is present it should be assumed that the user's age verification status is unknown	yes, no

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=extendeduserquery

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

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

This indicates that the end user:

has a mobile account which can accept billing (so you could charge the end user via PayForIT)
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)

Extended query

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