Subscriptions Developer Guide

Overview

This guide is intended for developers who wish to integrate the Charge To Account Gateway with an existing application to enable charging for subscriptions.

The Charge To Account Gateway provides subscription functionality compliant with the Payforit trusted payment scheme. If you are not familiar with Payforit, please refer to our introduction to the scheme.

Your application can set up a recurring charge for a given end user. The gateway handles billing and notifies your application if a subscription has been suspended due to non-payment.

The gateway also handles unsubscriptions initiated by the end user texting STOP to a short code.

Note that it is the responsibility of your application to handle the delivery or hosting of any content associated with a subscription.

In this guide, the term "end user" refers to the mobile phone user who is purchasing a subscription using their handset. The term "merchant site" refers to the application which is using the gateway to charge users.

Integration requirements
Types of subscription
Timed subscriptions
Automatic suspension and unsubscription of timed subscriptions
Timed subscription management
Ad hoc subscriptions
Ad hoc charge retries and queuing
Automatic unsubscription of ad hoc subscriptions
Ad hoc subscription management
Subscription setup workflow
- Subscription success workflow
- Subscription failure workflow
End user STOP requests
Example requests and notifications
API reference

Integration requirements

Integrating an application with the Charge To Account Gateway involves using a simple HTTP interface.

An application tells the gateway to create or modify a subscription using a secure HTTP GET or POST request.

Each application must also provide a URL for incoming notifications from the gateway about the status of charges and subscriptions, for example:

http://merchant.example.com/mxpay

This URL is specified when your gateway account is set up.

Notifications are made as HTTP or HTTPS GET requests to this URL. The possible parameters are defined by the Notification API.

A URL which supports the API must answer incoming notifications with an HTTP 200 response. It should respond within ten seconds.

Mobile networks only support certain charge values. You must ensure that any charge you wish to make is supported by your account. Contact your account manager for details.

Types of subscription

The Charge To Account Gateway supports two types of subscription:

timed: A timed subscription allows an end user to be charged at a pre-determined interval. The price point and interval are specified by the application at the point of subscription setup. Repeat billing is then handled by the Charge To Account Gateway.
ad hoc: An ad hoc subscription allows an end user to be charged at varying intervals. The price point is specified by the application at subscription setup. Charges can then be levied at the discretion of the application.

Timed subscriptions

A timed subscription is used for applications where the user should be charged at regular intervals.

Examples of applications which could be implemented using a timed subscription:

a daily cartoon delivered by MMS
a weekly subscription for access to a mobile website
a service offering unlimited access to a collection of ringtones for a single monthly charge

The interval between charges is called the period of the subscription.

Optionally, the subscription can initially operate without charges for a free period. The duration of the free period does not have to be related to the length of the period between charges.

A subscription can run either for a set number of periods, or indefinitely.

The number of periods until a fixed-length subscription automatically ends is called its duration.

Automatic suspension and unsubscription of timed subscriptions

Timed charges will sometimes fail due to a transient error; the gateway will notify you and automatically retry the charge.

However, if attempts to charge the end user's mobile account fail for an defined period of time, the gateway will automatically suspend the subscription. Usually, your application would prevent use of the subscription content or service while the subscription is suspended.

The time between the first billing failure and suspension is called the grace timeout period. You can specify it in your initial request to set up the subscription.

During the grace period, the gateway retries the charge and the subscription remains active.

If billing attempts continue to fail, a suspended subscription is automatically unsubscribed. The time between the first billing failure and final unsubscription is called the suspended timeout period. It is also defined in your initial request to set up the subscription.

Note that, since the suspended timeout period begins from the first billing failure, the time that a subscription stays suspended will be the duration of the suspended timeout period minus the grace timeout period.

While the subscription is suspended, the gateway continues to attempt to bill the user in order to restore the subscription.

Depending on the period of the subscription and the value of the suspended timeout period, there may be several outstanding charges at the point when billing is successful.

For example, suppose a subscription was set up to charge every week, but the suspended timeout period was one month. If the mobile account became unbillable for a period of 22 days then began accepting charges again, there would be three outstanding charges to process: the initial charge request, plus the charges for the following two weeks.

The gateway applies any outstanding charges in sequence. The grace and suspended timeout periods then begin from the time that the payments succeed.

Suspending accounts is handled only by the gateway. Your application cannot send a request to suspend a subscription. It will be notified of a suspension through the HTTP Notification API and must respond accordingly.

Timed subscription management

A number of API methods are provided to allow your application to manage a timed subscription. These are:

subscribe: Creates a new subscription. The price point, billing period and duration are specified at this point, along with other configuration options.
unsubscribe: If your application makes an unsubscribe request for a subscription, the subscription will be immediately and permanently ended. Any outstanding charge retries (which have not already been initiated) are abandoned.
concludeSubscription: If your application makes a request to conclude a subscription, when the next billing period is reached, the user will not be billed, and will be unsubscribed instead.
restoreSubscription: If a restore request is sent while a subscription is concluding or suspended, the user will re-enter the subscribed state, and will be billed again at the start of the next billing period. This may be used automatically (as part of the design of the integrated application) or manually (in response to a customer service call).

This diagram shows the possible states for a timed subscription, the transitions between them and the context of the management API calls (in red):

Timed Subscription State Lifecycle

Whenever the state of the subscription changes, an HTTP notification is made to the application so that it can undertake any necessary actions. A separate transaction notification is also made for each timed charge.

If a charge fails and has to be retried, a notification is made for the initial failure and a second notification is sent when the charge either succeeds or fails permanently.

Ad hoc subscriptions

An ad hoc subscription is used for applications where the end user is billed at the discretion of your application, instead of at fixed intervals. (This type of billing is not available on all carriers; see Carrier Differences for details).

Examples of applications which could be implemented using an ad hoc subscription:

a stock market alert service which sends an SMS when a particular company's share price reaches a certain level, with the user being charged for each alert
a pay-per-view mobile content service which charges for each browsing session or page
a weather alert service which warns the user of severe weather within a certain area

When an ad hoc subscription is set up, an arbitrary billing frequency (for example, "stock alert", "browsing session") is defined along with a price point for each charge. (Every charge for a given ad hoc subscription has the same value).

Optionally, a duration can be specified, after which the subscription will automatically be unsubscribed.

Unlike with a timed subscription, the Charge To Account Gateway does not automatically apply charges to an ad hoc subscription. Your application must instigate each charge separately by sending HTTP charge requests (see the Making an ad hoc charge section of the Subscription API for details).

Ad hoc charge retries and queuing

A charge may be applied to an active subscription at any time, at the discretion of your application. In the charge request you specify the validity period of a charge, which defines how long the gateway will keep retrying the charge in the event of a charge failure (which might occur, for example, if the end user is out of credit).

The validity period can be set from 30 seconds to three days, depending on what is most suitable for your application.

If multiple charges are requested, they will be queued by the gateway and applied in the order they were requested. Note that the validity period begins to elapse as soon as a charge is requested.

For example, two charges with validity periods of an hour are applied at 10:00pm and 10:10pm. The first charge initially fails and is retried until it succeeds at 10:30pm. The second charge is now attempted for the first time. If it fails, it will only retry until 11:10pm (one hour after it was requested).

Automatic unsubscription of ad hoc subscriptions

Unlike timed subscriptions, ad hoc subscriptions do not have a suspended state.

You can configure the Charge To Account Gateway to automatically unsubscribe an ad hoc subscription due to repeated failed charges or inactivity.

The gateway can unsubscribe an ad hoc subscription after a certain number of billing failures (charge attempts which fail permanently; this does not include a charge which fails, is retried and eventually succeeds).

The gateway can unsubscribe a subscription after a continuous billing failure period. If a charge fails, and no successful charges are made during the defined billing failure period, the subscription will end. Note that this will occur even if no more charges are attempted after the initial failure.

The gateway can unsubscribe a subscription after a continuous inactivity period where no charges are attempted. Suppose your application made an ad hoc charge when the end user visited a certain mobile site; using an inactivity period, you could automatically unsubscribe users who had not visited the site for three months.

All of these periods can be defined in your initial request to set up the subscription.

Ad hoc subscription management

The following API methods are provided to allow your application to manage an ad hoc subscription:

subscribe: Creates a new subscription. The price point for each charge is specified at this time.
charge: Attempts to make a charge at the predefined price point, and retries for the validity period specified for the charge request.
unsubscribe: If your application makes an unsubscribe request the subscription is immediately and permanently ended. Any outstanding charge retries (which have not already been initiated) or queued pending charges are abandoned.
concludeSubscription: If your application makes a request to conclude an ad hoc subscription, any queued charges are processed as usual. Once all outstanding charges either succeed or reach the end of their validity period, the subscription is unsubscribed.
restoreSubscription: If a restore request is sent while an ad hoc subscription is concluding, the subscription re-enters the subscribed state. Note that a subscription which is concluding due to the end user sending a STOP message (see below) cannot be restored.

This diagram shows the possible states for an ad hoc subscription, the transitions between them and the context of the management API calls (in red):

Adhoc Subscription State Lifecycle

Whenever the state of the subscription changes, an HTTP notification is made to the application so that it can undertake any necessary actions. As with timed charges, a separate transaction notification is made for each ad hoc charge.

If an ad hoc charge fails, one notification is sent for the initial failure, and a second is sent when the charge either succeeds or fails permanently (e.g. the validity period expires or the subscription is unsubscribed).

Subscription setup workflow

This example gives an overview of how a merchant site integrated with the Charge To Account Gateway would set up a timed subscription service.

Subscriptions with Payforit and the Charge To Account Gateway

The end user, browsing the merchant's WAP site, chooses a subscription service. The user experience up until the point of purchase is handled through the merchant's existing mobile store.
When the end user selects the subscription, the merchant site makes a secure GET or POST HTTP request to the Charge To Account Gateway at:

https://cta.mxtelecom.com/api

Details of the end user's desired subscription (including the service name, frequency of charges, cost per billing period, and any free subscription period) are sent as parameters to the request. The merchant's identity is verified with a username and password, also passed as parameters.

The merchant does not need to know the end user's mobile number to initiate subscription setup.

This truncated example shows the basic structure of a subscription request:

http://cta.mxtelecom.com/api?username=yourname&password=yourpass&action=subscribe&transactionMode=AutoConfirm…

For details of how to make a subscription request, see the Subscriptions API.
The Charge To Account Gateway responds with a payment verification URL hosted by MX Telecom.

The URL is returned (along with a unique subscriptionId parameter) in an HTTP response body similar to the following:
```
		outcome:userinputrequired
		outcomeReasonId:2002
		outcomeReasonText:Missing information that requires user input.
		redirectUrl:http://mxpay.net/3/n9RA946xMZOOvJiVbSodA0qI...
		subscriptionId:84282631
		      
```
The request for "user input" simply means that the end user must visit a payment verification URL hosted by the gateway so that their mobile number (MSISDN) can be confirmed.

The subscriptionId is used to refer to this subscription throughout the rest of its lifecycle.

Each charge made against this subscription is assigned a transactionId.
The merchant site must now direct the end user's mobile browser to the payment verification URL supplied by the gateway. This enables the gateway to verify the user's mobile number (MSISDN).

In this example, the end user's browser still has an HTTP connection to the merchant site open, so the merchant can return a redirect response to send the browser to the payment verification URL.
The end user arrives at the URL. The page provides a clear explanation of the subscription and the cost involved, in line with the PayForIT rules. The user follows the "Subscribe" link to confirm the subscription.
At this point the Charge To Account Gateway attempts to set up the subscription.

If there is an initial free period, or it is an ad hoc subscription, the subscription begins straight away.

For a timed subscription without a free period, the gateway makes the charge for the first period, and the subscription is only set up if the charge succeeds.

Subscription success workflow

To continue the example, we assume that the subscription has been successfully set up.

Payment confirmation and fulfilment with Payforit and the Charge To Account Gateway

The Charge To Account Gateway notifies the merchant application of the successful subscription using a GET request to the notification URL provided by the merchant application.

The notification from the gateway would be structured like this:

http://merchant.example.com/mxpay?subscriptionId=84282631&updateId=123&subscriptionState=subscribed&requirefulfilmentUrl=yes…

The subscriptionId value is the same as that previously returned along with the payment verification URL. This allows the merchant application to link related notifications.

If the initial charge is successful, the notification includes the end user's MSISDN and network. If the charge fails, these details are not returned (this is a requirement of the PayForIT rules).

The notification also contains a request for a fulfilment URL. The fulfilment URL should be a suitable location for the end user to continue the WAP browsing session after leaving the gateway-hosted PayForIt pages. This might be a page welcoming the user to the service, or the address of content which they are paying to access on a subscription basis.

For a failed subscription attempt, the gateway still requests a fulfilment URL; in this case, it should be a suitable page for the user to continue browsing after being presented with the gateway-hosted payment failure screen.
The merchant acknowledges the request with an HTTP 200 response containing the fulfilment URL (in plain text and no longer than 255 characters) presented like this:
```
fulfilmentUrl:http://merchant.example.com/subscribed/productId/foo...
		
```
The Charge To Account Gateway redirects the end user to a page acknowledging the successful subscription and offering the chance to opt in to marketing messages (optional, depending on the original request).
The end user selects their marketing preferences and clicks 'Continue'.
The Charge To Account Gateway redirects the user to the fulfilment URL provided by the merchant.
Finally, the Charge To Account Gateway sends details of the end user's marketing opt-in choices using the Notification API.
http://merchant.example.com/mxpay?transactionId=127384&marketingOptin=yes&marketingPartnerOptin=no

Subscription failure workflow

This section shows the workflow if the subscription attempt fails.

For a timed subscription with no free period, the gateway will attempt the first charge straight away. If the charge attempt fails, the subscription is not set up. Charging can fail for a number of reasons; for example, a pre-pay account may not have sufficient credit.

For a timed subscription with a free period, or an ad hoc subscription, the gateway will not attempt to make an initial charge, but the attempt to subscribe could still fail for other reasons (for example, user cancellation).

PayForIt one-off charge failure workflow

The Charge To Account Gateway notifies the merchant application of the failed subscription attempt using a GET request to the notification URL provided by the merchant application.

http://cta.mxtelecom.com/api?subscriptionId=subscriptionId=84282631&updateId=123&subscriptionState=cancelled&outcomeReasonId=285279488&outcomeReasonText=Subscription+cancelled%3A+request+successful.&requirefulfilmentUrl=yes…
The merchant responds with a fulfilment URL as before.

Note that the gateway still requests a fulfilment URL even though the subscription request failed. In this case, the fulfilment URL should be a suitable place for the user to continue browsing after being presented with the gateway-hosted error�screen.
The Charge To Account Gateway redirects the end user to an error page explaining that the subscription attempt has failed.
The end user clicks 'Continue'.
The Charge To Account Gateway redirects the user to the fulfilment URL provided by the merchant.

End user STOP requests

If the end user sends a STOP message by SMS, the Charge To Account Gateway will apply it to the last subscription from which that user received an SMS. (The gateway sends each user an SMS notification of all their subscriptions every month, or per �20 spent, as specified by the PayForIT guidelines.)

For a timed subscription, a user STOP is equivalent to an unsubscribe request.
For an ad hoc subscription, a user STOP is equivalent to a conclude request; pending charges submitted before the stop will still be processed, and your application cannot restore a subscription which is concluding due to a user STOP message.

If the end user sends STOPALL, the gateway will unsubscribe/conclude the last subscription from which that user received an SMS and all subscriptions on the same CTA brand.

Example requests and notifications

Setting up a timed subscription

This is an example request for a timed subscription. Not all of the options used in this request will be available for all carriers.

https://cta.mxtelecom.com/api?username=yourname&password=yourpass&action=subscribe&transactionMode=AutoConfirm&amount=250&currency=GBP&productName=Ringtones&productDescription=Ringtones+Deal+1&productGroup=Ringtones&productCat=Audio&productSubCat=Music&isAdult=no&subscriptionFreePeriod=4&subscriptionFreePeriodUnits=Days&subscriptionPeriod=1&subscriptionPeriodUnits=Weeks&subscriptionDuration=52&subscriptionGraceTimeoutPeriod=1&subscriptionGraceTimeoutPeriodUnits=Days&subscriptionSuspendedTimeoutPeriod=1&subscriptionSuspendedTimeoutPeriodUnits=Weeks&postConfirmationPage=confirmation&optIn=partner

This request does not include some optional parameters, so the gateway assumes default values.

The subscription confirmation page would look like this:

Ringtones is the productName value defined in the original request
4 days is the free period defined for this subscription by the subscriptionFreePeriod and subscriptionFreePeriodUnits values.
�2.50 is the recurring charge defined by the amount and currency values.
"per week" is displayed because the subscription period is defined as one week by the subscriptionPeriod and subscriptionPeriodUnits
Merchant is the merchant shop/site name (see Branding)
Terms and Conditions leads to merchant details (see Branding)
Operator Data Charges may apply leads to a standard terms and conditions messagespecified by the PayForIT scheme rules

Once the user has selected Subscribe and the subscription has been set up successfully, the post-confirmation page will be presented:

Depending on the parameters of the original request, the marketing opt-in can be omitted or the post-confirmation page can be skipped - see Marketing opt-ins
Delivery information can be collected on this page to support the sale of physical goods - see Delivery information collection

The gateway also sends the following SMS confirmation message to the end user:

FreeMsg: U have joined Ringtones for 4 days no charge, then �0.50 per week until you send STOP to 58870. Helpline 0808 1570 555

The STOP short code and helpline number are configured when your account is set up (see Branding).

If the timed subscription in the Ringtones example above was successfully set up, the notification sent from the gateway to the merchant site would look like this:

http://merchant.example.com/mxpay?subscriptionId=9654572&updateId=30639074&state=subscribed&subscriptionState=subscribed&reasonid=5006&reasontext=Subscription+subscribe+request+successful&outcomeReasonId=285278464&outcomeReasonText=Subscription+subscribe+request+successful&requirefulfilmentUrl=yes&date=2008-06-04+15%3A26%3A56+%2B0100&msisdn=447700900999&uniqueUserIdentifier=Lrmi9u%2BI9HOzYX27VzQoHzzscqsdZdxcfLk5pe8HoUA%3D&network=TMOBILEUK&useragent=SonyEricssonD750i%2FR1AA+Browser&channel=wap

Note that the subscriptionId value in the notification will match the value returned in the HTTP response to the original subscription setup request. All notifications about a particular charge will be identified with the same subscriptionId value.

The subscriptionState value of subscribed means that the subscription was successful.

If a subscription request fails or setup is not successfully completed, a notification will be sent giving the reason.

In this example, the subscription was not set up because the end user pressed 'Cancel' at the payment confirmation screen:

http://merchant.example.com/mxpay?subscriptionId=9654572&updateId=30639074&state=cancelled&subscriptionState=cancelled&reasonid=5003&reasontext=Subscription+cancel+request+successful&outcomeReasonId=285279488&outcomeReasonText=Subscription+cancelled%3A+request+successful.&requirefulfilmentUrl=yes…

In this example, the end user did not confirm or cancel the charge within an hour, so the transaction was abandoned:

http://merchant.example.com/mxpay?subscriptionId=9654572&updateId=55530152&state=confirmfailed&subscriptionState=failed&reasonid=4222&reasontext=Subscription+subscribe+failed%3A+Authorization%2Fconfirmation+timed+out&outcomeReasonId=17105153&outcomeReasonText=Subscription+subscribe+failed%3A+Confirmation+timed+out.…

Timed charge notifications

If a timed subscription with no free period is requested, the first timed charge is levied as soon as the user confirms the subscription.

This is an example request to set up a subscription with no initial free period. To do this, simply omit the subscriptionFreePeriod parameter.

https://cta.mxtelecom.com/api?username=yourname&password=yourpass&action=subscribe&transactionMode=AutoConfirm&amount=100&currency=GBP&productName=Virgo+Horoscope&productDescription=Daily+Horoscope+Virgo&productGroup=Daily+Texts&productCat=Spiritual&productSubCat=Astrology&isAdult=no&subscriptionPeriod=1&subscriptionPeriodUnits=Days&subscriptionDuration=365&postConfirmationPage=confirmation

Assuming the charge succeeds, the gateway sends two separate notifications: one to say that the charge transaction has succeeded:

http://merchant.example.com/mxpay?transactionId=66693716&updateId=99580043&state=confirmed&transactionState=confirmed&requirefulfilmentUrl=no&date=2008-06-16+14%3A32%3A09+%2B0100&subscriptionId=48417867&msisdn=447700900999&uniqueUserIdentifier=Lrmi9u%2BI9HOzYX27VzQoHzzscqsdZdxcfLk5pe8HoUA%3D&network=TMOBILEUK&channel=wap

and one to say that the subscription state has changed:

http://merchant.example.com/mxpay?subscriptionId=48417867&updateId=94540691&state=subscribed&subscriptionState=subscribed&reasonid=5006&reasontext=Subscription+subscribe+request+successful&outcomeReasonId=285278208&outcomeReasonText=Subscription+subscribe+request+successful.&requirefulfilmentUrl=yes&date=2008-06-16+14%3A32%3A10+%2B0100…

Note that it is easy for your application to associate the transaction notification with the relevant subscription, because both notifications have the same subscriptionId value.

The gateway sends a similar pair of notifications when a timed charge succeeds:

http://merchant.example.com/mxpay?transactionId=12618707&updateId=4764035&state=confirmed&transactionState=confirmed&requirefulfilmentUrl=no&date=2008-06-16+16%3A08%3A46+%2B0100&subscriptionId=48417867&msisdn=447700900999&uniqueUserIdentifier=Lrmi9u%2BI9HOzYX27VzQoHzzscqsdZdxcfLk5pe8HoUA%3D&network=TMOBILEUK&channel=direct

http://merchant.example.com/mxpay?subscriptionId=48417867&updateId=61932455&state=subscribed&subscriptionState=subscribed&reasonid=5008&reasontext=Timed+Subscription+billing+complete&outcomeReasonId=285344000&outcomeReasonText=Timed+billing+complete%3A+billing+successful.&requirefulfilmentUrl=no&date=2008-06-16+16%3A08%3A46+%2B0100&msisdn=447700900999&uniqueUserIdentifier=Lrmi9u%2BI9HOzYX27VzQoHzzscqsdZdxcfLk5pe8HoUA%3D&network=TMOBILEUK&useragent=SonyEricssonD750i%2FR1AA+Browser&channel=wap

Note that the channel for the timed charge is now direct, rather than wap.
channel is direct for all subscription charges that do not involve direct end user input: this is any charge except the first charge of a timed subscription without an initial free period.

Setting up an ad hoc subscription

This is an example request for an ad hoc subscription.

https://cta.mxtelecom.com/api?username=yourname&password=yourpass&responseFormat=plain&action=subscribe&transactionMode=AutoConfirm&amount=250&currency=GBP&productName=Storm+Alerts&productDescription=Severe+Weather+Alerts&productGroup=Info&productCat=Alerts&productSubCat=Weather&providerType=mobile&isAdult=no&arbitrarySubscriptionPeriodUnits=storm+alert&permittedBillingFailures=3&permittedInactivityPeriod=12&permittedInactivityPeriodUnits=Months&permittedBillingFailurePeriod=4&permittedBillingFailurePeriodUnits=Weeks&postConfirmationPage=confirmation&optIn=partner

Storm alerts is the productName value defined in the original request
storm alert is the item being charged for on an ad hoc basis, as defined by arbitrarySubscriptionPeriodUnits.
�0.25 is the amount of each ad hoc charge, as defined by the amount and currency values.
Merchant is the merchant shop/site name (see Branding)
Terms and Conditions leads to merchant details (see Branding)
Operator Data Charges may apply leads to a standard terms and conditions message specified by the Payforit scheme rules

This subscription would allow three consecutive billing failures before it was automatically unsubscribed.

After a charge failed, if a successful charge had not been made within four weeks, the subscription would automatically be unsubscribed due to the permitted billing failure period.

If no storm alerts were sent for 12 months, the subscription would also be automatically unsubscribed.

Making an ad hoc charge

This is an example request to make an ad hoc charge.

https://cta.mxtelecom.com/api?username=yourname&password=yourpass&responseFormat=plain&action=charge&subscriptionId=21903821&validity=20

The request will expire after 20 minutes.

The HTTP response to the charge request would look like this:

outcome:success
outcomeReasonId:1000
outcomeReasonText:Request was successful.
subscriptionId:21903821
requestId:cta-rid-88698380

Just as with a timed charge, your application will receive two notifications about an ad hoc charge attempt.

One notification is about the charge transaction:

http://merchant.example.com/mxpay?transactionId=95215843&updateId=1272392&state=confirmed&transactionState=confirmed&requirefulfilmentUrl=no&date=2008-06-16+19%3A33%3A46+%2B0100&subscriptionId=21903821&msisdn=447700900999&uniqueUserIdentifier=Lrmi9u%2BI9HOzYX27VzQoHzzscqsdZdxcfLk5pe8HoUA%3D&network=TMOBILEUK&ageVerified=no&channel=direct&requestId=cta-rid-88698380

and one is about the subscription status:

http://merchant.example.com/mxpay?subscriptionId=21903821&updateId=16541096&state=subscribed&subscriptionState=subscribed&reasonid=5007&reasontext=Arbitary+Subscription+billing+complete&outcomeReasonId=285343744&outcomeReasonText=Ad+hoc+charge%3A+billing+successful&requirefulfilmentUrl=no&date=2008-06-16+19%3A33%3A46+%2B0100&msisdn=447700900999&uniqueUserIdentifier=Lrmi9u%2BI9HOzYX27VzQoHzzscqsdZdxcfLk5pe8HoUA%3D&network=TMOBILEUK&ageVerified=no&useragent=SonyEricssonD750i%2FR1AA+Browser&channel=wap&requestId=cta-rid-88698380

Note that the common requestId value allows you to associate your request for the charge with subsequent notifications about it.

Charge failure notifications

The Charge To Account gateway will notify you the first time that a charge fails, then again when the charge succeeds or fails permanently. It will not send a notification for every retry.

Here is an example of a charge failure notification for the Ringtones timed subscription created above:

http://merchant.example.com/mxpay?transactionId=32561714&updateId=19301445&state=retrying&transactionState=retrying&requirefulfilmentUrl=no&date=2008-06-16+16%3A10%3A48+%2B0100&subscriptionId=9654572&outcomeReasonId=65794&outcomeReasonText=Other+credit+limit+exceeded

The grace period of the subscription is one day.

If billing continued to fail throughout the grace period, you would receive a subscription status notification like the following:

http://merchant.example.com/mxpay?subscriptionId=9654572&updateId=68631277&state=suspended&subscriptionState=suspended&requirefulfilmentUrl=no&date=2008-06-17+16%3A11%3A45+%2B0100&msisdn=447700900999&uniqueUserIdentifier=Lrmi9u%2BI9HOzYX27VzQoHzzscqsdZdxcfLk5pe8HoUA%3D&network=TMOBILEUK&useragent=SonyEricssonD750i%2FR1AA+Browser&channel=wap

The suspension timeout period of the subscription is one week.

If billing continued to fail until the suspension timeout elapsed, the subscription would be unsubscribed. You would receive another subscription status notification:

http://merchant.example.com/mxpay?subscriptionId=9654572&updateId=51531267&state=unsubscribed&subscriptionState=unsubscribed&requirefulfilmentUrl=no…

You would also receive a notification that the charge had failed permanently:

http://merchant.example.com/mxpay?transactionId=32561714&updateId=19301445&state=confirmfailed&transactionState=failed&requirefulfilmentUrl=no&date=2008-06-16+16%3A10%3A48+%2B0100&subscriptionId=9654572&outcomeReasonId=65794&outcomeReasonText=Other+credit+limit+exceeded

Unsubscribing

Suppose your application needs to unsubscribe a subscription (for example, due to a support call).

Here is the unsubscribe request you would send to unsubscribe the ringtones example above:

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

If the unsubscribe request was successful, you would receive an HTTP response like this:

outcome:success
outcomeReasonId:1000
outcomeReasonText:Request was successful.
subscriptionId:48417867
requestId:cta-rid-80645525

Here is the notification you would receive:

http://merchant.example.com/mxpay?subscriptionId=9654572&updateId=32015470&state=unsubscribed&subscriptionState=unsubscribed&reasonid=5005&reasontext=Subscription+unsubscribe+request+successful&requirefulfilmentUrl=no&subscriptionState=unsubscribed&outcomeReasonId=285278464&outcomeReasonText=Subscription+unsubscribed%3A+Subscription+unsubscribe+request+successful&requirefulfilmentUrl=no&date=2008-06-16+15%3A48%3A12+%2B0100&msisdn=447700900999&uniqueUserIdentifier=Lrmi9u%2BI9HOzYX27VzQoHzzscqsdZdxcfLk5pe8HoUA%3D&network=TMOBILEUK&useragent=SonyEricssonD750i%2FR1AA+Browser&channel=wap&requestId=cta-rid-80645525

API reference

For full details of request and notification parameters, see the Subscription API.