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 a secure HTTP 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
currency	Yes	A code denoting the currency of the charge being requested 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 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 carriers	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. 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 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. Giant+Sequoia
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
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 if a checkbox is displayed for the user to opt in to future marketing messages on the post-confirmation page	yes (default), 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	confirmation (default)
singleclick	No	Specifies whether this is a Payforit Single Click transaction.	yes, no (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

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 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 and address details.

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

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?transactionId=78858761&marketingOptIn=no&msisdn=12125551234&uniqueUserIdentifier=rtU6zCoOAcH9NOqSN7N0IyUsU9noNZwoVEfyYzEDauY%3D

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
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.
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 channel through which the charge was originated. Currently only the WAP channel is supported.	wap

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 (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	Depends on carrier*	The mobile number of the user charged	international format with no leading + e.g. 12125551234
uniqueUserIdentifier	Depends on carrier*	A unique identifier based on msisdn	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

* Depending on the carrier, these parameters may be provided in the charge confirmation or the post-confirmation notification (see below); for details, see Carrier Features.

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.

Post-confirmation notification

If the collection of a user marketing opt-in is requested, then, after a charge is confirmed, an HTTP GET request will be made to your notification URL with the following parameters:

Parameter	Always present?	Meaning	Values allowed
transactionId	Yes	The unique ID of the transaction as returned in the original response
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
msisdn	Depends on carrier*	The mobile number of the user charged	international format with no leading + e.g. &example-msisdn;
uniqueUserIdentifier	Depends on carrier*	A unique identifier based on msisdn	URL-encoded, maximum 47 characters long

* Depending on the carrier, these parameters may be provided in the charge confirmation or the post-confirmation notification; for details, see Carrier Features.