Premium SMS refunds
Please make sure Sergel Connect Support have provided you with Username, Password, PlatformId, PartnerId and a GateId. To provide a GateId support will need a result receiver URL to which refund acknowledgements can be delivered. You will also need to know the MessageId of the transaction you wish to refund, this is provided to you through the API for sending messages when you do that. Username, Password, PlatformId, PartnerId can be the same as you use when submitting messages.
You will also need the MessageId and MSISDN of the message you wish to refund.
Please make an opening in your firewall if necessary so that Common can connect to your system. For a list of the addresses Common will connect from, see below. Refund results are sent asynchronously.
This document will describe the Application Programming Interface (API) to perform refunds of Premium (Overcharged) SMSes. Use this if your end-user has been billed and you wish to refund the charge to your end-user.
Actually sending the MT message is described in the document “Common_MT_and_DLR”, available separately.
A basic familiarity with JSON and REST is assumed.
When delivering a refund result to you asynchronously, the requests will be coming from the following IP addresses:
|
Hostname |
IP address |
|
socks1.sp247.net |
195.84.162.34 |
|
socks2.sp247.net |
194.71.165.71 |
|
socks3.sp247.net |
195.84.162.16 |
|
socks4.sp247.net |
194.71.165.98 |
|
socks5.sp247.net |
195.84.162.3 |
|
socks6.sp247.net |
194.71.165.122 |
Please add openings in your firewalls so that these six hosts can connect to you, if necessary.
All communication to and from Common will be encoded using UTF-8.
|
Parameter |
Data type |
Description |
|
messageId |
String |
The messageId of the message that should be refunded |
|
gateIds |
List<String> |
A list of gateIds where the callbacks should be delivered when the refund is processed. |
The following object is returned to you when the refund is processed. Usually you are only interested in the messageId and resultCode fields.
|
Parameter |
Data type |
Description |
|
refId |
String |
A reference id. Usually null. |
|
id |
String |
The messageId of the message processed |
|
operator |
String |
The telecom operator. Usually null. |
|
sentTimestamp |
Datetime |
The timestamp when the refund was requested. |
|
timestamp |
Datetime |
The timestamp when the refund was processed. |
|
resultCode |
Integer |
The result of the refund request. See table below for result codes. |
|
operatorResultCode |
String |
If the operator supplied more information, it will be here. Usually null. |
|
segments |
int |
The number of segments that were in the transaction that was refunded. For more information, see the MT documentation. |
|
gateCustomParameters |
List<String> |
Any custom parameters attached to the gateId supplied. |
|
customParameters |
List<String> |
Any custom parameters used to process the request. |
https://wsx.sp247.net/sms/refund
|
Method |
Request ok |
Invalid request |
Invalid login |
No access |
|
POST |
200 OK No response |
400 Bad Request |
401 Unauthorized |
403 Forbidden |
For all requests; set the header “Authorization” to “Basic [encoded string]” where [encoded string] is a base 64 encoded string of your username and password separated by a colon.
POST /platform/[platformId]/partner/[partnerId]/msisdn/[msisdn]
|
URI Parameter |
Data type |
Description |
|
platformId |
String |
Provided by Sergel Connect. |
|
partnerId |
String |
Provided by Sergel Connect. |
|
msisdn |
String |
The MSISDN of the transaction to refund. International format, no leading “+”. |
POST the refund object described in the Refund Data Type table above.
|
Result code |
Description |
|
16050 |
Message already queued for refund |
|
2300 |
Refund OK |
|
2301 |
Missing or illegal MSISDN for refund |
|
2302 |
Missing or illegal messageId for refund |
|
2303 |
Message is queued for refund |
|
2304 |
Refund timeout failure |
|
2305 |
Refund failure |
Substitute your own messageId, gateId, username, password, platformId, partnerId for the ones given in the example.
curl –user ”yourUsername:yourPassword” \ https://wsx.sp247.net/sms/refund/platform/yourPlatformId/partner/yourPartnerId/msisdn/46735555555 –data ’{”messageId”:”EDCRkibXW/YAAAFSrLwl9wDe”, ”gateIds”: [”BVldZyQt”]}’
When the refund has been processed, your callback URI (in the gateId) will receive a POST looking like this (Additional custom properties will come depending on country/segment):
{”refId”:null,”id”:”EDCRkibXW/YAAAFSrLwl9wDD”,”operator”:null,”sentTimestamp”:”2016-02-04T13:03:06Z”,”timestamp”:”2016-02-04T13:12:16Z”,”resultCode”:2300,”operatorResultCode”:null,”segments”:1,”gateCustomParameters”:null,”customParameters”:{”gateIds”:”xxxxxx”}
From 2020-11-15 will TLS 1.2 or higher be required for all HTTPS connections.
Support for TLS 1.0 and 1.1 will be discontinued. Versions 1.0 and 1.1 of TLS are older protocols that have been deprecated and are considered as security risks in the Internet community.
Sergel Connect strongly recommend to use HTTPS if HTTP is being used today.