Subscriptions API

Overview

This page provides details of how to use the MX Telecom Charge To Account Gateway to set up a subscription which will make recurring charges against a given end user.

If you only need to charge the user for a single payment, see the One-off charges documentation.

There is also a Developer Guide describing how this API can be used.

Contents

• Making requests using HTTP
• Setting up a subscription
• Concluding a subscription
• Restoring a subscription
• Unsubscribing a subscription
• Format of response from server
• Receiving notifications
• Notification API

Making requests using HTTP

The Charge to Account Gateway exposes an HTTPS interface for making requests to charge a user or set up a subscription. The endpoint for these HTTP requests is:

https://cta.mxtelecom.com/api

This URL accepts both GET and POST requests. The gateway's response to these requests is explained in Format of response from server below.

The parameters you use to specify the details of a subscription are explained in Setting up a subscription below.

Parameters should be URL encoded and UTF-8 encoded.

Setting up a subscription

This table details the parameters you can use when setting up a subscription:

Parameter	Required?	Meaning	Values allowed
username	Yes	Username for access to the gateway	username for your CTA Gateway account
password	Yes	Password for access to the gateway	password for your CTA Gateway account
responseFormat	No	The desired response format	plain - Plain text format (default) xml - XML format
action	Yes	The action to take	subscribe (to set up a subscription)
transactionMode	Yes	The desired authorisation and confirmation mode	AutoConfirm
brand	No	Pre-provisioned brand ID for accounts supporting multiple brands; if not included, default brand details will be used. See Branding for details.	specific to your account
tradingName	No	Changes the trading name displayed on screen for the end user. This enables you to set a different name per request for the same brand. All other details (including the logo) remain the same for the specified brand. See Branding for details. Default: The default trading name is displayed.	A text string up to 30 characters in length.
currency	Yes	A code denoting the currency of subscription charges e.g. GBP for British Pounds Sterling	three letter ISO 4217 currency code; currencies subject to account policy restrictions
amount	Yes	The amount to be charged per billing period in thousandths of the specified currency e.g. if currency=GBP, 5000 = £5 You must ensure that your account supports each charge value you send; some values may need to be provisioned for some networks	positive integer, range subject to account policy restrictions ; max charge for Payforit is 10000 (£10)
productGroup	Yes	Top level product grouping description, for your reference; can be set to an arbitrary value or generic	string, max 35 characters; e.g. Daily+Messages
productCat	Yes	Product category; can be set to an arbitrary value or generic; stored in the charge record for your reference	string, max 35 characters; e.g. Entertainment
productSubCat	Yes	Product subcategory; can be set to an arbitrary value or generic; stored in the charge record for your reference	string, max 35 characters; e.g. Horoscopes
productName	Yes	Product name; this will be displayed to users on the Payforit WAP pages. The Payforit rules specify that it must be "a clear statement that allows the consumer to associate the payment with what is being paid for."	string, max 35 characters; e.g. Your+Horoscope+(Virgo)
productDescription	Yes	Brief description of the product	string, max 200 characters
isAdult	Yes	The adult nature of the product. Possible values are: adult - the product is adult (end user's account must be verified as adult for the charge to succeed) nonadult - the product is not adult either - the product can be provided in either an adult or a non-adult version See Age Verification for details	adult, nonadult, either
note	No	A descriptive note that will be stored in the charge record	string, max 160 chars
subaccount	No	The subaccount that will be stored in the charge record	string, max 10 chars
subscriptionFreePeriod	No	The initial free period expressed in units of subscriptionFreePeriodUnits	non-zero integer; if there is no free period, omit the parameter
subscriptionFreePeriodUnits	Yes, if above is specified		Hours, Days, Weeks, Months
subscriptionPeriod	Yes	The billing period expressed in units of subscriptionPeriodUnits; how often the user is charged after any free period
subscriptionPeriodUnits	Yes		Hours, Days, Weeks, Months
subscriptionDuration	Yes	Number of billing periods before the subscription automatically terminates; for example, if the billing period is 1 week, a subscriptionDuration of 52 would mean that the subscription automatically ends after a year	integer or 0 for perpetual
subscriptionGraceTimeoutPeriod	No	If billing fails, how long after the charge is attempted that the gateway will retry charging until suspending the subscription.	integer (default is one day or the billing period, whichever is lower)
subscriptionGraceTimeoutPeriodUnits	Yes, if above is specified		Hours, Days, Weeks, Months
subscriptionSuspendedTimeoutPeriod	No	If a subscription is suspended, how long after the charge is attempted that the gateway will retry billing until unsubscribing the user.	integer (default is six months)
subscriptionSuspendedTimeoutPeriodUnits	Yes, if above is specified		Hours, Days, Weeks, Months
optIn	No	Determines the choices displayed for the user to opt in to future marketing messages on the post-confirmation page (see Marketing Opt-ins)	yes (default), no
postConfirmationPage	No	Determines the page displayed to the user after a successful WAP Payforit transaction. Possible values are: none—Send user straight to the fulfilment URL and send a confirmation SMS (optIn must equal no). confirmation—Show a confirmation page which asks for the marketing opt-ins specified with the optIn parameter. This parameter is ignored for Web Payforit transactions as the confirmation page cannot be skipped for these transactions.	none, confirmation (default)
channel	No	Used to identify whether the Charge To Account Gateway should use the WAP or Web Payforit workflow. When web is specified, the Charge To Account Gateway uses the Web Payforit workflow and displays the pages as webpages rather than WAP pages. If the Charge To Account Gateway cannot automatically gather the MSISDN of the end user's phone, and web has not been specified, then the Charge To Account Gateway will use the Web Lite workflow and display. See WAP vs. web initiated purchases for more information.	web, wap (default)
msisdn	No	Used in MT Web Payforit transactions. It is only used to pre-populate the MSISDN field on the user validation page.	447700900750

Concluding a subscription

If you conclude a subscription, it will continue until the end of the current billing period, then terminate.

The following parameters are required:

Parameter	Required?	Meaning	Values allowed
action	Yes	The action to take.	For a conclude subscription request this should be concludeSubscription
subscriptionId	Yes	The unique ID of the subscription to be concluded.

An example request is:

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

Restoring a subscription

If you restore a subscription which is concluding, it will not terminate at the end of the current billing period.

The following parameters are required:

Parameter	Required?	Meaning	Values allowed
action	Yes	The action to take.	For a subscription restore request this should be restoreSubscription
subscriptionId	Yes	The unique ID of the subscription to be restored.

An example request is:

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

Unsubscribing a subscription

If you unsubscribe a subscription, it terminates immediately.

The gateway will not process any outstanding charge retry attempts which have not already been instigated.

The following parameters are required:

Parameter	Required?	Meaning	Values allowed
action	Yes	The action to take	For an unsubscribe request this should be unsubscribe
subscriptionId	Yes	The unique ID of the subscription to be unsubscribed.

An example request is:

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

Format of response from server

The gateway's response to all requests uses the HTTP response code to indicate whether or not the request was accepted:

Response Code	Description
200	The request was accepted.
40x	The request was invalid. The possible reasons for this are outlined below.
50x	There was a server error.

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.

In order to confirm a request for a new subscription, the user must visit a WAP confirmation page so that their MSISDN can be detected; the gateway will indicate in its response that user input is required and provide a URL for the confirmation page.

These are the possible name/value pairs when the gateway responds to a subscription request:

Name	Returned if?	Meaning	Values allowed
outcome	Always	Result of the request	rejected, success, failed or userinputrequired
outcomeReasonId	Always	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	Always	Natural language description of the outcome	string
subscriptionId	Outcome is success, failed or userinputrequired	Unique ID of the subscription	64-bit unsigned integer e.g. 69134309
redirectUrl	Outcome is userinputrequired	URL which the user must visit to confirm the subscription, prefixed with redirectUrl:	e.g. redirectUrl:http://mxpay.net/3/6PXQnZIHTh
requestId	Request is to unsubscribe, conclude or restore	Unique ID of this particular request	64-bit unsigned integer prefixed with cta-rid- e.g. cta-rid-20043781

An example plain text response:

outcome:success

outcomeReasonId:1000
outcomeReasonText:Request was successful.
subscriptionId:45312560 
requestId:cta-rid-73403073

An example XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <outcome>success</outcome>
  <outcomeReasonId>1000</outcomeReasonId>
  <outcomeReasonText>Request was successful.</outcomeReasonText>
  <subscriptionId>45312560</subscriptionId>
  <requestId>cta-rid-73403073</requestId>
</response>

All additional information, including response information specific to a particular type of request, will be returned as parameters in the body of the response in a similar fashion.

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.
success	200	Yes	The request was accepted and is being processed.
failed	200	Yes	The request was accepted but the transaction failed. See the status codes documentation for more details.
userinputrequired	200	Yes	The request was accepted but additional user information and/or confirmation is required.

Receiving notifications

Whenever the status of a subscription changes, the MX Telecom Charge To Account Gateway notifies you via an HTTP request to a server you control. Notifications are also used to inform you of user marketing opt-in preferences.

Each subscription you request is identified by the gateway with a unique subscriptionId. The subscriptionId is returned in all notifications about the subscription.

You specify the destination URL for incoming notifications when your account is set up. A different URL can be set for each brand configured to your account (see Branding for details).

Your server should return an HTTP 200 response with a non-empty body. This response must 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.

If a fulfilment URL is to be returned, then it should be inserted into the HTTP body in plain text prefixed with fulfilmentUrl: and should be no longer than 255 characters, e.g.:

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

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 83.166.68.0 -> 83.166.69.255)

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

Notification API

This is an example of a notification request which the Charge To Account Gateway would make to your server to confirm a successful subscription:

http://merchant.example.com/mxpay?subscriptionId=60006878&updateId=96162605&subscriptionState=subscribed&outcomeReasonId=285278464&outcomeReasonText=Subscription+subscribe+request+successful&requirefulfilmentUrl=yes&date=2008-05-06+13%3A36%3A59+%2B0100&msisdn=447700900999&network=TMOBILEUK&ageVerified=no&uniqueUserIdentifier=Lrmi9u%2BI9HOzYX27VzQoHzzscqsdZdxcfLk5pe8HoUA%3D&useragent=SonyEricssonD750i...&channel=wap

This table describes the parameters the gateway uses when sending subscription state notifications:

Parameter	Always present?	Meaning	Values allowed
subscriptionId	Yes	The subscriptionId of the subscription that has been updated	64-bit unsigned integer e.g. 69134309
updateId	Yes	A unique ID identifying the specific update to the given subscription; this can be used to filter duplicate updates if received.
requestId	No	A unique ID identifying the request which triggered this notification; applies to notifications from unsubscribe, conclude or restore requests. The requestId value is assigned in the gateway's initial HTTP response to the request. See Format of response from server above.	64-bit unsigned integer prefixed with cta-rid- e.g. cta-rid-20043781
subscriptionState	Yes	The current state of the subscription.	See table below for full details.
outcomeReasonId	No	A numeric code identifying a detailed reason for the status change.	See table of outcome reasons for full details.
outcomeReasonText	No	Natural-language description of the outcomeReasonId.	See table of outcome reasons for full details.
ageVerified	No	Indicates whether the user has been age verified as an adult. If no parameter is present, it should be assumed that the user's age verification status is unknown See Age Verification for details	yes - the user is age verified no - the user is not age verified
requirefulfilmentUrl	Yes	Indicates whether or not the Charge To Account Gateway requires a fulfilment URL for the transaction The fulfilment URL should be a suitable page for the end user to continue browsing after being redirected from the WAP pages hosted by the gateway. The content of the page indicated should take into account the state of the subscription attempt.	yes - a fulfilment URL is required no - a fulfilment URL is not required
date	Yes	The date and time of the update; the time zone indicated is relative to GMT	yyyy-MM-dd HH:mm:ss ±hhmm e.g. 2008-04-29 14:31:02 +0100
channel	Yes	Denotes the way in which the end user originally accessed your site. See WAP vs. web initiated purchases for more information. Note that subscription state notifications will always show the same original value, while transaction notifications will show whether the charge occurred due to direct user input or was automated.	wap , web, weblite

subscriptionState parameter

The meaning of the subscriptionState parameter is as follows:

subscriptionState	Meaning
awaitinguserinput	The user needs to accept the subscription in order for setup to proceed.
subscribed	The user is currently subscribed
failed	The subscription setup has failed. The reason for the failure is given by the outcomeReasonId value.
expired	The user did not confirm or cancel the subscription within the expected timeframe.
cancelled	The user cancelled the subscription when asked for input.
suspended	The subscription has been suspended but billing will be retried. The reason for the suspension is given by the notifications sent at the time the subscription entered this state.
concluding	The subscription is concluding and will be unsubscribed at the end of the current billing period.
unsubscribed	The user has been unsubscribed. The subscription is permanently ended.

To determine why the subscription entered a particular state, you should interpret the outcomeReasonId value. See the Subscription status outcomeReasonId codes table on the Status codes page.

Subscription confirmation

If a request for a new subscription is confirmed, the gateway will send the following additional parameters in the notification:

Parameter	Always present?	Meaning	Values allowed
msisdn	Yes	The mobile number of the end user	international format with no leading + e.g. 447700900750
uniqueUserIdentifier	Yes	A unique identifier based on msisdn (see Anonymous User Identification)	URL-encoded, maximum 47 characters long
useragent	Subject to account policy	The useragent of the end user's mobile browser	string, cropped to the first 255 characters of the useragent if necessary
network	Yes	The network of the end user	See table of network codes
mvno	Only for certain mobile virtual networks	The mobile virtual network of the end user. Note that for technical reasons, this will not be returned for users of most MVNOs, and the gateway will instead report them as a user of the mother network operator.	virgin
ageVerified	Only if available from the network	Indicates whether the user has been age verified as an adult. If no parameter is present, it should be assumed that the user's age verification status is unknown See Age Verification for details	yes - the user is age verified no - the user is not age verified

Post-confirmation notifications

If you have requested the Charge to Account Gateway to collect marketing opt-in, a separate notification is sent after the subscription has been confirmed.

Parameter	Always present?	Meaning	Values allowed
subscriptionId	Yes	The unique ID of the subscription as returned in the original response
marketingOptIn	Yes	Whether or not the user has opted in to receive free marketing updates from the content provider who originates the charge	yes, no

See the Marketing opt-in page for further details.

Charge notification

When a charge is made as part of a subscription, the gateway sends a notification about the charge using the parameters in the table below.

If a charge fails, the gateway will not send a notification for each retry attempt. It will only send a notification about the initial failure and one about the eventual success or permanent failure of the charge attempt. The same transactionId is present in all notifications about a particular charge.

Charges will also generate a separate subscription notification (as above). For example a successful charge would generate a notification that the charge had succeeded, and a "billing successful" notification for the subscription.

Parameter	Always present?	Meaning	Values allowed
transactionId	Yes	Unique identifier for the charge.	64-bit unsigned integer
subscriptionId	Yes	Unique identifier for the subscription.	64-bit unsigned integer
updateId	Yes	A unique ID identifying the specific update to the given subscription; this can be used to filter duplicate updates if received.
transactionState	Yes	The current state of the charge.	See table of transactionState meanings for details
outcomeReasonId	No	A code describing the reason for the charge outcome.	See table of outcome reasons for details
outcomeReasonText	No	Natural-language description of the outcomeReasonId.	See table of outcome reasons for details
requirefulfilmentUrl	Yes	Indicates whether the Charge To Account Gateway requires a fulfilment URL for directing the end user. For a charge this is always no	no
msisdn	Yes	The mobile number of the end user.	international format with no leading + e.g. 447700900750
uniqueUserIdentifier	Yes	A unique identifier based on msisdn (see Anonymous User Identification).	URL-encoded, max 47 characters long
network	Yes	The network of the end user.	See table of network codes
mvno	Only for selected mobile virtual networks	The mobile virtual network of the end user. Note that, for technical reasons, this will not be returned for users of most MVNOs, and the gateway will instead report them as a user of the mother network operator.	virgin
channel	Yes	Whether the charge occurred due to direct user input or was automated. If a subscription does not have an initial free period, then the first charge for the subscription will show the browsing method the end user was using. This will be one of wap, web or weblite (see WAP vs. web initiated purchases for more information). For all other charges, such as a monthly subscription renewal charge, the parameter will have the value direct. This shows that the charge was initiated by the Charge To Account Gateway or your application.	wap, web, weblite, direct