Technical GuideOTP SMS ServiceSMPP Interface

Version 1.1

Sophisticated Simplicity In Mobile InteractionSophisticated Simplicity In Mobile Interaction

Table of Contents

1. Introduction to OTP SMS Service – SMPP Interface 3

2. Requirements for OTP SMS Implementation with SMPP 3

3. Technical Overview 43.1 General Interface Information3.2 tyntec Specific Interface Information

4. Detailed Communication Process 5

5. OTP SMS SMPP Features 65.1. swapdlr5.2. extendeddlr5.3. setton_npi5.4. Protocol id5.5. GSM Return codes in DLRs5.6. Buffered Notification5.7. Geographic Time Stamp5.8. Alphanumeric Sender ID5.9. Dynamic Sender ID replacement Feature

6. Example Java Programs 86.1 Reading the OTP automatically from the SMS on Android

7. Glossary of Terms 11

8. Frequently Asked Questions 11

9. Recommended values for SMPP parameters in submit_sm PDUs 13

10. Contact Information 13

Page

3

1. Introduction to OTP SMS Service – SMPP Interface

The One-Time Password (OTP) SMS SMPP is a service which enables you to send high quality SMS to all operators listed on tyntec’s network list using the SMPP protocol. This service is appropriate for mid-to-high-level usage (over 100.000 SMS sent / month). tyntec supports SMPP protocol version 3.4. The service also allows you to determine in real-time when a message is sent to invalid numbers and to notify your users to correct the numbers in order to receive the OTP.

Figure 1: The OTP SMS Communication Process with SMPP

The arrows show the direction of the data flow. Each arrow is labeled with the type of data carried. The essential data that is transported appears in brackets following the data type. A detailed overview of the communication process is provided in section 5 of this document.

2. Requirements for OTP SMS Implementation with SMPP

To implement and use the OTP SMS service with SMPP, the customer should have certain resources available that are not provided by tyntec. Choosing an existing SMPP software which is available in a variety of client models. The customer should choose one that is suitable for his needs.

Step 1 – Setting up a session (bind_transceiver)

Step 2 – Acknowledge bind request (bind_transceiver_resp)

Step 3 – Submit a message (submit_sm)

Step 4 – Acknowledge submit request (submit_sm_resp)

Step 5 – Optional: Submitting a delivery receipt (deliver_sm)

Step 6 – Acknowledge submitted DLR (deliver_sm_resp)

Customer

4

3. Technical Overview

3.1 General Interface Information

SMPP … is an industry standard. … is a tailor made protocol for short message handling. … offers a wide range of options to the user, such as setting the data coding.

3.2 tyntec Specific Interface Information

SMPP is a session based Peer-to-Peer (P2P) protocol. “Session based“ means a customer has to establish a connection to tyntec and use this connection to send messages. ‚Peer to peer‘ means that both the customer and tyntec (i.e. the peers) may use operations defined by the SMPP protocol, depending on the type of session. Authentication is done during the set-up of this connection. After the initial authentication, the session between the customer‘s system and tyntec‘s system (i.e. the peers) is kept open and alive.

There are three types of SMPP sessions:

– Transmitter session: used by the customer for sending SMPP requests to tyntec.

– Receiver session: used by tyntec for sending SMPP requests to the customer.

– Transceiver session: used in both of the above ways.

tyntec supports the following SMPP operations:

– bind_transmitter: used by the customer for establishing a transmitter session to tyntec. Answered by tyntec with a „bind_transmitter_resp“.

– bind_receiver: used by the customer for establishing a receiver session to tyntec. Answered by tyntec with a „bind_receiver_resp“.

– bind_transceiver: used by the customer for establishing a transceiver session to tyntec. Answered by tyntec with a „bind_transceiver_resp“.

– unbind: used by the customer for closing a session to tyntec. Works with every session type. Answered by tyntec with a „unbind_resp“.

– generic_nack: used by tyntec as a negative answer to any faulty request or if the service is currently unavailable. Works with every session type.

– submit_sm: used by the customer for sending a short message to tyntec. Works with transmitter and transceiver sessions. Answered by tyntec with a „submit_sm_resp“, which contains the message id. The message id is a unique identifier for each message.

– deliver_sm: used by tyntec for sending a DLR or an incoming MT (aka MO) message to the customer. Works with receiver and transceiver sessions. Should be answered by the customer with a „deliver_sm_resp“. If that is not the case (either no response or a generic_nack), we will try sending the deliver_sm again.

– enquire_link: may be used by tyntec and the customer to check if a session is still working. Works with every session type. tyntec sends an enquire_link through each open session every 90 seconds. This should be answered by the customer with an „enquire_link_resp“. If that is not the case (either no response or a generic_nack) for 5 consecutive times, tyntec will terminate the respective session. tyntec does answer with an enquire_link_responses to any incoming enquire_link. If the customer can not see the enquire_link_response, the session is likely to be dead.

5

4. Detailed Communication Process

The following section describes each step of the communication process. Each step is described individually with examples of the possible URL that may be used. For an overview of the process, please refer to Figure 1.

Step 1 - Setting up a session using a bind request

After entering the data given by tyntec (IP, port, username, password) into the SMPP client, a connection between the customer‘s system and tyntec will be established using one of the bind operations described above. For transmitting messages to tyntec, a transmitter or transceiver session is needed. Please note that after a session is established, any number of messages can be transmitted via this session. For receiving delivery receipts or incoming MT (aka MO), a receiver or transceiver session is needed.

tyntec recommends setting up one transceiver session or one transmitter and one receiver session.

Please note that setting up more that one session will not increase the available bandwidth at tyntec.

Step 2 - Acknowledge bind request

After tyntec receives a bind request with the correct authentication, a bind_resp will be issued and the session is available for communication.

Step 3 – Submitting a message

By using the submit_sm operation, the customer sends a message to tyntec. For details on the submit_sm operation and the PDU, please refer to the SMPP 3.4 documentation. A short summary of recommended values for some parameters is provided in section 9.

Step 4 - Acknowledge submitted message

After tyntec received a correct submit_sm request, a submit_sm_resp will be issued. The submit_sm_resp contains the message id in the message_id parameter, which is a unique identifier for each message. It may vary in length and layout, depending on the message. The submitting of the message to tyntec is closed with the issuing of the submit_sm_resp. The messages are stored in the tyntec SMSC and will be delivered to the receiver. If the initial delivery attempt is not successful – e.g. the receiving mobile phone is turned off – further attempts of delivering the message will be made. The message will be kept in the tyntec SMSC for 48 hours, after which it will expire.

Step 5 – Submitting a delivery receipt (DLR), optional

After a certain message is either delivered, can not be delivered or expired, tyntec creates a delivery receipt if this is requested in the initial submit_sm. The DLR will be submitted to the customer via an existing receiver or transceiver session using the deliver_sm operation. The delivery receipt itself is included in the text parameter of the deliver_sm PDU.

Please note that the tyntec deliver_sm content of the source and destination parameters match the values of the original submit_sm. This behaviour is different to the SMPP specification but commonly used. Upon request, tyntec can change the behaviour to match the SMPP 3.4 specification.

tyntec DLR format:The text in the deliver_sm will be in the following format:

“ id:<Tyntec‘s messageid> sub:001 dlvrd:001 submit date:YYMMDDhhmm donedate:YYMMDDhhmm stat:DDDDDDD err:E Text: . . . . . . . . .”

6

Possible values for DDDDDDD: – DELIVRD – message was successfully delivered– UNDELIV – message could not be delivered, e.g. due to unknown number– EXPIRED – message could not be delivered within validity period, maximum 48 hours– REJECTD – message was rejected, e.g. because an alphanumeric sender id was set without activated feature

Possible values for E: – message was delivered, used with DDDDDDD = DELIVRD– 002 – message was not delivered, used with DDDDDDD = UNDELIV– 006 – message expired, used with DDDDDDD = EXPIRED– 010 – message was rejected, used with DDDDDDD = REJECTD

Please note that the activation of special features may modify the values.

Text: the first few characters of the original message.

Step 6 – Acknowledge submitted DLR

After the customer received a deliver_sm, he must acknowledge the receipt by answering with a deliver_sm_resp. Otherwise, tyntec will re-issue the deliver_sm.

5. OTP SMS SMPP Features

There are a couple of additional features available for OTP SMS SMPP that can be activated upon customer request. For an overview of all features provided in the OTP SMS SMPP service (included by default or activated upon customer request), please refer to the Appendix 1 – Feature List.

These additional features available for OTP SMS with SMPP:

– swapdlr– extendeddlr– setton_npi– Protocol id – GSM return codes– Buffered notification– Geographic time stamp– Alphanumeric sender ID

tyntec does not support the following features:

– service_type: i.e. possibility of setting “Voice Mail Alerting“– replace_if_present_flag: for changing a “not yet delivered“ message– sm_default_msg_id: predefined messages of the SMSC– priority_flag: prioritizing the delivery of SMS

7

5.1. swapdlr

In the tyntec DLRs, the content of the sender and receiver parameters are set to the same values as the matching message. If this feature is activated, the contents are swapped, i.e. the content of the sender parameter in the original message becomes the receiver in the DLR.If this feature is activated, the originator and receiver number in the DLR to match SMPP 3.4 documentation.

5.2. extendeddlr

If this feature is activated, the TON/NPI values are set in the deliver_sm PDU that delivers the DLR to the customer (MT). The TON/NPI values match the values originally set by the customer in the submit_sm.

5.3. setton_npi

If this feature is activated, the customer may set ton/npi for the originator as he sees fit. We do not touch them. Every rule has its exception: If the originator is alphanumeric, we set the TON to 5.

5.4. Protocol id

This feature enables the setting of the protocol id as per GSM 3.40 documentation.

5.5. GSM Return codes in DLRs

The GSM return codes substitute the three tyntec response codes with a four-digit hexadecimal code. This feature allows the customer to see why a message failed.

A list of GSM error code values and their associated descriptions can be provided upon request to Customer Relations. This list is necessary for handling and understanding the return codes. You can use the GSM return codes to identify invalid phone numbers. This way you can determine in real time when your users provide a wrong number, e.g. as a result of a typo or their landline which is not SMS enabled. This feature gives you the opportunity to display a message in your app or on your website asking your user to correct the number in order to receive the OTP. Please refer to the GSM return codes document provided by tyntec for more details.

5.6. Buffered Notification

The buffered notification is sent to the customer if the first delivery attempt of a short message failed. In conjunction with the GSM Return codes, (see 5.5), it provides a good hint at the reason why a message was not delivered. The buffered notification follows the format of the DLR. In case of a buffered notification the Message State is set to “BUFFERD”.

5.7. Geographic Time Stamp

This feature adapts the time stamp to the local time of the home network. It is particularly useful for international mobile service providers and enterprises, which need to have the exact sending time adapted to the local time. (Please note this is not linked to the MSC, so if the subscriber is roaming the message will not show local time, it only shows the subscribers home network time).

5.8. Alphanumeric Sender ID

This feature allows specifying the originator field freely for each message. This feature is needed in order to send messages with an alphanumeric sender ID e.g. tyntec. The length of an alphanumeric sender ID is

8

between 1-11 characters.

5.9. Dynamic Sender ID replacement Feature

This feature can change an alphanumeric Sender ID or a shortcode to a normal MSISDN with international TON/NPI (1/1). It is particularly useful for networks who handle alphanumeric Sender IDS or shortcodes more sensitively. Please contact your account manager for further details.

6. Example Java Programs6.1 Reading the OTP automatically from the SMS on Android

On the Android OS it is possible to access the incoming SMS from an app and to read the OTP (One-Time Password) directly instead of asking the user to type it. This improves the customer experience and speeds up the OTP authentication process. It also increases the conversion rates, since you will remove an extra step that might have otherwise interrupted the authentication or registration process. You will find below some sample code that you can integrate into your Android app in order to read the OTP from the incoming SMS automatically.

/** * * @author tyntec * * Interface that is used to handle received SMS by a * dedicated android receiver object * */ private interface IMessageReceiver { /** * Called for each SMS received * * @param from originating phone number * @param text message text */ void onMessage(String from, String text); }

/** * Method that is called when user wants to pass and authorization * @param v */ private void onAuthButtonClick(View v) { setUiInitialState();

// Get a phone number from either android app widget or settings String phoneNumber = getPhoneNumber(); // Send auth request based on phone number sendAuthRequest( phoneNumber ); // Show a message or start an indication of the auth processing notifyUserRequestSended(); }

9

/** * This method must be called before the application exit */ private void unregisterReceiver() { if (receiver == null) return;

getApplicationContext().unregisterReceiver(receiver); receiver = null; }

/** * Registers special receiver object in the Android‘s infrastructure and * configures the object to forward received messages into the app. */ private void registerReceiver() { IntentFilter ifilter = new IntentFilter(); // Use number higher than 999 if you want to be able to stop processing and not to put // auth messages into the inbox. ifilter.setPriority(1000); ifilter.addAction(„android.provider.Telephony.SMS_RECEIVED“); // Create and hold the receiver. We need to unregister on shutdown receiver = createReceiver(); getApplicationContext().registerReceiver( receiver, ifilter ); }

private SmsReceiver createReceiver() { return new SmsReceiver(new IMessageReceiver() {

@Override public void onMessage(String from, String text) { processMessage(from, text); } }); }

/** * Method that is called on every SMS receive. * It needs to accept only valid originating phone number * @param from originating phone number * @param text message text */ private void processMessage(String from, String text) { if (isValidSender(from)) // Auth procedure performAuth(text); }

/**

10

* Class for receiving SMS * Required to be as a separate object for the Android‘s infrastructure. * Once SMS received it forwards it to IMessageReceiver object passed in the class‘s constructor * @author tyntec * */ public class SmsReceiver extends BroadcastReceiver { private static final String SMS_EXTRA_NAME = „pdus“;

private final IMessageReceiver messageReceiver; public SmsReceiver(IMessageReceiver messageReceiver) { if ( messageReceiver == null ) throw new IllegalArgumentException(„messageReceiver“);

this.messageReceiver = messageReceiver; }

@Override /** * Method that handles SMSs. * It iterates over all the messages and forward each method to IMessageReceiver object. */ public void onReceive(Context context, Intent intent) { Bundle extras = intent.getExtras();

if ( extras != null ) { Object[] smsExtra = (Object[]) extras.get( SMS_EXTRA_NAME );

for ( int i = 0; i < smsExtra.length; ++i ) { SmsMessage sms =SmsMessage.createFromPdu((byte[])smsExtra[i]);

String body = sms.getMessageBody().toString(); String address = sms.getOriginatingAddress();

messageReceiver.onMessage(address, body); } }

// WARNING!!! // Uncomment this if you do not want the SMS put into the inbox (for priority > 999) // this.abortBroadcast(); } }

}

11

7. Glossary of Terms

– MCC: Mobile Country Code consisting of 3 digits, e.g. 234 for UK.– MNC: Mobile Network Code consisting of 2 or 3 digits, e.g. 58 for Manx Telecom.– MSISDN: Mobile Subscriber ISDN Number.– GSM 3.40: ETSI document for Technical realization of the Short Message Service.– HTTP: Hyper text transfer protocol.– Unicode: A character encoding standard.– DLR: Delivery Receipt. A message that is delivered by tyntec to the customer and contains information on a

certain message, e.g. the time it was delivered to the handset.– HTTP request: A request sent to a webserver by a client using the HTTP protocol. In this case the HTTP

request contains all necessary data for a short message to be delivered to a mobile phone.– HTTP response: The response to an HTTP request sent to a client by a webserver. It contains the status of the

issued request. In this case, it may also contain the tyntec message reference. – RFC: Request for Comments (RFC) documents are a series of memoranda encompassing new research,

innovations, and methodologies applicable to Internet technologies. RFC documents are issued with a unique serial number.

– SMPP: Short Message Peer to Peer. A protocol used for transmitting short messages. – OTP: One Time Password.

8. Frequently Asked Questions

Q: I can‘t set-up a SMPP session because...A: ...Error: timeout or connection refused.

You should check the following:– If the IP address communicated to tyntec is really the IP of the computer which will connect to the tyntec

server.– If the computer is behind a firewall, gateway, router or the IP is NATed. If that is the case, provide the

respective IP to tyntec.– If local firewall blocks outgoing traffic, especially to the port number tyntec provided. If that is the case, allow

outgoing traffic in the firewall.– If the target IP tyntec provided is entered correctly into SMPP client software.– If everything of the above is correct, ask tyntec technical support for help.

...Error: invalid username / password. You should check the following:

– If the account data provided by tyntec was entered correctly into SMPP client software.– If the target IP tyntec provided is entered correctly into SMPP client software.– If the test messages are used up.– If everything of the above is correct, ask tyntec technical support for help.

Q: I can not send a message because...A: ...Error: general NACK.

You should check the following:– Message settings.

12

– If the submit_sm SMPP PDU is faulty (e.g. too long).– If a mandatory SMPP parameter is not correctly set.– If an optional SMPP parameter is set. If that is the case, do not set this parameter. tyntec does not support the

optional SMPP parameters.– Try again later as there may be difficulties at tyntec.

...Error: no response at all – tyntec might have encountered an error. Please contact support or try again later.

Q: The message did not arrive on the handsetA: You should check the following:

– If the receiver number is correct; especially look for the international prefix of the number.– If the handset is turned on and has good reception.– Message settings.– If network is supported by tyntec with the network list provided by tyntec.– Ask tyntec support to track message.

Q: The message arrived on the handset but is not readable / shows strange characters.A: You should check the following:

– Message settings, especially if the data coding set in the dcs parameter matches the coding used in the short_message parameter.

– tyntec recommends using the GSM 7 default character set. Other characters may not be displayed correctly.– Please note that interpretation of characters is always up to the handset, so handset issues are always

possible.

Q: The message was received on the handset, but I did not receive a DLR.A: You should check the following:

– If you requested a DLR in the submit_sm PDU, parameter registered_delivery.– If the there is a working receiver or transceiver session open to tyntec‘s SMSC. If this is not the case, establish

one.– For customers with more than one account server: if the DLR was received on the correct account or the

correct server. tyntec can not guarantee that a DLR is sent to the same server the original submit_sm originated from.

13

9. Recommended values for SMPP parameters in submit_sm PDUs

– dest_addr_ton: 1– dest_addr_npi: 1– dest_addr: receiver number in international format, i.e. with leading ‚+‘ or ‚00‘ plus country code– data_coding:

10. Contact InformationPlease contact tyntec’s Customer Relations for the enabling of features and for commercial conditions:

Email: customer-relations@tyntec.com Phone: +49 700 TYNTECBIZ or +49 89 202 451 200Fax: +49 89 202 451 101

Data coding

0

1

3

8

Description

European characters including French, Spanish and Nordic letters. Some Greek characters are also included, but not every character is covered. Euro sign is covered.

European characters.

European characters including French, Spanish and Nordic letters. SMPP only: ISO 8859-15, which also covers the Euro sign, is supported, although it is displayed as a generic currency symbol on most handsets.

Everything. All European, Greek, Arabic, Chinese, Thai, Kanji and special characters. Display on the handset differs strongly and may depend on setting of the handset (example: Chinese characters may not be displayed if the interface is set to European display). Note: A Unicode SMS may only contain 70 Unicode characters!See also: http://www.unicode.org/charts/ or http://www.unicode.org/charts/PDF/Unicode-4.1/

Name

GSM 7 aka SMSC Default alphabet

ASCII aka IA5 aka (CCITT T.50)/ASCII (ANSI X3.4)

Latin-1 aka ISO 8859-1

Unicode aka UCS2 aka ISO/IEC-10646 aka double-byte

14

Appendix 1 – Feature List

Feature

Delivery Receipt (DLR)

Binary content

Unicode

Concatenated

Flash SMS

WAP-Push SMS

MNP check for each message (before sending)

Flexible retry scheme

Validity Period

swapdlr

TON/NPI settings

Protocol ID / Over the Air (OTA)

GSM return codes in DLRs

Buffered Notifications

Geographic Time Stamps

Numeric Originator, Alphanumeric or Short Code Originator individual on each message

Alphanumeric Sender ID Replacement

Needs activation?

No

No

No

No

No

No

No

No

No

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Description

Provides a delivery report for sent messages.

A binary SMS message has 140 bytes of used data. This user data can be split into two parts: the user data header and the actual data. The user data header can be used to inform mobile phones about certain message types. This way SMS can be used to carry operator logos, ringtones, telephone settings and WAP-Push messages.

Provides SMS sending in different language alphabets.

Allows sending of concatenated messages. All parts of the concatenated message have to be sent independently to tyntec.

Message appears directly on the phone‘s screen, instead of being allocated in the inbox. It’s a useful alternative to normal SMS when you want to catch the recipient’s attention immediately.

Specially formatted SMS messages that display an alert message to the user, and gives the user the option of connecting directly to a particular URL via the mobile phone‘s WAP browser. This allows the sending party to enable the viewing and/or downloading of complex data by specifying a web link within a regular SMS format.

Checks the true home network of a mobile number before routing the message. It’s an essential feature for countries where Mobile Number Portability (MNP) is in place.

Minimum of 6 retries conducted in the time frame set by deliverStart and deliverEnd parameters. The exact scheme can be explained by the Customer Relations manager.

Customers use the Validity Period feature for time-restricted SMS messages, e.g. One-Time Passwords, which can be valid only for a certain short time period. This feature is conducted in the time frame set by deliverStart and deliverEnd parameters.

In the tyntec DLRs, the content of the sender and receiver parameters are set to the same values as the matching message. If this feature is activated, the contents are swapped, i.e. the content of the sender parameter in the original message becomes the receiver in the DLR. If this feature is activated, the originator and receiver number in the DLR to match SMPP 3.4 documentation.

Type of Number/Numbering Plan Indicator – This allows the customer to set the originator settings - the number as national format (07852 900460) instead of international +447852 900460. This feature is useful to recognize the characteristics of the number (international, national, alphanumeric, ISDN, etc.).

Sends OTA configuration messages, such as software updates, configuration settings and security locks. It‘s particularly useful for Mobile Device Management purposes.

Give a more detailed answer to why a response failed. This feature gives standard GSM return codes and tyntec codes, giving more detailed information about the status of the message.

Informs the customer of the reason for the unsuccessful delivery after the first SMS delivery attempt. The “Buffered Notification” is sent in the format of a DLR.

Adapts the time stamp to the local time of the home network. It is particularly useful for international mobile service providers and enterprises, which need to have the exact sending time adapted to the local time. (Please note this is not linked to the MSC, so if the subscriber is roaming the message will not show local time, it only shows the subscribers home network time).

Allows specifying the originator field freely for each message. This can allow a targeted, clear identity for sending to opt-in subscribers, and also facilitate 2-way exchange with them if a short code or a long number is set in this way. International e.g. +447852 900 460, short codes e.g. 80080 and alphanumeric e.g. tyntec 1. The length is 1-11 characters.

This feature can change an alphanumeric Sender ID to a normal MSISDN with international TON/NPI (1/1). It is particularly useful for networks who handle alphanumeric Sender IDs more sensitively. Please contact your account manager for further details.

Munich +49 (89) 202 451 100 – London +44 (207) 436 0283 – Singapore +65 6478 3020 - San Francisco +1.415.608.6127E-Mail sales@tyntec.com www.tyntec.com

Sophisticated Simplicity In Mobile Interaction