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 cell user accounts on different carriers using a single API.

In this guide, the term "end user" refers to the cell 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.

Integration requirements
Charge workflow
- Successful charge workflow
- Charge failure workflow
Example request
Example notifications
Refund requests
API reference

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.

Wireless carriers 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.

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

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

The merchant does not need to know the end user's cell 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…
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
		
```
The request for "user input" simply means that the end user must visit a payment verification URL hosted by the gateway so that their cell number (MSISDN) can be confirmed.

The transactionId is used to refer to this particular charge request throughout the rest of its lifecycle.
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.
The end user arrives at the payment verification URL and confirms the payment.

On AT&T, the gateway redirects the user to the carrier's own payment system for them to confirm the payment. For details of carrier differences, see the Carrier Features table.
At this point the Charge To Account Gateway passes the charge request to the end user's wireless carrier.

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

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.

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 completing the transaction. 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.
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.
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.
The end user selects their marketing preference and clicks 'Continue'.
The Charge To Account Gateway redirects the user to the fulfilment URL provided by the merchant.
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

For a successful charge request, the user's MSISDN and a unique user identifier will be returned. Depending on the carrier, this may be in the initial success notification or the marketing details notification. See the Carrier Features table for details.

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

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

For technical reasons, it is not possible to return detailed failure reasons on certain carriers (currently, AT&T). See the Carrier Features table.
The merchant responds with a fulfilment URL as before.

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.
The Charge To Account Gateway redirects the end user to an error page explaining that the transaction has failed.
The end user clicks 'Continue'.
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=USD&amount=500&productGroup=Wallpapers&productCat=Nature&productSubCat=Wild&productName=Tiger+Wallpaper+4&productDescription=Crouching+Siberian+Tiger+Wallpaper+004

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 USD0.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)
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

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

Depending on the parameters of the original request, marketing opt in 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=12125551234&uniqueUserIdentifier=Lrmi9u%2BI9H...&network=ATTUS&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.

However, you may be notified of refunds initiated by some carriers.

See the One-off Charges API for details of the refund notification.

API reference

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