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.
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.
|BOOSTUS||Up to 24 hours|
|CINGULARUS||Up to 24 hours|
|NEXTELUS||Up to 24 hours|
|SPRINTUS||Up to 36 hours|
|TMOBILEUS||Up to 36 hours|
|VERIZONUS||48 to 72 hours|
|TIER3US||Up to 1 month|
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:
|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:
|100||No / other reason given|
|110||Subscriber did not use|
|111||Subscriber not satisfied|
|112||Subscriber did not receive message|
|121||Did not remember purchase|
|123||Did not understand charges would recur|
This is an example of a refund notification:
Your server should return an HTTP 200 response with a non-empty body.
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:
- 18.104.22.168 - 22.214.171.124 (126.96.36.199/23)
- 188.8.131.52 - 184.108.40.206 (220.127.116.11/24)
- 18.104.22.168 - 22.214.171.124 (126.96.36.199/22)
The HTTP endpoint can be an HTTPS (SSL) URL to protect the data whilst in transit.