Europe USA/Canada
 Home
 SMS Gateway
 Mobile Crediting
 Payforit
 Mobile Applications
 Video Gateway
 MMS Gateway
 Interactive TV Platform
 Location Gateway
 Voice Services
 Network Lookup
 The Regulatory Guide
 Technical Information
  > SMS Gateway
  > Content Management System
  · Video Gateway
  > MMS Gateway
  > Location Gateway
  v Charge To Account Gateway
    v One-off Charges
      · Developer Guide
      · API Reference
    · Single Click
    > Subscriptions
    > Web Payforit
    > Crediting
    · Status Codes
    · Branding
    · Marketing Opt-ins
    · Age Verification
    · Anonymous User ID
  > Network Lookup
  > Network Codes
  · System Status
  · Knowledge Base
 Partner Login
 Careers
 Press Releases
 About Us
 Contact Us

One-off Charges Developer Guide

Overview

This guide is intended for developers who wish to integrate the Charge To Account Gateway with an existing application to make one-off charges.

The gateway allows you to make charges directly to mobile user accounts in line with the guidelines of the Payforit scheme. If you are not familiar with Payforit, please refer to our introduction to the scheme.

In this guide, the term "end user" refers to the mobile phone user who is purchasing an item using their handset. The term "merchant site" refers to an application, such as a WAP shopping site, which relies on the Charge To Account Gateway to charge users.

Contents

Integration requirements

Integrating an application (such as a WAP shopping site) with the Charge To Account Gateway involves using a simple HTTP interface.

The application tells the gateway to initiate a transaction using an HTTPS GET or POST request.

The 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.

NOTE:

Mobile networks 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.

WAP vs. web initiated purchases

The Payforit scheme allows both WAP and web initiated purchases. Depending on how an end user is accessing your site, the Charge To Account Gateway delivers different display and workflow options:

  • WAP
    This is designed for end users who are browsing your site using a WAP browser on a mobile phone. The Charge To Account Gateway uses this option when it can retrieve the phone's MSISDN. However, if you specify channel=web the Gateway will instead use the Web Payforit workflow.

  • Web
    This is designed for end users browsing your website using a computer rather than a mobile phone. As this sort of browsing does not identify an end user's mobile phone number, the Charge To Account Gateway needs to use a different workflow from WAP browsing. This also displays each page as a webpage, rather than a WAP page.

    The Charge to Account Gateway will only use this option if you specify channel=web in the initial request to the Gateway. See Web Payforit for more information.

  • Web Lite
    Web Lite is designed for end users browsing your site using a smartphone (such as an iPhone) via a Wi-Fi connection. The Charge To Account Gateway will use this option when it cannot automatically gather the MSISDN of the end user's phone and you have not requested the web option (channel=web). This option uses the same workflow as Web Payforit; however, the pages have the look and feel of the WAP Payforit pages and are optimised for small screens.

    Note that, unlike the web option, you cannot specify Web Lite. See Web Payforit for more information.

This page describes the WAP Payforit workflow, and most pages in this Technical Information section also use WAP Payforit workflow and screenshot examples. For information on the web and Web Lite workflow see Web Payforit.

Charge workflow

This example gives an overview of the process of making a charge using a merchant site integrated with the Charge To Account Gateway.

Charging with Payforit and the Charge To Account Gateway
  1. The end user, browsing the merchant's WAP/XHTML site, chooses an item to buy. The user experience up until the point of purchase is handled through the merchant's existing mobile store.

  2. When the end user selects the item, 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 purchase (including the cost and item description) are sent as parameters to the request. The merchant's identity is verified with a username and password, also passed as parameters.

    NOTE:

    The merchant does not need to know the end user's mobile number to initiate a charge.

    This truncated example shows the basic structure of a charge request:

    https://cta.mxtelecom.com/api?username=yourname&password=yourpass&action=charge&transactionMode=AutoConfirm…

  3. The Charge To Account Gateway responds with a payment verification URL hosted by MX Telecom.

    The URL is returned (along with a unique transactionId 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...
		transactionId:84282631
    NOTE:

    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 transactionId is used to refer to this particular charge request throughout the rest of its lifecycle.

  4. The merchant site must now direct the end user's mobile browser to the payment verification URL supplied by the gateway.

    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.

  5. The end user arrives at the payment verification URL. The page provides a clear explanation of what they are buying and the cost involved, in line with the Payforit rules. The user follows the "Pay Now" link on the payment verification page to confirm the purchase.

    Payforit payment confirmation screen

    Note that if the purpose of the site is to collect donations, rather than to sell mobile content, then the 'Pay Now' button will instead be a 'Donate' button.

  6. At this point the Charge To Account Gateway passes the charge request to the end user's mobile network.

Successful charge workflow

To continue the example, we assume that the end user has been successfully charged.

Where a charge cannot be levied (e.g. insufficient credit on a pre-pay account) the workflow is different. See Charge failure workflow below for details.

Payment confirmation and fulfilment with Payforit and the Charge To Account Gateway

  1. The Charge To Account Gateway notifies the merchant site of the successful charge using a GET request to the notification URL provided by the merchant site.

    The notification from the gateway would be structured like this:

    http://merchant.example.com/mxpay?transactionId=84282631&updateId=123&transactionState=confirmed&requirefulfilmentUrl=yes…

    For details of charge requests, see the One-off Charges API.

    The transactionId value is the same as that previously returned along with the payment verification URL. This allows the merchant application to link related notifications.

    In this case, because the charge was successful, the notification includes the end user's MSISDN and network. If the charge had failed, these details would not have been returned (this is a requirement of the Payforit rules).

    The notification also contains a request for a fulfilment URL. The fulfilment URL should be a suitable location for the end user to continue their browsing session after leaving the gateway-hosted Payforit pages. Because the purchase was successful, the URL could point directly to downloadable content. Alternatively, it could be an acknowledgement screen and the merchant could deliver content using a method such as WAP push.

  2. 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/view/productId/foo/productVersion/bar...

    The format of the fulfilment URL is determined by your application.

  3. The Charge To Account Gateway redirects the end user to a page acknowledging the successful payment and offering the chance to opt in to marketing messages.

    Payforit marketing opt-in page

  4. The end user selects their marketing preference and clicks 'Continue'.

  5. The Charge To Account Gateway redirects the user to the fulfilment URL provided by the merchant.

  6. Finally, the Charge To Account Gateway sends details of the end user's marketing opt-in choice using the Notification API.

    http://merchant.example.com/mxpay?transactionId=127384&marketingOptIn=yes

Charge failure workflow

This section shows the workflow if the attempt to charge the user fails.

This may happen for a number of reasons. For instance, a pre-pay account user may not have enough credit; it may not be possible to detect the user's MSISDN due to the use of certain mobile browsers or a Wi-Fi connection; or the account may be barred from receiving charges.

Payforit one-off charge failure workflow

  1. The Charge To Account Gateway notifies the merchant site of the charge failure using a GET request to the notification URL provided by the merchant site.

    This is a simplified example of a one-off charge failure notification:

    http://merchant.example.com/mxpay?transactionId=36934800&updateId=31380787&transactionState=failed&requirefulfilmentUrl=yes&outcomeReasonId=65536&outcomeReasonText=Insufficient+credit+in+account…

    The transactionState parameter shows that the charge attempt failed.

  2. The outcomeReasonText and outcomeReasonId parameters can be interpreted to understand the reason for the failure. The outcomeReasonId is a four digit code—for a guide to interpreting it, see the Transaction Failures table on the Status Codes page.

  3. The merchant responds with a fulfilment URL as before.

    NOTE:

    Note that the gateway still requests a fulfilment URL even though the charge 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.

  4. The Charge To Account Gateway redirects the end user to an error page explaining that the transaction has failed.

  5. The end user clicks 'Continue'.

  6. The Charge To Account Gateway redirects the user to the fulfilment URL provided by the merchant.

Example request

This is a simple example request for a one-off charge.

https://cta.mxtelecom.com/api?username=yourname&password=yourpass&action=charge&transactionMode=AutoConfirm&currency=GBP&amount=500&productGroup=Wallpapers&productCat=Nature&productSubCat=Wild&productName=Tiger+Wallpaper+4&productDescription=Crouching+Siberian+Tiger+Wallpaper+004&isAdult=nonadult

This example only includes mandatory parameters, so the gateway assumes default values for the optional parameters.

The payment confirmation page for this one-off charge would look like this:

Click 'Pay now' to get Tiger Wallpaper 4 from Merchant for GBP0.50. / Pay Now / Cancel / Terms and Conditions / Operator Data Charges may apply
  • Tiger Wallpaper 4 is the productName value defined in the original request
  • £0.50 is the charge amount defined by the currency and amount values
  • Merchant is the merchant shop/site name (see Branding)
  • What is Payforit links to a description of Payforit, as specified in the scheme rules
  • Terms and Conditions links to merchant details supplied by you (see Branding)
  • Operator Data Charges may apply links to a standard terms and conditions message specified by the Payforit scheme rules

Once the user has selected Pay Now and the charge has been completed successfully, the post-confirmation page will be presented.

Thank you for your payment of GBP0.50 to Merchant. To access your purchase, Tiger Wallpaper 4, please click continue below. / Continue / Marketing opt-in
  • Depending on the parameters of the original request, marketing opt in and the post-confirmation page can be skipped—see Marketing opt-ins
  • The Shop Helpline number is supplied by you (see Branding)

Example notifications

If the end user was successfully charged for the Tiger Wallpaper purchase example above, the notification sent from the gateway to the merchant site would look like this (some values truncated for legibility):

http://merchant.example.com/mxpay?transactionId=78858761&updateId=92647076&state=confirmed&transactionState=confirmed&requirefulfilmentUrl=yes&date=2008-04-29+11%3A46%3A12+%2B0100&msisdn=447700900999&uniqueUserIdentifier=Lrmi9u%2BI9H...&network=TMOBILEUK&useragent=SonyEricssonD750i%2FR1AA+Browser...&channel=wap

Note that the transactionId value in the notification will match the value returned in the original HTTP response. All notifications about a particular charge will be identified with the same transactionId value.

The transactionState value of confirmed means that the charge was successful.

If the charge is not successfully completed, a notification will be sent giving the reason.

In this example, the charge was not made because the end user pressed 'Cancel' at the payment confirmation screen:

http://merchant.example.com/mxpay?transactionId=78858761&updateId=20684143&state=cancelled&transactionState=cancelled&requirefulfilmentUrl=yes&date=2008-04-29+13%3A55%3A05+%2B0100

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?transactionId=39023321&updateId=47730352&state=confirmfailed&transactionState=failed&requirefulfilmentUrl=no&date=2008-05-02+13%3A10%3A47+%2B0100&outcomeReasonId=327680&outcomeReasonText=Userinput+timed+out

For details, see the Notifications section of the One-off Charges API.

Refund requests

Initiating refund requests from an application integrated with the Charge To Account Gateway is not currently supported.

API reference

See the One-off Charges API for full details of request and notification parameters.

© 2000-2010 MX Telecom Ltd