SMS Gateway
Charge To Account Gateway
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.
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 hosting and delivery of any content associated with a subscription.
In this guide, the term "end user" refers to the cell 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.
Contents
- Integration requirements
- Overview
- Automatic suspension and unsubscription
- Subscription management
- Subscription setup 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 an HTTPS 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.
Wireless carriers 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.
Overview
The Charge To Account Gateway supports subscriptions that charge end users at pre-determined regular intervals. Example applications include:
- 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 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.
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.
Some carriers do not allow a free period, and there may also be limitations on the allowed value of period—see Carrier Differences for details).
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
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.
Subscription management
A number of API methods are provided to allow your application to manage a 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, 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 subscription, the transitions between them and the context of the management API calls (in red):
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 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.
Subscription setup workflow
This example gives an overview of how a merchant site integrated with the Charge To Account Gateway would set up a subscription service.
- 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 an HTTPS GET or POST 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 cell 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 explains the subscription and the cost involved. The user follows the "Subscribe" link to confirm the subscription.
On AT&T, the gateway redirects the user to the carrier's own payment system to confirm the subscription. For details, see the Carrier Features table.
-
At this point the Charge To Account Gateway attempts to set up the subscription.
If there is an initial free period, the subscription begins straight away.
For a 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.
-
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.
The notification may return details about the end user such as their MSISDN and network. See Carrier Features for details.
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 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 a 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 preference 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
Subscription failure workflow
This section shows the workflow if the subscription attempt fails.
For a 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 subscription with a free period, 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).
-
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… Note that for technical reasons, it is not possible to return detailed failure reasons on certain carriers (currently, AT&T). See the Carrier Differences table.
-
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 an end user sends a STOP message by SMS (equivalent to an unsubscribe request), then the Charge To Account Gateway applies 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.)
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 subscription
This is an example request for a subscription. Not all of the options used in this request will be available for all carriers.
https://cta.mxtelecom.com/api?
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 message.
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—see Marketing opt-ins
Once the user has confirmed the subscription, the gateway sends the following SMS confirmation message to the end user:
FreeMsg: U have joined Ringtones for 4 days no charge, then $2.50 per week until you send STOP to 222111. Helpline 555-2368
The STOP Short Code and helpline number are configured when your account is set up (see Branding).
If the 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?
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?
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?
Charge notifications
When a charge is successfully made, the Charge To Account Gateway will send your application two notifications. One is a transaction notification, which informs you that the charge has succeeded, while the other is a subscription state notification, which informs you that the subscription state has changed.
If a subscription with no free period is requested, the first 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?
Assuming the charge succeeds, the gateway sends a transaction notification:
http://merchant.example.com/mxpay?
and a subscription state notification:
http://merchant.example.com/mxpay?
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.
When the next charge occurs for the subscription, then the gateway sends a similar pair of notifications when a charge succeeds:
http://merchant.example.com/mxpay?
http://merchant.example.com/mxpay?
Note that in the transaction notification the channel for the charge is now direct, rather than wap. This is set to direct when the subscription charge does not involve direct end user input: this is any charge except the first charge of a subscription without an initial free period.
The subscription status notification will continue to show the channel that the end user subscribed through; in this example, wap.
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 subscription created above:
http://merchant.example.com/mxpay?
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?
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?
You would also receive a notification that the charge had failed permanently:
http://merchant.example.com/mxpay?
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?
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?
API reference
For full details of request and notification parameters, see the Subscription API.
