Crediting API

Overview

This page provides details of how to use the MX Telecom Charge To Account Gateway to make one-off credits to a given end user, such as for a promotion or refund. It is designed to be used alongside the Crediting Developer Guide.

Making requests using HTTP
Credit request parameters
Format of response from server
Receiving notifications
Notification parameters
Pre-paid credit balance enquiry
Test accounts

Making requests using HTTP

The Charge to Account Gateway exposes an HTTPS interface for making requests to credit an end user. The endpoint for these HTTP requests is:

https://cta.mxtelecom.com/api/credit

This URL accepts both GET and POST requests.

The parameters you use to specify the details of a credit request are explained in the Credit request parameters section below. You can check your pre-paid credit balance using the method detailed in the Pre-paid credit balance enquiry section.

Parameters should be URL and UTF-8 encoded.

Credit request parameters

This table details the parameters you can use when making a one-off credit:

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
msisdn	Yes	The mobile number of the end user being credited	international format with no leading + e.g. 447700900750
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 credit 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 credited in thousandths of the specified currency e.g. if currency=GBP, 5000 = Ł5 You must ensure that your account supports each credit value you send; some values may need to be provisioned for some networks	positive integer, range subject to account policy restrictions ; max credit is 10000 (Ł10)
smsContent	No	Some networks mandate that a confirmation SMS is sent on behalf of MX Telecom. smsContent contains the content of the SMS message.	string, max 160 characters
note	No	A descriptive note that will be stored in the credit record	string, max 160 characters
subaccount	No	The subaccount that will be stored in the credit record	string, max 10 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.

These are the name/value pairs the gateway can return in response to a credit request:

Name	Returned if?	Meaning	Values allowed
outcome	Always	Result of the request	rejected, success or failed
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
creditId	Valid request	Unique ID of the credit	64-bit unsigned integer e.g. 69134309
redirectUrl	Not currently implemented	URL which the end user must visit to confirm the credit	e.g. http://mxpay.net/3/6PXQnZIHTh...

An example plain text response:

outcome:failed
outcomeReasonId:3000
outcomeReasonText:Missing username.

An example XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <outcome>failed</outcome>
  <outcomeReasonId>3000</outcomeReasonId>
  <outcomeReasonText>Missing username.</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 credit failed.

Receiving notifications

Whenever the status of an attempted credit changes, the MX Telecom Charge to Account Gateway notifies your server via an HTTP request.

Each credit attempted is identified by the gateway with a unique creditId. The creditId is returned in all notifications about the credit.

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.

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 might make to your server:

http://merchant.example.com/mxpay?creditId=92647076&updateId=92647076&creditState=confirmed&requirefulfilmentUrl=no&date=2008-04-29+11%3A46%3A12+%2B0100&date=2008-04-29+11%3A46%3A12+%2B0100&network=TMOBILEUK&msisdn=447700900999&uniqueUserIdentifier=Lrmi9u%2BI9H...&billingType=prepay

This table describes the parameters the gateway uses when sending credit notifications:

Parameter	Always present?	Meaning	Values allowed
msisdn	Yes	The mobile number of the end user credited	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
creditId	Yes	The creditId of the credit that has been updated.	64-bit unsigned integer e.g. 69134309
updateId	Yes	A unique ID identifying the specific update to the given credit. This can be used to filter duplicate updates if received.	64-bit unsigned integer e.g. 69134309
creditState	Yes	The current state of the credit.	See table of credit states 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 credit. The URL should be a suitable page for the end user to continue browsing. Currently fulfilment URLs are never required, and this parameter will always be set to "no".	no - a fulfilment URL is not required yes - a fulfilment URL is 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
network	Yes	Denotes the network through which the credit was applied.	See table of network codes.
mvno	No	Denotes the MVNO through which the credit was applied e.g. For Virgin UK network=TMOBILEUK and mvno=virgin	See table of network codes.
billingType	No	Denotes whether the account is pre-pay or post-pay.	prepay or postpay in lower case.

creditState parameter

The meaning of the creditState parameter relating to credits is as follows:

creditState	Meaning
submitted	The credit request has been submitted to the network but is yet to be applied. Ordinarily a confirmed request will follow.
confirmed	The credit has been confirmed, and has been applied to the end user's account.
retrying	The credit has failed and is being retried.
failed	The credit request has failed. The outcomeReasonId should be used to determine the reason for the failure. See table for details.

Pre-paid credit balance enquiry

In order to credit end users, you must hold sufficient pre-paid funds in an account with MX Telecom. The balance is reduced by the relevant amount whenever a credit is applied. This section explains how to check your current balance.

The balance is reported from log files which are updated frequently, but may lag slightly behind real time. The balance can go up as well as down. This is because MX Telecom deducts the value of the credit at the beginning of a transaction. If the credit to the user fails, the balance is increased by the same amount.

This is an example of a credit balance request that you might issue to the gateway:

https://cta.mxtelecom.com/remainingCredit?user=myuserid&pass=mypassword

This table details the parameters you use when querying the balance of credit left on an account:

Parameter	Required?	Meaning	Values allowed
user	Yes	Username for access to the gateway	username for your CTA Gateway account
pass	Yes	Password for access to the gateway	password for your CTA Gateway account

Receiving credit balance

The server returns a response in the format:

currency,amount

In this response, currency is the three letter ISO 4217 currency code and amount is the current balance held, in thousandths of the specified currency. In the following example, the balance is Ł10,000, 19 pence and 0.6 of a penny:

GBP,10000196

If an error occurs, the gateway will return the appropriate 4xx or 5xx HTTP response code with a single line of text describing the error.

Test Accounts

In order to integrate with the Crediting API, MX Telecom can configure a test account that does not interact with the mobile networks and as such can be used without incurring crediting charges.

See Test accounts in the Crediting Developer Guide for more information.