Contents

Before you begin

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.

Scope of this document

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.

IP addresses

When delivering a refund result to you asynchronously, the requests will be coming from the following IP addresses:

Please add openings in your firewalls so that these six hosts can connect to you, if necessary.

Character encoding

All communication to and from Common will be encoded using UTF-8.

Data types

Refund

Refund Response

The following object is returned to you when the refund is processed. Usually you are only interested in the messageId and resultCode fields.

Performing a refund

Base URL

https://wsx.sp247.net/sms/refund

HTTP methods, statuses and actions

Basic authentication

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.

Request refund

POST /platform/[platformId]/partner/[partnerId]/msisdn/[msisdn]

POST the refund object described in the Refund Data Type table above.

Result codes

Examples

Substitute your own messageId, gateId, username, password, platformId, partnerId for the ones given in the example.

cURL 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"}

Appendix 1

Supported TLS versions

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.

Changelog of this document