SMS Gateway
Charge To Account Gateway
One-off Charges API
Overview
This page provides details of how to use the MX Telecom Charge To Account Gateway to make one-off charges against a given user (such as for the purchase of a single item).
If you need to set up an ongoing subscription, see the Subscriptions documentation.
There is also a Developer Guide describing how this API can be used.
Contents
- Making requests using HTTP
- Charge request parameters
- Format of response from server
- Receiving notifications
- Notification parameters
Making requests using HTTP
The Charge To Account Gateway exposes an HTTPS interface for making requests to charge a user. The endpoint for these HTTP requests is:
https://cta.mxtelecom.com/api
This URL accepts both GET and POST requests.
The parameters you use to specify the details of a charge request are explained in the Charge request parameters section below.
Parameters should be URL encoded and UTF-8 encoded.
Charge request parameters
This table details the parameters you can use when making a one-off charge:
| 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 | charge (to make a charge request) |
| 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 the charge being requested
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 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. Wallpapers |
| 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. Nature |
| 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. Trees |
| 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. Giant+Sequoia |
| productDescription | Yes | Brief description of the product | string, max 200 characters |
| isAdult | Yes | The adult nature of the product. Possible values are: See Age Verification for details |
|
| note | No | A descriptive note that will be stored in the charge record | string, max 160 characters |
| subaccount | No | The subaccount that will be stored in the charge record | string, max 10 characters |
| 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: This parameter is ignored for Web Payforit transactions as the confirmation page cannot be skipped for these transactions. |
none, confirmation (default) |
| singleclick | No | Specifies whether this is a Payforit Single Click transaction. |
yes, no (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 |
| 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) |
Format of response from server
The Charge To Account Gateway responds to all requests using an 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 pairs in either plain text (name:value) or XML (<name>value</name>) format depending on the responseFormat specified.
For a charge to succeed, the user must visit the 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 name/value pairs the gateway can return in response to a one-off charge 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 details. |
| outcomeReasonText | Always | Natural language description of the outcome. | string |
| transactionId | Valid request, not Single Click | Unique ID of the charge transaction | 64-bit unsigned integer e.g. 69134309 |
| redirectUrl | Valid request, user confirmation needed | URL which the user must visit to confirm the charge | e.g. http://mxpay.net/3/6PXQnZIHTh... |
| singleclickId | Valid Single Click request | Unique ID for the Single Click request | 64-bit unsigned integer |
| imageUrl | Valid Single Click request | URL of the Single Click button image | e.g. http://mxpay.net/3/EC17BVC9we... |
An example plain text response:
outcome:failed outcomeReasonId:3002 outcomeReasonText:Missing action.
An example XML response:
<?xml version="1.0" encoding="UTF-8"?> <response> <outcome>failed</outcome> <outcomeReasonId>3002</outcomeReasonId> <outcomeReasonText>Missing action.</outcomeReasonText> </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. The outcome will be provided via the Notification API (see below). |
| failed | 200 | Yes | The request was accepted but the transaction failed. |
| userinputrequired | 200 | Yes | The request was accepted but additional user information and/or confirmation is required. |
Receiving notifications
Whenever the status of an attempted charge changes, the MX Telecom Charge To Account Gateway notifies you via an HTTP request to a server you control. Notifications are also used to send the user's marketing opt-in preferences.
Each one-off charge attempted is identified by the gateway with a unique transactionId. The transactionId is returned in all notifications about the charge.
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&purchased=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 gateway would make to your server:
http://merchant.example.com/mxpay?
This table describes the parameters the gateway uses when sending one-off charge notifications:
| Parameter | Always present? | Meaning | Values allowed |
| transactionId | Yes | The transactionId of the transaction that has been updated. | 64-bit unsigned integer e.g. 69134309 |
| singleclickId | No | The singleclickId of the transaction that has been updated. | 64-bit unsigned integer |
| updateId | Yes | A unique ID identifying the specific update to the given transaction. This can be used to filter duplicate updates if received. | |
| transactionState | Yes | The current state of the transaction. | 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. The URL should be a suitable page for the user to continue browsing. The content of the page indicated should take into account the state of the charge attempt. If the charge succeeded (transactionState is confirmed) the fulfilment URL may provide the user with direct access to the product. |
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 [timezone] e.g. 2008-04-29 14:31:02 +0100 |
| channel | Yes | Denotes the way in which the end user accessed your site. See WAP vs. web initiated purchases for more information. | wap , web, weblite |
transactionState parameter
The meaning of the transactionState parameter relating to one-off charges is as follows:
| transactionState | Meaning |
|---|---|
| authorised | The transaction has been authorised successfully but has not yet been confirmed (not applicable to Payforit charges; reserved for future payment systems) |
| confirmed | The charge or refund has been confirmed |
| retrying | The charge or refund has failed and is being retried |
| cancelled | The subscription has been cancelled |
| failed | The charge request has failed (the outcomeReasonId should be used to determine the reason for the failure; see table for details) |
| settled | The transaction has been settled (where applicable) |
| refunded | The charge has been refunded |
Charge confirmation
When a charge is confirmed, some additional information will also be provided in the notification:
| Parameter | Always present? | Meaning | Values allowed |
| msisdn | Yes | The mobile number of the user charged | 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 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 |
Post-confirmation notification
After a charge is confirmed, an HTTP GET request will be made to your notification URL to provide further information in the following cases:
- if marketing opt-ins were collected
- if a user's Single Click opt-in status needs to be updated
The parameters for this post-confirmation notification are as follows:
| Parameter | Always present? | Meaning | Values allowed |
| transactionId | Yes | The unique ID of the transaction as returned in the original response | |
| singleclickId | If Single Click | The unique ID of the Single Click request related to this transaction | |
| singleclickOptIn | If user was presented with a Single Click opt-in | Whether or not the user opted in to Single Click | yes, no |
| marketingOptIn | If user was presented with marketing opt-in | Whether or not the user opted in to receive free marketing updates from the content provider who originates the charge | yes, no |
