SMS Gateway
Charge To Account Gateway
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 timed subscription
- Setting up an ad hoc subscription
- Making an ad hoc charge
- Concluding any kind of subscription
- Restoring any kind of subscription
- Unsubscribing any kind of subscription
- Format of response from server
- Receiving notifications
- Notification API
Making requests using HTTP
The Charge to Account Gateway exposes a secure HTTP 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 timed subscription and Setting up an ad hoc subscription below.
Parameters should be URL encoded and UTF-8 encoded.
Setting up a timed subscription
This table details the parameters you can use when setting up a timed 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 |
| currency | Yes | A code denoting the currency of subscription charges e.g. USD for US Dollars | 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=USD, 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 |
| 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 payment confirmation page. This should 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. In the US, the only permissible value is nonadult |
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 Not supported by all carriers. |
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 if a checkbox is displayed for the user to opt in to future marketing messages on the post-confirmation page | yes, no |
| postConfirmationPage | No | Determines the page displayed to the user after a successful transaction. In the US the only value allowed is:confirmation - Show a confirmation page which asks for the marketing opt-ins specified with the optIn parameter |
none, delivery, confirmation (default) |
| serviceDeliveryMessage | No | Custom service delivery message displayed on the post-confirmation page.
Default: "To access your purchase, productName,
please click continue below." |
string, max 40 characters |
Setting up an ad hoc subscription
This table details the parameters you can use when setting up an ad hoc 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 |
| currency | Yes | A code denoting the currency of ad hoc charges e.g. USD for US Dollars | three letter ISO 4217 currency code; currencies subject to account policy restrictions |
| amount | Yes | The amount to be charged each time in thousandths of the
specified currency e.g. if currency=USD, 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 |
| 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. Alerts |
| 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. Travel |
| 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. Traffic |
| productName | Yes | Product name; this will be displayed to users on the Payforit WAP pages | string, max 35 characters; e.g. North+London |
| productDescription | Yes | Brief description of the product | string, max 200 characters |
| isAdult | Yes | The adult nature of the product. In the US, the only permissible value is nonadult |
adult, nonadult, either |
| note | No | A descriptive note that will be stored in the charge record (max 160 chars) | string, max 160 characters |
| subaccount | No | The subaccount that will be stored in the charge record (max 10 chars) | string, max 10 characters |
| arbitrarySubscriptionPeriodUnits | Yes | The description of the item for which ad hoc charges will be generated. See the Developer Guide for how this is presented to the end user. | string, max 35 characters; e.g. Daily+Horoscope |
| subscriptionDuration | No | Time before the subscription automatically terminates, expressed in subscriptionDurationUnits If no value is specified, the subscription is perpetual unless it is suspended for billing failure or inactivity |
integer (default is 0/perpetual) |
| subscriptionDurationUnits | Yes, if above is specified | Hours, Days, Weeks, Months | |
| permittedBillingFailures | No | The gateway will automatically terminate the subscription if the given number of consecutive failed attempts to charge the end user is exceeded. For example, if permittedBillingFailures is 5, the sixth consecutive billing failure causes the subscription to end. |
integer (default is 5) |
| permittedBillingFailurePeriod | No | The gateway will automatically terminate the subscription if charge attempts fail continuously for the specified period. | |
| permittedBillingFailurePeriodUnits | Yes, if above is specified | Hours, Days, Weeks, Months | |
| permittedInactivityPeriod | No | The gateway will automatically terminate the subscription if no ad hoc charge attempts are made within the specified period. A charge attempt does not have to succeed to count for the purposes of preventing unsubscription due to inactivity. Default period is six months. |
integer |
| permittedInactivityPeriodUnits | 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, no |
| postConfirmationPage | No | Determines the page displayed to the user after a successful transaction. In the US the only value allowed is:confirmation - Show a confirmation page which asks for the marketing opt-ins specified with the optIn parameter |
none, delivery, confirmation (default) |
| serviceDeliveryMessage | No | Custom service delivery message displayed on the
post-confirmation page. Default: "To access your purchase, productName, please click continue below." Where no opt-ins are requested, defaults to: "Redirecting you to your purchase now" |
string, max 40 characters |
Making an ad hoc charge
Once an ad hoc subscription has been set up, your application is responsible for initiating charges to the end user as appropriate.
The value per charge and the associated product details are specified when the ad hoc subscription is set up. For a given ad hoc subscription, the value of each charge is always the same.
| Parameter | Required? | Meaning | Values allowed |
| action | Yes | The action to take. | For an ad hoc charge request this should be charge |
| subscriptionId | Yes | The unique ID of the ad hoc subscription. | |
| validity | No | The gateway will retry the subscription charge for this number of minutes. |
0.5 to 4320 (30 seconds to three days) Default is 1440 (one day) |
An example ad hoc charge request is:
https://cta.mxtelecom.com/api?
Concluding any kind of subscription
If you conclude a timed subscription, it will continue until the end of the current billing period, then terminate.
If you conclude an ad hoc subscription, it will continue until any outstanding charges have been processed, 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?
Restoring any kind of subscription
If you restore a timed subscription which is concluding, it will not terminate at the end of the current billing period.
If you restore a concluding ad hoc subscription with outstanding charges, it will not terminate once the charges are processed.
Note that an ad hoc subscription which is concluding due to the end user sending a STOP message cannot be restored.
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?
Unsubscribing any kind of subscription
If you unsubscribe a subscription, it terminates immediately.
The gateway will not process any queued-up ad hoc charges or 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?
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.
|
| requestId | Request is to unsubscribe, conclude, restore or make an ad hoc charge | Unique ID of this particular request | 64-bit unsigned integer prefixed with cta-rid- |
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 and address details.
Each subscription you request is identified by the gateway with a unique subscriptionId. The subscriptionId is returned in all notifications about the subscription.
For an ad hoc subscription, each charge made is also identified with its own transactionId.
When you make an ad hoc charge request, you will receive two notifications: one about the ad hoc charge transaction, and a second about the subscription status.
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
The fulfilment URL you return must include the protocol at the beginning (e.g. http://merchant.example.com, not just merchant.example.com). Otherwise, the redirection of the user will fail.
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?
This table describes the parameters the gateway uses when sending subscription 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, restore or ad hoc charge 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. 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
|
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 | No | Denotes the channel through which the subscription was originated; currently only the trusted WAP pages are supported. | wap |
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. 12125551234 |
| 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. |
|
| collectingDeliveryAddress | Only if collection of delivery details is requested | Whether or not delivery address information is being requested. | yes - delivery information is being collected no - delivery information is unable to be collected |
Post-confirmation notifications
If the collection of marketing opt-ins and/or delivery information is requested, the gateway sends them in a separate notification 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 | Only if you specified a marketing opt-in in the initial request* | 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 (ad hoc or timed) 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. | |
| requestId | Only for ad hoc | A unique ID identifying the charge request which triggered this notification. 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 |
| 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. 12125551234 |
| 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 |
| channel | Yes | Denotes the channel through which the charge was originated. Possible values: |
wap, direct |
Refund notification
When some carriers refund a charge to the end user, you may receive a notification in the following format:
| Parameter | Always present? | Meaning | Values allowed |
| transactionId | Yes | The previously-assigned transactionId of the refunded charge. | 64-bit unsigned integer e.g. 69134309 |
| transactionState | Yes | The state of the transaction | refunded |
| msisdn | Yes | The mobile number of the refunded user | international format with no leading + e.g. 12125551234 |
| uniqueUserIdentifier | Yes | The previously-assigned unique identifier based on msisdn | URL-encoded, maximum 47 characters long |
This notification is to inform you of a refund initiated by the carrier, perhaps in response to an end user support call. It is not possible for your application to initiate refunds.
Some operators refund the previous periodic charge when a subscription is unsubscribed. See Carrier Differences for details.
