Docstoc

Gateway SMS Premium

Document Sample
Gateway SMS Premium Powered By Docstoc
					Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                  Last Revision. 19/07/2010




                   Gateway SMS Premium
                     Language: English (international)




               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid Spain
               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid --Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                   Last Revision. 19/07/2010




General information

Introduction.
MobiAdvanced is a platform which allows you to offer methods of payment via mobile telephone
through SMS premium,which can be integrated and automated with other applications, webs or
other means. MobiAdvanced also offers tools of practical use related to payment via SMS premium
and different services related to payment systems and mobile marketing.

Notice of non-liability
Mobiadvanced offers no warranties of any type be they express, implied or statutory of the
information contained in this document. Mobiadvanced assumes no liability of damages direct or
indirect resulting from the use of this document or of the examples of the codes contained within.
MobiAdvanced reserves the right to carry out changes and corrections in the document with prior
notice. MobiAdvanced does not guaranty the future validity of this document. Before using this
document we recommend you ensure that it is the latest version of the same.

Document
This document describes the integration process of the tool “gateway” offered by MobiAdvanced.
Even though the integration of this tool offers simple methods of implementation ... for it’s use one
needs to posses a minimum knowledge of web development, HTTP communication standards and
language standards of web communication.

This document focuses on the technical detail of the integration not on the function of each type of
service or method of payment which can be integrated. When carrying out the integration, one
should take into account the technical and legal details of each method of payment integrated. It is
very important you know the details referent to each method.

* Request information in case of not having it available.



Intended Audience
This document is aimed at developers and merchants MobiAdvanced clients who want to integrate
their payment services and test them before putting them into production.




                MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                  Last Revision. 19/07/2010




Definitions and basic necessary information.
Below a series of concepts and definitions which you need to know before carrying out any type of
integration with MobiAdvanced.




SMS Premium
Premium SMS are defined as SMS having an additional cost in exchange for receiving an
additional service. The basic process of payment through a premium SMS can be summarized in
the following steps: The user sends an SMS to a short number, this SMS is passed on to the
telephone operator, afterward the operator passes on the SMS to the service provider which in turn
sends an SMS to the user indicating the service contracted. A special rate is included in the users
telephone bill, after a predetermined time the service supplier is paid a percentage of the total
billed to the user.



SMS MO
An SMS Mo is that originating in the users terminal ( Mobile Originated ), Ex: when the user writes
an SMS to request a service.



SMS MT
-SMS MT: an SMS MT are those received in the users terminal ( Mobile Terminated ), Ex: when the
user receives an SMS in responds to a service.



SMS Premium with opt-in simple
This type of premium SMS is the most common. The user sends an SMS-MO and receives an
SMS-MT with information for the requested service, opt-in can be understood as “ confirmation “ in
tis type of premium SMS, it is understood as simple opt-in being that user sending a first SMS-MO
would be carrying out a confirmation.




               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                  Last Revision. 19/07/2010



SMS Premium with double opt-in
This type of premium SMS is used in ranges going above common price or in some type of
premium subscriptions. The user sends a first SMS-Mo requesting the service receiving an SMS-M
that indicates the service the service to be contracted and requesting a SMS-MO as confirmation
to the response, once the user responds the SMS-MT an SMS-MO is sent informing of the service
contracted. It is understood as a double opt-in being that the user makes a first confirmation with
an SMS-MO and then is requested to send a second SMS-MO as confirmation.



MO Service
Is understood as the SMS-MO in which the user requests the service. Also defined as “MO1”



MO Opt-in
SMS-MT in which information about the service to be contracted is given and/or you request
confirmation to complete a service. In some payment methods and/or exceptions of operators
require the sending of an MT-opt-in with information of the service to be contracted. Also defined
as “MO2”



MT Service
SMS-MT in which you respond with the contracted service. Also defined as “MT1”



MT Optin
SMS-MT in which information about the service to be contracted is given and/or you request
confirmation to complete a service. In some payment methods and/or exceptions of operators
require the sending of an MT-opt-in with information of the service to be contracted. Also defined
as “MT2”



MT Extra
in some cases due to the nature of the service contracted it is required to send more than one MT,
Ex: in the case of a response to a text with a higher number of characters and an extra MT may be
required to complete the text. Also defined as “MT3”



Billing model
The billing model varies according to the method of payment, it indicates at which moment of the
transaction the user is charged for the service.




               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                  Last Revision. 19/07/2010



Model “Billing-MO”
the charge is applied when the user sends the first service MO. Ex: if the user is prepayment and
has no credit available he will be unable carry out the order requesting the service.



Model “Billing-MT”
the charge is applied once the user receives the service MT.




Sale cycle
The sale cycle defines the process and type of SMS required to complete a transaction and that it
may be paid. The sale cycle may vary depending on the method of payment and the telephone
operator.



1 - Example:


 One method of payment may require a sale cycle, MO-service+MT+MT service if the user
 doesn’t receive the MT service, the transaction will not be paid. The case may arise that a
 same method of payment be applied to different sale cycles depending on the telephone
 operator.




2 - Example:


 In operator A’s case an MO service + an MT service is require and in operator B’s case an
 MO-service + MT service +MT opt-in is required ( as it was previously indicated an MT opt-in
 may be used as an information method in premium SMS simple opt-in.)




Sale cycle time
Depending on the payment method and/or operator there is deadline o complete a cycle once this
deadline is past the transaction will be marked as incomplete and will not be paid.




               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                  Last Revision. 19/07/2010




Types of SMS
The type of message may vary depending on content and format, MobiAdvanced’s platform will
accept the following types of messages, (The type of message varies depending on the method of
payment ) if you plan on using a different type of message than SMS-TEXT check availability for
the payment method before you carry out your integration.



SMS-TEXT
Common text messages accept up to 160 characters and GSM 3.38 7bit charset. ( the length may
vary depending on the payment method and legal obligations and the need to include obligatory
information )



SMS-FLASH
Messages with text appearing on screen accept up to 160 characters and GSM 3.38 charset. ( the
length may vary depending on payment method and legal obligations and the need to include
obligatory information. )



SMS-WAP
Messages in wap format, these may include a URL which will be included in the WAP message of
up to 255 characters and a text that will be as “anchor” for that URL , of up to 55 characters using a
3.38 charset.



SMS-UCS2
Messages encoded UCS2 accept up to 70 characters, this type of message admit the majority of
international characters ( length may vary depending on the method of payment and legal
obligations and the need to include obligatory information. )



SMS-UDH
this type of SMS “user-defined-header” allows to define the codification of the SMS and its content.
in hexadecimal format. This type of SMS there are usually used in special content like Logo
operators and ringtones.




               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                  Last Revision. 19/07/2010




Gateway, general concept
The Gateway Tool provides a “bridge” of transparent communication between Mobiadvanced’s
platform and an external application. This way at the moment that a transaction is made, it is
reported automatically to the external application. Configuration and options for gateway tool are
detailed below.

All configuration options can be defined in the tool control panel. Not all options mentioned in this
document are available by default. If you require any of these options that by default are not
available, please contact MobiAdvanced’s support staff.




Methods of integration
The MobiAdvanced “Gateway” tool, provides two methods of integration, that differ in the response
mode selected. There are two methods:



1. HTTP - Direct response in the request content.
      The necessary MT’s to complete the transaction, will be defined in the content of the HTTP
      request made by MobiAdvanced’s platform. This options requires a low level of knowledge
      and is recommended in the most cases that require a fast and simple integration. A
      disadvantage is that it requires that the content of the request be generated in the same
      instant as the request is made.



2. HTTP - Asynchronous response through API
      The SMS-MT’s will be informed in asynchronous way, at a different moment that the request
      of notification is made. the notification of these MT’s is made through the MobiAdvanced’s
      API. It’s necessary that the user have an API KEY for use the API.



In both methods of integration it is necessary to have a URL where the transaction will be reported.
This URL can be defined or modified at any time by the user. The URL can use HTTP or HTTP’s
protocol.

In the below sections, you will find more information about the HTTP notifications.




               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                  Last Revision. 19/07/2010




Opt-in Management
MobiAdvanced’s “Gateway” tool has two options when we are dealing with methods that require
Opt-in MT’s.



1. Opt-in managed by system
      This is the option selected by default. Delegating to MobiAdvanced the job of setting the Opt-
      in MT’s required to complete the sale cycle. This is the recommended option, being that you
      only have to respond the MT-service.



2. Opt-in managed by user
      The user is responsible for responding all the Opt-in MT’s, and they can be detailed by the
      user. This option of management is not available by default. If you require please contact
      MobiAdvanced’s support staff.



The content and nomenclatures used in Opt-in MT’s vary by payment method, You must take into
account the laws and rules defined for each method and/or country, because it is imperative to
follow these rules and laws.




HTTP request
Each transaction MobiAdvanced’s platform reports, with a HTTP request to the URL defined in the
configuration’s tool.

The request must be completed and answered with “HTTP code 200”, In case that the response
isn’t “HTTP code 200”, this request will be defined as an error, and the error control process is
started.



The HTTP request allows two types of methods for sending the parameters: HTTP POST and
HTTP GET. both methods use the same name of variables. This option can be defined in the panel
control of this tool.




               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                          Last Revision. 19/07/2010




HTTP request variables
Variables names.
Names of the variables used in HTTP POST and HTTP GET requests. The charset encoding used
is UTF-8 for all the variables.



 Name                                  Type            Desc
                                                       A Unique reference for SMS EX: MO1-28728792 it is
id_psms_sale_transaction               Varchar(32)
                                                       recommended save this value to control the duplicity.
                                                       Transaction ID “not unique” EX: can be the same for an MO
id_psms_sale                           Varchar(32)
                                                       Opt-in and a MO-service that belong to the same “sale”
id_psms_cmp                            int(9)          ID for the campaign in MobiAdvanced.
psms_cmp_title                         varchar(128)    Title defined in the campaign.
operator_mcc                           int(3)          MCC code operator.
                                                       MNC code operator. combined “MCC/MCN” are used to
operator_mnc                           int(3)          determine the operator ( see the operators list on each
                                                       payment method details. )
operator_code                          varchar(16)     Short name for the operator.
operator_title                         varchar(64)     Name of the operator.
psms_method_sc_number                  int(10)         Number of the Short code.
psms_method_sc_price                   float(6,3)      User price in local currency , whit out VAT.
psms_method_sc_currency                ISO             ISO 4217 code.
psms_method_sc_price_vat               float(4,2)      Percent of VAT applied in the sale.
psms_method_billing_mode               String(mt, mo) Billing mode used in the sale ( see basic information )
psms_method_lang                       ISO             ISO 639-1
psms_method_country                    ISO             ISO 3166-1 alpha 2
psms_sale_mo_number                    varchar(16)     Client mobile number , with country prefix, with out + symbol
                                                       Determine the type of the MO MO1 = MO-service MO 2 = MO
psms_sale_mo_type                      MO1 o MO2
                                                       Opt-in.
psms_sale_mo_time                      timestamp       Sale timestamp, format: YYYY-mm-dd hh:ii:ss
psms_sale_mo_data                      varchar(160)    Text in the content of the SMS.
psms_sale_alias                        varchar(32)     Principal ALIAS.
psms_sale_alias_sub                    varchar(32)     Sub alias , only if exists.
psms_sale_track                        varchar(32)     Tracking parameter, only if exists.
psms_sale_cycle_type                   int(2)          type of the cycle sales ( see payment method doc )
psms_sale_cycle_time                   int(3)          Max time in minutes to complete the sale cycle.
psms_sale_simulated                    Enum(Y , N)     Y, if the transaction is generated with the simulator tool.
                                                       Y, If the Sale is redirected from a unassigned ALIAS, only
psms_sale_redirected                   Enum(Y , N)
                                                       used in exclusive short codes.
psms_cmp_alias_product_value int(11)                   Virtual value defined for the Alias (optional).
psms_cmp_alias_product_name varchar(64)                Name of the product defined for the Alias (optional).




                 MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                  Last Revision. 19/07/2010




Error control process
The MobiAdvanced’s Platform has an advanced control of errors, you can also consult these errors
on a log system.

There are two types of possible incidents.



1. Error type
The transaction can’t be completed correctly, the motive is defined in the log system.



Some of the possible causes:


  1. The URL defined in the configuration, is not responding or is responding an incorrect
     HTTP code.

  2. The configuration of the response or content are incorrect.

  3. The necessary MT’s have not been completed before the sale cycle time is finished.

  4. The HTTP request is slow and takes more than 10 seconds.




These kind of errors are saved in the log system that is available in the control panel of this tool.



The next process is started at the moment that the error is produced.


  1. The request is executed again after 1 minute.

  2. If the problem persists, the request will bi executed each minute until the sale cycle time is
     finished.

  3. After reaching the last attempt, the transaction will be responded with the error MT by
     default set in the control panel.

  4. The technical contact defined in MobiAdvanced will be notified with this error via Email.




               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                  Last Revision. 19/07/2010



2. Warning ( alerts )
These kind of alerts are generated when the request was not totally correct, but was completed.




Some cases of warnings:


 1. The text was too long and was truncated.

 2. Some chars has been replaced with a similar or approximated in the GSM 3.38 charset.

 3. Some chars have been deleted because they are out of 3.38 GSM charset.


These kind of warnings are not notified via email, but they are saved in the log system of the tool. If
logs accumulate a large quantity of warnings then the technical contact will be notified.




               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                  Last Revision. 19/07/2010




Content in HTTP response

If you are using the model of integration “Content in HTTP response” you can set the content and
type of MT’s necessary for the transaction. You can define multiple MT’s in the same request,
following a pattern that is explained below for each type of configuration.

This model of integration allows three types of languages and/or standers of communication like
PLAIN TEXT, JSON and XML. You can select the method used for the content response in the
control panel of the tool. In any case JSON method is the recommended option and less prone to
failure.

This model of integration “Content in HTTP response” has some systems of “status” and “error”
control:

Error control: In a situation that you need to force an error, you can defined it in the response
content. This error and its message will be saved in the log system of the tool and the request will
be executed after 1 minute. For example: this can be useful if you are doing some temporary
maintenance. Another useful example: if your response depends on your DB and this is down at
the moment.

In every method “JSON, XML or PLAIN TEXT” you have to set a HTTP code header with 503 to
set an error.

Status control requests: In the STATUS request, the parameter “__method” => “check_status”
will be sent through GET or POST. If you receive this parameter, you have to respond to the
request with the “STATUS” message, that is explained in the examples below.

As a technical detail, you must know that is not possible to combine the MT’s responses with the
model “Content in HTTP response” and “Responses through API”.




               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                  Last Revision. 19/07/2010



TEXT PLAIN response model.
In the model of plain text, not being a markup language, it requires a set of rules, to separate each
MT element and their specifications.

To separate each SMS-MT element, we used “\n---\n”, with out the quotation marks, being “\n” as a
new line “invisible chars”. In the last definition it’s not necessary to add the separator “\n---\n” at the
end ( see examples ).

To separate the values of each SMS-MT, we used “;\n”, with out the quotation marks, being “\n” as
a new line “invisible chars”. In the last value definition it’s not necessary to add the separator “\n---
\n” at the end ( see examples ).

In a situation that you need use this exact sequence of chars in some value, you can “scape” its
function, adding a backslash “\” before the sequence.

On each request you can set 3 types of SMS-MT, a MT-service “mt_service”, a MT-Optin
“mt_optin” and a MT-Extra “mt_extra”, it’s possible that MT-optin or MT-extra are not available, that
depends of the method payment used.

We recommend that you use or look at the examples and the SDK, Where some functions are
already created for managing the requests.

It’s necessary that you define the mime type. In your HTTP set a header “content-type: text/plain”.
The charset encoding must be UTF-8. Do not put any HTML tag in the response.



Scheme of response for each MT.


  type_of_mt;
  type_of_SMS;
  SMS_content


Below there is a series of examples and formats to follow when defining MTs. In the PLAIN TEXT
model, you have to follow the order of the values of each MT. if you define more than one MT, the
order of these doesn't matter.



Example: force a “ERROR”.

Don’t forget set a HTTP CODE 503 header.


  none;
  ERROR;
  This message will be saved in the log of the tool




               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                  Last Revision. 19/07/2010



Example: “STATUS” response.

Where 1279098293 you have to put the actual unix_timestamp value set in your server, this helps
us, to detect the difference between time zones.


 none;
 STATUS;
 1279098293

Example: MT service - SMS_TEXT.

 mt_service;
 SMS_TEXT;
 Thanks for your purchase your code is: K97973


Example: MT service - SMS_WAP.


 mt_service;
 SMS_WAP;
 http://wap.domain.com/wap_content?id=2982982;
 Follow this link to download your content.


Example: MT service - SMS_UCS2.


 mt_service;
 SMS_UCS2;
                    K97973

Example: MT service - SMS_FLASH.


 mt_service;
 SMS_FLASH;
 This SMS is show on the screen device directly

Example: MT service - SMS_UDH.

This example only shows the order to follow, the values have to be in Hexadecimal.


 mt_service;
 SMS_UDH;
 {DSC};
 {UDH};
 {DATA}




               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                  Last Revision. 19/07/2010



Example: Multiple MTs in the same request.

 mt_service;
 SMS_TEXT;
 Your access code is: K397389
 ---
 mt_optin;
 SMS_TEXT;
 This service is offered by MobiAdvanced, the total cost is…
 ---
 mt_extra;
 SMS_TEXT;
 Remember if you purchase again, you will get a free code!


Example 2: Multiple MTs in the same request.


 mt_service;
 SMS_WAP;
 http://wap.domain.com/wap_content?id=2982982;
 Your access code is: K397389
 ---
 mt_extra;
 SMS_TEXT;
 Remember if you purchase again, you will get a free code!




               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                  Last Revision. 19/07/2010



JSON response model.
On each request you can set 3 types of SMS-MT, a MT-service “mt_service”, a MT-Optin
“mt_optin” and a MT-Extra “mt_extra”, is possible that MT-optin or MT-extra are not available, that
depends of the method payment used.

It’s necessary that you define the mime type. In your HTTP set a header “content-type: application/
json”.

Following JSON standers, the non ASCII chars must be encoded with scape USC2. If you are
using native functions or libraries in your programming language it’s probable that you don’t have
to worry about this.

We recommend that you use or look at the examples and the SDK, Where some functions are
already created for managing the requests.



Scheme of response for each MT.

 {
         "type_of_mt":
         {
                "psms_sale_mt_type":"{TYPE OF SMS}",
                "psms_sale_mt_data":"{RESPONSE DATA}",
                "psms_sale_mt_url":"{URL DATA * if is SMS_WAP}",
                "psms_sale_mt_udh":"{UDH DATA *if is s SMS_UDH}",
                "psms_sale_mt_dsc":"{DSC DATA *if is SMS_UDH}",
                "psms_sale_mt_dsc":"{DSC DATA *if is SMS_UDH}",
                "status_time":"{UNIX TIMESTAMP *if is STATUS request}",
                "psms_sale_error_msn":"{ERROR MESSAGE * if is error}",
         }
 }

Below there is a series of examples and formats to follow when defining MTs. In JSON you don’t
have to follow the order of the values of each MT. if you define more than one MT, the order of
these doesn't matter.



Example: “ERROR” response.

Don’t forget set a HTTP CODE 503 header.


 {
          "none":
          {
                    "psms_sale_mt_type":"ERROR",
                    "psms_sale_error_msn":"Error message save in the log"
          }
 }




               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                  Last Revision. 19/07/2010



Example: “STATUS” control response.

Where 1279098293 you have to put the actual unix_timestamp value set in your server, this help
to us, to detect the difference between time zones.


 {
          "none":
          {
                    "psms_sale_mt_type":"STATUS",
                    "status_time":"1279098293"
          }
 }


Example: MT service - SMS_TEXT.

 {
          "mt_service":
          {
                "psms_sale_mt_type":"SMS_TEXT",
                "psms_sale_mt_data":"Your access code is: K97973"
          }
 }


Example: MT Service - SMS_WAP.


 {
          "mt_service":
          {
                "psms_sale_mt_type":"SMS_WAP",
                "psms_sale_mt_data":"Your access code is K97973",
                "psms_sale_mt_url":"http://wap.domain.com/wap_content?id=2982982;"
          }
 }


Example: MT service - SMS_UCS2.


 {

          "mt_service":
          {
                "psms_sale_mt_type":"SMS_UCS2",
                "psms_sale_mt_data":"\u7684\u8bbf\u95ee\u4ee3\u7801\u662f K32923"
          }
 }




               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                  Last Revision. 19/07/2010



Example: MT Service - SMS_FLASH.


 {

          "mt_service":
          {
                "psms_sale_mt_type":"SMS_FLASH",
                "psms_sale_mt_data":"This SMS is showed directly on the screen"
          }
 }

Example: Multiple MTs in the same request.

 {
          "mt_service":
          {
                 "psms_sale_mt_type":"SMS_TEXT",
                 "psms_sale_mt_data":"Your access code is K97973"
          },
          "mt_optin":
          {
                 "psms_sale_mt_type":"SMS_TEXT",
                 "psms_sale_mt_data":"This service is offered by MobiAdvanced…"
          },
          "mt_extra":
          {
                 "psms_sale_mt_type":"SMS_TEXT",
                 "psms_sale_mt_data":"Remember if you purchase again, you will get a …"
          }
 }




Example: Multiple MTs in the same request.


 {
          "mt_service":
          {
                 "psms_sale_mt_type":"SMS_WAP",
                 "psms_sale_mt_date":"Follow this link to…",
                 "psms_sale_mt_url":"http://wap.domain.com/wap_content?id=2982982"
          },
          "mt_extra":
          {
                 "psms_sale_mt_type":"SMS_TEXT",
                 "psms_sale_mt_data":"Remember if you purchase again, you will get a…"
          }
 }




               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                  Last Revision. 19/07/2010



XML response model
On each request you can set 3 types of SMS-MT, a MT-service “mt_service”, a MT-Optin
“mt_optin” and a MT-Extra “mt_extra”, is possible that MT-optin or MT-extra are not available, that
depends of the method payment used.

It’s necessary that you define the mime type. In your HTTP set a header “content-type: text/xml”.

Following XML standers, the tags that defines the content of the MT have to use <![CDATA
[ {content} ]]> ( see examples )

We recommend that you use or look at the examples and the SDK, Where some functions are
already created for managing the requests.



Scheme of response for each MT.

 <?xml version="1.0" encoding="UTF-8"?>
 <statements>
        <{type_of_mt}>
               <psms_sale_mt_type>{TYOE_OF_SMS}</psms_sale_mt_type>
               <psms_sale_mt_data><![CDATA[{content}]]></psms_sale_mt_data>
               <psms_sale_mt_url><![CDATA[{URL *if is SMS_WAP}]]></psms_sale_mt_url>
               <psms_sale_mt_udh>{UDH DATA*if is UDH}</psms_sale_mt_udh>
               <psms_sale_mt_dsc>{DSC DATA*if is UDH}</psms_sale_mt_udh>
               <status_time>{UNIX TIME STAMP} *if is STATUS</status_time>
               <psms_sale_error_msn>{ERROR MESSAGE*if is ERROR}</
 psms_sale_error_msn>
        </{type_of_mt}>
 </statements>

Below there is a series of examples and formats to follow when defining MTs. In XML you don’t
have to follow the order of the values of each MT. if you define more than one MT, the order of
these doesn't matter.



Example: “ERROR” response.

Don’t forget set a HTTP CODE 503 header.


 <?xml version="1.0" encoding="UTF-8"?>
 <statements>
        <none>
               <psms_sale_mt_type>ERROR</psms_sale_mt_type>
               <psms_sale_mt_data>Error message for the log … </psms_sale_mt_data>
        </none>
 </statements>




               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                  Last Revision. 19/07/2010



Example: “STATUS” control response.

Where 1279098293 you have to put the actual unix_timestamp value set in your server, this help
to us, to detect the difference between time zones.


 <?xml version="1.0" encoding="UTF-8"?>
 <statements>
        <none>
               <psms_sale_mt_type>STATUS</psms_sale_mt_type>
               <status_time>1279098293</status_time>
        </none>
 </statements>


Example: MT Service - SMS_TEXT.

 <?xml version="1.0" encoding="UTF-8"?>
 <statements>
        <mt_service>
               <psms_sale_mt_type>SMS_TEXT</psms_sale_mt_type>
               <psms_sale_mt_data><![CDATA[Your code: K97973]]></psms_sale_mt_data>
        </mt_service>
 </statements>


Example: MT Service - SMS_WAP.


 <?xml version="1.0" encoding="UTF-8"?>
 <statements>
        <mt_service>
               <psms_sale_mt_type>SMS_WAP</psms_sale_mt_type>
               <psms_sale_mt_data><![CDATA[Follow the link…]]></psms_sale_mt_data>
               <psms_sale_mt_url><![CDATA[http://www.domain…]]></psms_sale_mt_url>
        </mt_service>
 </statements>

Example: MT Service - SMS_UCS2.


 <?xml version="1.0" encoding="UTF-8"?>
 <statements>
        <mt_service>
               <psms_sale_mt_type>SMS_UCS2</psms_sale_mt_type>
               <psms_sale_mt_data><![CDATA[           K…]]></psms_sale_mt_data>
        </mt_service>
 </statements>




               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                  Last Revision. 19/07/2010



Example: MT Service - SMS_FLASH.


 <?xml version="1.0" encoding="UTF-8"?>
 <statements>
        <mt_service>
               <psms_sale_mt_type>SMS_FLASH</psms_sale_mt_type>
               <psms_sale_mt_data><![CDATA[This SMS is…]]></psms_sale_mt_data>
        </mt_service>
 </statements>

Example: Multiple MTs in the same request.

 <?xml version="1.0" encoding="UTF-8"?>
 <statements>
        <mt_service>
               <psms_sale_mt_type>SMS_TEXT</psms_sale_mt_type>
               <psms_sale_mt_data><![CDATA[Your pass: K3938]]></psms_sale_mt_data>
        </mt_service>
        <mt_optin>
               <psms_sale_mt_type>SMS_TEXT</psms_sale_mt_type>
               <psms_sale_mt_data><![CDATA[Send OK to…]]></psms_sale_mt_data>
        </mt_optin>
        <mt_extra>
               <psms_sale_mt_type>SMS_TEXT</psms_sale_mt_type>
               <psms_sale_mt_data><![CDATA[Remember if…]]></psms_sale_mt_data>
        </mt_extra>
 </statements>

Example: Multiple MTs in the same request.


 <?xml version="1.0" encoding="UTF-8"?>
 <statements>
        <mt_service>
               <psms_sale_mt_type>SMS_WAP</psms_sale_mt_type>
               <psms_sale_mt_data><![CDATA[Follow the link…]]></psms_sale_mt_data>
               <psms_sale_mt_url><![CDATA[http://www.domain…]]></psms_sale_mt_url>
        </mt_service>
        <mt_extra>
               <psms_sale_mt_type>SMS_TEXT</psms_sale_mt_type>
               <psms_sale_mt_data><![CDATA[Remember, if…]]></psms_sale_mt_data>
        </mt_extra>
 </statements>




               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                       Last Revision. 19/07/2010




MT response through API
If you selected to respond asynchronous trough API, your user should have the necessary permits,
also have an API KEY, this can be obtained in the control panel.

El MobiAdvanced’s API is based on simple HTTP requests “POST and GET”. All the data sent
should use UTF-8 encoding. You have various methods of response.

       JSON “json”, XML “xml”, PHP serialized “php-serialized”



URL pattern of API requests


 http://api.mobiadvanced.com/{tipo}/?__method={class.method}&__lang={lg}&__version={ver}

Example: API URL for JSON response


 http://api.mobiadvanced.com/json/?__method=psms_set.mt&__lang=es&__version=1.1




Method psms_set.mt
In this document we will only use the class “psms_set” and “mt” method, and its 1.1 version. You
have more information about platform API, in the specific API documents.

Args accepted in psms_set.mt method

Name                                Type            Desc
user_api_key                       char(40)        User API KEY , obligatory
id_psms_sale                       Varchar(32)     transaction ID of the sale ( obligatory )
                                                   1 = MT-service , 2 = MT-optin , 3 = MT-extra Depending on the
psms_sale_mt_type                  int(1)
                                                   selected type you have to define one or others args
psms_sale_mt_service_type          vchar(128)      Type of SMS ( see types of SMS )
psms_sale_mt_service_data          text            Content of the SMS
psms_sale_mt_service_url           vchar(255)      URL, only if it’s WAP_URL type
psms_sale_mt_service_udh           vchar(127) Hex Header definitions, used only in UDH type
psms_sale_mt_service_dsc           int(1)          1= 7bit 2=8bit 3=16bit. used only in UDH type
psms_sale_mt_optin_type            vchar(128)      Type of SMS ( see types of SMS )
psms_sale_mt_optin_data            text            Content of the SMS
psms_sale_mt_optin_url             vchar(255)      URL, only if it’s WAP_URL type
psms_sale_mt_optin_udh             vchar(127) Hex Header definitions, used only in UDH type
psms_sale_mt_optin_dsc             int(1)          1= 7bit 2=8bit 3=16bit. used only in UDH type
psms_sale_mt_extra_type            vchar(128)      Type of SMS ( see types of SMS )
psms_sale_mt_extra_data            text            Content of the SMS
psms_sale_mt_extra_url             vchar(255)      URL, only if it’s WAP_URL type
psms_sale_mt_extra_udh             vchar(127) Hex Header definitions, used only in UDH type
psms_sale_mt_extra_dsc             int(1)          1= 7bit 2=8bit 3=16bit. used only in UDH type

               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                  Last Revision. 19/07/2010



Example: setting MT_service SMS_TEXT

Don’t forget replace the user API KEY.


 POST http://api.mobiadvanced.com/json/?__method=psms_set.mt
      'user_api_key' => '4b2f64874972bbacdfc49686bc182ea915041b312,
      'id_psms_sale' => '356361234',
      'psms_sale_mt_type' => '1',
      'psms_sale_mt_service_type' => 'SMS_TEXT',
      'psms_sale_mt_service_data' => 'Your access code is K39G3'



 {
          "status":"ok",
          "code":true,
          "args":false,
          "value":null,
          "message":
          {
                  "public":"psms_set_mt_service_ok",
                  "private":"ok"
          }
 }


Example: setting MT_service SMS WAP

Don’t forget replace the user API KEY.


 POST http://api.mobiadvanced.com/json/?__method=psms_set.mt
      'user_api_key' => '4b2f64874972bbacdfc49686bc182ea915041b312',
      'id_psms_sale' => '156361234',
      'psms_sale_mt_type' => '1',
      'psms_sale_mt_service_type' => 'SMS_WAP',
      'psms_sale_mt_service_data' => 'Follow this link to download your product'
      'psms_sale_mt_service_url' => 'http://wap.example.com?wap_product=29822'



 {
          "status":"ok",
          "code":true,
          "args":false,
          "value":null,
          "message":
          {
                  "public":"psms_set_mt_service_ok",
                  "private":"ok"
          }
 }




               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                  Last Revision. 19/07/2010



Example: setting MT_optin SMS_TEXT

Don’t forget replace the user API KEY.


 POST http://api.mobiadvanced.com/json/?__method=psms_set.mt
      'user_api_key' => '4b2f64874972bbacdfc49686bc182ea915041b312',
      'id_psms_sale' => '356361234',
      'psms_sale_mt_type' => '2',
      'psms_sale_mt_service_type' => 'SMS_TEXT',
      'psms_sale_mt_service_data' => 'Send OK to confirm your purchase…'



 {
          "status":"ok",
          "code":true,
          "args":false,
          "value":null,
          "message":
          {
                  "public":"psms_set_mt_optin_ok",
                  "private":"ok"
          }
 }




               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                  Last Revision. 19/07/2010



Some examples of error responses.

You can control the status of the request looking the “status” value, this can be “ok” or “error”



1. Example


  {"status":"error",
          "message":
          {
                  "public":"This sale doesn’t expect an MT-service",
                  "private":"error"
          }
  }




2. Example

  {"status":"error",
          "message":{"public":"Some arguments are incorrect","private":"Some arguments are
  incorrect"},
          "args":{
                  "id_psms_sale":{
                         "status":"error",
                         "public":"This argument can’t be empty.",},
                  "psms_sale_mt_type":{
                         "status":"ok",
                         "public":"Correct"},
                  "psms_sale_mt_service_type":{
                         "status":"ok",
                         "public":"Correct"}
                  "psms_sale_mt_service_data":{
                         "status":"ok",
                         "public":"Correct",}
                  }
          }
  }




               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain
Integration guide for Premium SMS Gateway - v 1.1 / MobiAdvanced.com                  Last Revision. 19/07/2010




IP protection
If your have an activated firewall in your server, where your receive the request, you should allow
these IP’s


 94.23.50.192
 94.23.50.193
 94.23.50.194
 94.23.81.108
 94.23.87.35


It’s possible that due to improvement of the platform the IP’s may be modified. In case of being a
client you will be notified via email with a few weeks anticipation.




More information
If you have any doubts regarding this document or you want to inform us of any errors, please
don’t hesitate to contact us.



MobiAdvanced ( General information )

E-mail: soporte@mobiadvanced.com




Luis Muñoz - CTO ( Technical information )

E-mail: luis.munoz.hdez@mobiadvanced.com



MobiAdvanced.com




               MobiAdvanced.com is a product by Sponsorocio, S.L. CIF: B97844807 Madrid - Spain

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:24
posted:8/17/2011
language:English
pages:26