Dia SDP Ussd API Dgdv1.3.0
Dia SDP Ussd API Dgdv1.3.0
Dia SDP Ussd API Dgdv1.3.0
475, Union Place Colombo-2 Sri Lanka Tel: +94-777-678700 Fax: +94-777-087917
Document Code DIA-SDPAPI-DGD-v1.3.0 Last edited: 09 August 2012 Copyright 1997-2012 hSenid Mobile Solutions (Pvt) Ltd. All rights reserved. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without prior written permission from hSenid Mobile. All copyright, confidential information, patents, design rights and all other intellectual property rights of whatsoever nature in and to any source code contained herein (including any header files and demonstration code that may be included), are and shall remain the sole and exclusive property of hSenid Mobile. The information furnished herein is believed to be accurate and reliable. However, no responsibility is assumed by hSenid Mobile for its use, or for any infringements of patents or other rights of third parties resulting from its use. All other trademarks in this publication are the property of their respective owners.
Idea Mart Pro USSD API Guide for Dialog Axiata PLC
Table of contents
Chapter 1.......................................................................................................................................6 1 Overview ................................................................................................................................6 1.1 1.2 1.3 SMS Service .......................................................................................................................... 6 USSD ..................................................................................................................................... 6 CAAS ..................................................................................................................................... 6
Chapter 3.......................................................................................................................................8 3 USSD.......................................................................................................................................8 3.1 Send Service ......................................................................................................................... 8 Request ......................................................................................................................... 8 Response ..................................................................................................................... 10 Request ....................................................................................................................... 11 Response ..................................................................................................................... 13
Appendix a ..................................................................................................................................14 Status Codes and Error Codes......................................................................................................14 Status Codes (Non Retry able) ................................................................................................... 14 Error Codes (Non Retry able) ..................................................................................................... 14 Error Codes (Retry able) ............................................................................................................ 15 Appendix b ..................................................................................................................................16
Page 3 of 16
Idea Mart Pro USSD API Guide for Dialog Axiata PLC
Change Control
Version 1.0.0 Date 27/12/11 Description Final Documentation Author hSenid Mobile Technical Writing Team 1.1.0 15/05/12 Baselined to send to customer after updates 1.2.0 13/07/12 Added USSD details to the document hSenid Mobile Technical Writing Team hSenid Mobile Technical Writing Team 1.2.1 27/07/12 Added CAAS details to the document hSenid Mobile Technical Writing Team 1.2.2 27/07/12 Updated document as per feedback hSenid Mobile Technical Writing Team
Page 4 of 16
Idea Mart Pro USSD API Guide for Dialog Axiata PLC
Page 5 of 16
Idea Mart Pro USSD API Guide for Dialog Axiata PLC
Chapter 1
1 Overview
This chapter describes how the Service Providers can use the HTTP-based Interfaces from Idea Mart for SMS, USSD and CAAS services. For more details on each service please refer the relevant document.
1.2 USSD
The USSD Interface allows applications to initiate USSD sessions using a HTTP-based API. Supported services are as follows: Send Service An application wishing to send response to MO USSD session should call this method. Deliver Service Deliver Service can be either a user initiated session or a response to an existing USSD session.
1.3 CAAS
Applications have Caas NCS access if charging as a service requests are required by the application. Query Balance This service retrieves the account balance and other related information of a given subscriber MSISDN. Direct Debit This service charges a specific amount from a subscribers account.
Page 6 of 16
Idea Mart Pro USSD API Guide for Dialog Axiata PLC
Chapter 2
2 HTTP REST
In this context, both requests/responses used to exchange information are with content type "application/json".
Page 7 of 16
Idea Mart Pro USSD API Guide for Dialog Axiata PLC
Chapter 3
3 USSD
USSD (Unstructured Supplementary Service Data) is a capability built into SMS-based mobile devices. USSD information is directly sent from the senders device to an application which is with USSD platform. A USSD service can be invoked either by the mobile user or by a USSD platform.
3.1.1 Request
Following is a sample request for send service.
{ "applicationId": "APP_000001", "password": "password", "message": "1. Press One 2. Press two 3. Press three 4. Exit", "sessionId": "1330929317043", "ussdOperation": "mt-cont", "destinationAddress": "tel:94771122336" }
M/O M M
Page 8 of 16
Idea Mart Pro USSD API Guide for Dialog Axiata PLC
version
API version (shall be numbered as 1.0 etc) If not specified shall be validated against the latest version
sessionId
Unique number that USSD Gateway assigns to the application for the duration of the session. This number will be maintained in all messages throughout a single session.
String
ussdOperation
USSD operation mo-init: Idea Mart to assign when a USSD session is initiated by subscriber mo-cont: Idea Mart to assign for any USSD message originated from subscriber, that comes after a init mt-init: App to assign when a USSD session is initiated by an application mt-cont: App to assign for any USSD message originated from application, that comes after a init mt-fin: App to assign when session ends in final message
Enumerator Data type will be string where the operation name itself will be used in the parameter value.
destinationAddress
String
tel: 94771122336 Note : tel might be a masked number depending on the type of application encoding Encoding scheme used in the message 440 - Plain ASCII characters Enumerated O
Page 9 of 16
Idea Mart Pro USSD API Guide for Dialog Axiata PLC
chargingAmount
Charging amount specified for variable charging applications only Shall be considered only in system currency
{ "applicationId": "APP_000001", "password": "password", "version": "1.0", "message": "1. Press One 2. Press two 3. Press three 4. Exit", "sessionId": "1330929317043", "ussdOperation": "mt-cont", "destinationAddress": "tel:94771122336", "encoding": "440", "chargingAmount": "5" }
3.1.2 Response
USSD-Send-Response is a response from the Idea Mart to the application, which will be sent as a response to the USSD-Send-Request message.
Following are the response parameters of send service. Parameter Name version requestId Description API version (shall be numbered as 1.0 etc) MessageID to uniquely Identify the request within the Idea Mart timeStamp statusCode statusDetail Processed timestamp The status code for the entire request The status detail for the entire request String String M M M
Page 10 of 16
M/O M M
Idea Mart Pro USSD API Guide for Dialog Axiata PLC
{ "statusCode": "S1000", "timeStamp": "1203051205", "statusDetail": "Success", "requestId": "1330929317059", "version": "1.0" }
3.2.1 Request
Following is a sample request for receive service.
{ "message": "*141#", "ussdOperation": "mt-cont", "requestId": "1330933229901", "sessionId": "1330929317043", "encoding": "440", "sourceAddress": "tel:94771122336", "applicationId": "APP_000001", "version": "1.0" }
Page 11 of 16
Idea Mart Pro USSD API Guide for Dialog Axiata PLC
Following are the request parameters of deliver service. Parameter Name version applicationId sessionId API version (shall be numbered as 1.0 etc) Application ID as given when provisioned Unique number that USSD GW assigns to the application for the duration of the session ussdOperation USSD operation mo-init: Idea Mart to assign when a USSD session is initiated by subscriber mo-cont: IDEA MART to assign for any USSD message originated from subscriber, that comes after a init mt-init: App to assign when a USSD session is initiated by an application mt-cont: App to assign for any USSD message originated from application, that comes after a init mt-fin: App to assign when session ends in final message sourceAddress sender address sourceAddress: tel:94771122336 vlrAddress message encoding VLR address of the sender Message as sent from the user Encoding scheme used in the message 440 - Plain ASCII characters requestId Request ID to uniquely Identify the request within the Idea Mart String M String String Enumerated O M M String M Integer M String String String M M M Description Type M/O
Page 12 of 16
Idea Mart Pro USSD API Guide for Dialog Axiata PLC
3.2.2 Response
Deliver-USSD-Response should be the response given by the Application to the Idea Mart as an acknowledgement on the receipt of a MO message submitted by Idea Mart.
Description The status code for the entire request The status detail for the entire request
M/O M M
Page 13 of 16
Idea Mart Pro USSD API Guide for Dialog Axiata PLC
Appendix a
Page 14 of 16
Idea Mart Pro USSD API Guide for Dialog Axiata PLC
E1334
SMS sent to <application name> application could not be processed as the message length is too long. Maximum message length allowed is <specify_max_limit>
E1601 E1342
System experienced an unexpected error. MSISDN is black listed. Not authorized to use the application <application_name>
E1343
MSISDN is not white listed. Only white list numbers are allowed to send messages at this state.
E1325
E1308
Page 15 of 16
Idea Mart Pro USSD API Guide for Dialog Axiata PLC
Appendix b
What follows is a list of definitions of all terms, acronyms and abbreviations required to properly interpret this document. NCS Network Capability Service SMS Simple Message Service HTTP Hyper Text Transfer Protocol MO Mobile Originated MT Mobile Terminated MSISDN Mobile Station Integrated Services Digital Network SLA Service Level Agreement
Page 16 of 16