Premium SMS API Centili Premium SMS API
1. Introduction... 3 1.1 Flow Summary... 3 1.2 Requirements... 3 2. MO restful web service (required on Merchant side)... 3 2.1 Example:... 3 2.2 Parameters... 4 3. MT send restful web service (Centili)... 4 3.1 Parameters... 5 3.2 MT service Response... 5 3.3 200 Success response body:... 6 3.1 Parameters... 6 3.2 400 Bad request response body:... 7 3.1 Parameters... 7 4. DLR restful web service (required on Merchant side)... 7 4.1 Example:... 8 4.2 Parameters... 8
1. Introduction 1.1 Flow Summary User sends a SMS message to short number Message is forwarded to merchants MO web service Merchant evaluates received message and decides to charge the user and how much will charge it for. Charge request is sent to Centili MT send web service. After MT send request has been received Centili charges user for requested amount and result of charging operation is sent to Merchant on DLR web service 1.2 Requirements Merchant must expose following web services: MO restful web service (MO Uri) DLR restful web services (DLR Uri) Centili exposes following web service: MT send restful web service (MT Uri) 2. MO restful web service (required on Merchant side) Mo web service receives the user s SMS message pushed from Centili system on the Merchant side. To be able to receive MO message Merchant should provide MO Uri where message will be submitted, with following information: Server name or IP address (e.g. example.com) Server port (e.g. 80) Script name and location, if any (e.g. /mo/receive.php) 2.1 Example: http://example.com/mo/receive.php http://example.com:8080/mo/receive.php MO message is received as HTTP POST request with Content-Type: application/xwww-form-urlencoded composed of parameters with associated values. POST http://example.com/mo/receive.php HTTP/1.1 Host: example.com:80 Content-Type: application/x-www-form-urlencoded Date: Thu, 06 Jun 2011 07:51:59 GMT
msisdn=491626839553&shortcode=808181&keyword=pay&message=pay%20token &operator=26202&date=2012-01-03%2000%3a02%3a35&transactionid=505478 2.2 Parameters Required msisdn Message sender s MSISDN. Conforms to the following format: (example: Vodafone DE MSISDN 491626839553) Country code (49) National Destination Code (162) Subscriber Number (6839553) shortcode Short number that the message is delivered to keyword Service keyword (reserved keyword for merchant service) String message Received SMS message String operator Mobile country code and mobile network code (mcc+mnc) concatenated(http://en.wikipedia.org/wiki/mobile_network _Code), max. 17, max. 6 date Date and time of MO message reception (UTC) Date-time, yyyy- MM-dd HH:mm:ss transactionid Unique transaction identifier assigned to this particular transaction Upon successful HTTP submission Merchant application should respond with HTTP/1.1 200 OK response; otherwise Centili server will retry request in regular intervals until application responds properly or until message validity expires (by default, validity is 24 hours). 3. MT send restful web service (Centili) MT send message request is submitted as HTTP POST with Content-Type: application/x-www-form-urlencoded composed of parameters with associated values. <MT URI>/1/api/sms/mt Centili supplied uri of MT send restful web service. POST http://<mt URI>/1/api/sms/mt HTTP/1.1 Accept: application/json Host: <CENTILI HOST>:80 Content-Type: application/x-www-form-urlencoded Date: Thu, 06 Jun 2011 07:51:59 GMT
msisdn=491626839553&operator=26202&username=username&password=passwo rd&shortcode=808181&transactionid=505478&flow=1&price=150&message=<m essage>&apikey=<apikey>&referenceid=ab123dnb&messagetype=1 3.1 Parameters Required msisdn operator Message sender s MSISDN. Conforms to the following format: (example: Vodafone DE MSISDN 491626839553) Country code (49) National Destination Code (162) Subscriber Number (6839553) Mobile country code and mobile network code (mcc+mnc) concatenated (http://en.wikipedia.org/wiki/mobile_network_code), max. 17, max. 6 username Account username String password Account password String apikey Application key Centili issued String shortcode Short number that the message is delivered to (user will receive message from this number) message Message that will be sent to msisdn (160 GSM7, 70 Unicode) String transactionid flow price Optional Unique transaction identifier assigned to this particular transaction, received on MO request 1 - sms 2 - web Message price in native currency, with (.) dot as decimal separator. (example: 1.99 or 4.99) referenceid Custom ID assigned by Merchant to MT message. It will be returned in delivery report and can be used as reference. String, max 30 characters messagetype simple (default) wappush wapheader Message part of the WAP push String 3.2 MT service Response The response content type is application/json. (Content-Type: application/json) Response codes - HTTP response codes are used to indicate: 200 Success - MT request accepted successfully
400 Bad request; check the error message and correct the request syntax. 401 Authentication failure, check your authentication requirements. 403 Forbidden; please provide authentication credentials. 404 Not found: mistake in the host or path of the service URI. 405 Method not supported 503 Server busy and service unavailable. Please retry the request. 3.3 200 Success response body: HTTP/1.1 200 OK Content-Type: application/json Date: Thu, 14 Jun 2011 02:51:59 GMT Location: http://<centili-uri>/1/api/sms/mt/491626839553 { } "msisdn": "491626839553", "operator": "26202", "transactionid": 491626839553, "referenceid": "AB123DNB", "resourceurl": "http://<centiliuri>/1/api/sms/mt/491626839553", "status": 4 Parameters JSON Success response msisdn operator transactionid referenceid Customer MSISDN. Conforms to the following format: (example: Vodafone DE MSISDN 491626839553) Country code (49) National Destination Code (162) 3. Subscriber Number (6839553) Mobile country code and mobile network code (mcc+mnc) concatenated (http://en.wikipedia.org/wiki/mobile_network_code) Unique transaction identifier assigned to this particular transaction, received on MO request Custom ID assigned by Merchant to MT message, if any (empty if not supplied), max. 17, max. 6 String, max 30 characters resourceurl URl that identifies started task String status 1 "Initiated", Action is initiated by user 2 "Success", Action success 3 "Failure", Action failed 4 "Pending", Result will be delivered in a call back Number
5 "Closed", stared transaction is administratively closed (Initiated - > Closed) 3.4 400 Bad request response body: HTTP/1.1 400 Bad Request Content-Type: application/json Date: Thu, 14 Jun 2011 02:51:59 GMT { } "errorid" : 1006, "message": " Transaction number required" "description" : "Value for transactionid is null or empty" Parameters JSON Bad request response errorid 1001, "Authorization failed" 1002, "IP authorization failed" 1003, " Nonexistent API key" 1004, "Auth. API key mismatch" 1005, "Invalid Transaction number" 1006, "Transaction number required" 1007, " Transaction is already used - processed" 1008, "Submitted price is invalid" 1009, "Sending bulk SMS messages is not enabled" 1012, "Bad request input value is missing" 1013, "Authorization parameters are missing" 1014, Transaction is expired and closed 1015, "Invalid MSISDN for transaction" 1016, "Error submiting message to Mobile Operator" message Error message with error description String description Additional error description String For all other response codes response body will be empty, content length will be 0. (Content-Length: 0) 4. DLR restful web service (required on Merchant side) DLR web service receives notification when state of MT send request changes. Merchant should provide MT Uri where message will be submitted, with following information: Server name or IP address (e.g. example.com) Server port (e.g. 80)
Script name and location, if any (e.g. /dlr/receive.php) 4.1 Example: http://example.com/dlr/receive.php http://example.com:8080/dlr/receive.php Delivery message is received as HTTP POST request with Content-Type: application/x-www-form-urlencoded composed of parameters with associated values. POST http://example.com/dlr/receive.php HTTP/1.1 Host: example.com:80 Content-Type: application/x-www-form-urlencoded Date: Thu, 06 Jun 2011 07:51:59 GMT msisdn=491626839553&shortcode=808181&operator=26202&date=2012-01- 03%2000%3A02%3A35&transactionid=505478&referenceid=AB123DNB&status=2 &description=2 4.2 Parameters Required msisdn operator shortcode transactionid Message sender s MSISDN. Conforms to the following format: (example: Vodafone DE MSISDN 491626839553) Country code (49) National Destination Code (162) 3. Subscriber Number (6839553) Mobile country code and mobile network code (mcc+mnc) concatenated(http://en.wikipedia.org/wiki/mobile_net work_code) Short number that the message is delivered to (user will receive message from this number) Unique transaction identifier assigned to this particular, max. 17, max. 6 transaction, received on MO request date Delivery report timestamp Date-time, YYYY-MM- DD HH:MM:SS referenceid Custom ID assigned by Merchant to MT message. It will be returned in delivery report and can be used as String, max 30
status description Optional errortext reference. 1 "Initiated", Action is initiated by mobile subscriber 2 "Success", Action success 3 "Failure", Action failed 4 "Pending", Result will be delivered in a call back 5 "Closed", started transaction is administratively closed (Initiated - > Closed) 1, "The message is in inprocess at operators SMSC" 2, "Message is delivered to destination" 3, "Message presumably is delivered to destination" 4, "Message is delivered with payment risk" 5, "Message is submited to SMSC" 6, "Message validity period has expired at operators SMSC" 7, "Message validity period has expired in Centili system" 8, "Message unroutable unknown operator" 9, "Message unroutable unknown MSISDN" 10, "Message could not be delivered because operators SMSC is not responding" 11, "Message deleted from operators SMSC" 12, "Message is undeliverable at operators SMSC" 13, "Message blocked by Centili" 14, "Operator charging failed" 15, "Insufficient Funds on prepaid subscriber account" 16, "Internal centili system error" 17, "Message is in accepted state" 18, "Message is in a rejected state" 19, "Daily limit exceed" 20, "Monthly limit exceeded" 99, "Message is in invalid state" Additional description of the status if deliver has failed (gives a more detailed textual representation). characters Number String Upon successful HTTP submission Merchants application should respond with HTTP/1.1 200 OK response; otherwise Centili server will retry request in regular intervals until application responds properly or until message validity expires.