Refund Notifications

Overview

OpenMarket now offers a RESTful and feature-rich Global SMS API. Compared to the existing MX Telecom APIs, the Global SMS API provides:

  • Automated originator selection, which selects the correct short code or VMN for any country or territory
  • Our highest level SLA and increased messaging capacity
  • Better security through Basic authentication
  • A test environment for new and migrating customers

as well as a host of other benefits. While we will continue to support our existing SMS APIs, we believe that our Global SMS API offers some exciting features and benefits that you'll want to take advantage of, and future feature development will be focused on the Global SMS API. For more information, see the Release Note on our Docs and Resources website.

Note that currently the Global SMS API does not support Premium Rate messaging. Existing Premium Rate customers should continue to use the MX Telecom APIs.

When an end-user contacts their carrier's Customer Services department with respect to a service, the carrier may elect to give the user a refund for the service. In this case no outpayment will be made by the carrier for the corresponding premium MT message. The MX Telecom SMS Gateway can inform partners of refund events via an HTTP interface.

Enabling refund notifications

Refund notifications are enabled on a per-account basis. Please contact us with a URL to which refund notifications should be posted to have this enabled on one or more of your SMS Gateway accounts.

Supported carriers

Refund notifications and reports are only supported on carriers where we receive notifications of refunds from the carrier. At present these are as shown in the table below. The table also shows the duration before refund information normally becomes available. Click here for a table of carrier codes.

Carrier codeDelay
BOOSTUSUp to 24 hours
CINGULARUSUp to 24 hours
NEXTELUSUp to 24 hours
SPRINTUSUp to 36 hours
TMOBILEUSUp to 36 hours
VERIZONUS48 to 72 hours
TIER3USUp to 1 month

Notification format

An HTTP GET request will be made to the configured URL by the SMS Gateway for each refund. The following parameters will be present in the GET request:

Parameter Always present? Meaning
network Yes Operator code for the carrier to which the affected SMS was sent. See here for possible values.
shortcode Yes Originator field from the affected SMS.
msisdn Yes The cell phone number for which the refund has been issued.
smsid Yes The SMS ID which was returned by the SMS Gateway when the affected SMS was sent. This is a positive 64 bit integer used to uniquely identify the SMS message.
date Yes The date and time at which the refund occurred. Format is "yyyy-MM-dd HH:mm:ss" in London UK time.
reason Yes Reason for refund, as defined below.
refundcomment No Text from carrier giving further details of the refund (where available).
mtusername Yes * The SMS Gateway MT account through which the refunded message was sent.
amount Yes The amount refunded, in cents.

* May not be present for some older integrations.

The reason parameter will be populated with one of the following Reason Codes:

Reason Code Meaning
100No / other reason given
110Subscriber did not use
111Subscriber not satisfied
112Subscriber did not receive message
120Duplicate purchase
121Did not remember purchase
122Unauthorized purchase
123Did not understand charges would recur
130Recycled MSISDN
131Out-out error

This is an example of a refund notification:

http://merchant.example.com/mxpay?network=CINGULARUS&msisdn=12125551234&shortcode=10990&smsid=3494029575&date=2009-08-04+02%3A15%3A00&reason=111&reasoncomment=Too+small&mtusername=uscitraffictxt2&amount=1498

Your server should return an HTTP 200 response with a non-empty body.

NOTE:

When sending HTTP GETs we will retry a request which fails after a timeout (currently 60 seconds), or which returns a non-200 response. It is the partner's responsibility to filter duplicate requests - these might occur if for some reason we did not receive the HTTP response from a previous attempt within 60 seconds.

To ensure the authenticity of the HTTP requests, you should only accept requests from the following IP addresses:

  • 83.166.68.0 - 83.166.69.255 (83.166.68.0/23)
  • 83.166.72.0 - 83.166.72.255 (83.166.72.255/24)
  • 208.93.48.0 - 208.93.51.255 (208.93.48.0/22)

The HTTP endpoint can be an HTTPS (SSL) URL to protect the data whilst in transit.

For more information, please contact us at 1-877-698-3532 or via email at sales@uk.openmarket.com.