SMS Gateway
HTTP Interface
Refund Notifications
Overview
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 code | Delay |
| BOOSTUS | Up to 24 hours |
| CINGULARUS | Up to 24 hours |
| DOBSONUS | Up to 1 month |
| 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 |
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 |
| 100 | No/Other reason given |
| 110 | Subscriber did not use |
| 111 | Subscriber not satisfied |
| 112 | Subscriber did not receive message |
| 120 | Duplicate purchase |
| 121 | Did not remember purchase |
| 122 | Unauthorized purchase |
| 123 | Did not understand charges would recur |
| 130 | Recycled MSISDN |
| 131 | Out-out error |
This is an example of a refund notification:
http://merchant.example.com/mxpay?
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 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.
