====== Technical description of the service «Subscription through SMS» MTS mobile carrier ======


====== 1. General ======


The principle that lies behind the activation of the service «Subscription through SMS» by means of phone number authorization based on a unique code is designed for those cases when no other implementation method is available. 


====== 2. Terminology ======


**Subscription** — subscription based service.

**Subscription activation code** — unique set of characters that is sent to the
subscriber's mobile phone for activation of specific service «Subscription through SMS». 

**Rebill** —  the payment for the service «Subscription through SMS» is billed to the subscriber's mobile phone account upon the expiry of active period. The duration of active period is determined by the website owner who offers the service. 

====== 3. How it works ======


  - Prior to forwarding the user to the page where he orders the service “Subscription through SMS”, he is provided with complete information regarding the service in the form of service agreement.
  - After the subscriber has read the service agreement and agreed to it((Subscriber must give his unambiguous consent to the service terms and conditions agreement by marking the checkbox next to «I agree to the terms and conditions of the service agreement» located in the form where a mobile phone number or the password is entered.)), he has to enter his mobile phone number into the correspondent field and click “Next”. Then he is forwarded to the subscription creation page (MTS mobile carrier gateway).
  - On subscription creation page subscriber enters captcha and waits for incoming SMS with password.
  - After that subscriber is redirected to partner's website.
  - Subscriber activates the service by entering the received password on partner's site or by entering the phone number.
====== 4. MTS mobile carrier subscriptions – how it works ======


  - The identification of MSISDN connection to certain mobile carrier is performed on partner's side.  
  - If the identification process succeeded, it is necessary to perform «create_subs» GET-query. In addition it is necessary to add two parameters to “create” query:
        * web_aware=1 –  activates subscriptions option with forward to mobile carrier gateway;
        * return_url – your website URL which the subscriber is redirected to from mobile carrier payment gateway after transaction completion.

**2.1 Subscription creation**

**2.1.1 URL**\\
[provided at the moment of service creation]

**2.1.2 Parameters**


^ Parameters       ^ Type        ^ Description           ^
| command    | text     | parameter  'create' is specified        |
| web_aware    | int     | 1 — enable subscriptions through mobile carrier gateway        |
| return_url    | string     | The script to which the redirect from payment gateway is performed        |
| phone    | varchar(16)     | MSISDN in international format (without + or 00)        |
| ip    | varchar(15)     | IP-address of the subscriber who entered the phone number (used for protection against fraud)        |
| limit_ip    | int     | varies from zero - the subscription activation limit from one IP address. Missing - by default 10       |
| limit_phone    | int     | varies from zero — the limit of active subscriptions for the specified phone number. Missing — by default 10       |
| sid    | int    | ID service (provided separately)        |

**2.2 Reply format**

Generally, response from XML looks as an example given below.

<file>
<response>
<code>0</code>
<desc>code_created</desc>
<extra>link*</extra>
</response>
</file>


**2.2.1 Possible answers from the system**

Generally, response from XML looks like the example given below.


^ Type       ^ Status        ^ Description           ^ value           ^
| OK    | 0     | code_created        | The password is created        |
| error    | 6     | too_much_subs_for_ip        | The limit of subscriptions for a single IP is exceeded        |
| error    | 4     | too_much_subs_for_phone        | The limit of subscriptions for a single phone number is exceeded        |
| error    | 3     | phone_have_active_subs_already        | There is an active subscription on this phone number        |
| error    | 2     | phone_blacklisted        | The phone number is blacklisted        |
| error    | 1     | subs_not_supported_for_provider        | Subscription is not supported for mobile carrier        |

3. In reply to that query our server returns a temporary link to the payment gateway that is generated on MTS mobile carrier side in parameter  <extra> </extra>. Since the previously mentioned link contains HTML entities, it should be decrypted using this function html_entity_decode() prior to being redirected.\\ 

4. Access code to your resource is generated by our system based on successful redirection of the subscriber from MTS gateway to your return_url. This code is provided for period when subscription is active. If subscriber has cancelled activation – access code will be cancelled.\\ 

5. After the subscriber is redirected to your website return_url, there are two possible responses of subscription status: «subscription was successfully created» and «error while creating subscription».\\ 

5.1 Subscription was successfully created\\
If subscription is successfully created the subscriber is redirected to return_url with additional parameters (see the table below).	

^ Parameter       ^ Description        ^ 
| phone    | Subscriber's phone number     | 
| subscription_id    | Subscription ID    | 
| s_id    | Subscription service ID      | 
| hash_sign    | The result of the function:  md5(':-:'.subscription_id.':-:'.s_id.':-:'.phone)     | 
| status    | This parameter is always =0     | 
After that we're sending access code to subscriber, as well as status=start and and mts_subs_code = 1234 (access code generated by our system) to Status URL. After receipt of the data on your Status URL you'll provide access to the site with pair of phone number + access code.\\
status = start can be transmitted at the moment of redirecting to return url, or a little later, the action depends on the mobile carrier.

5.2 Error during the creation of subscription\\
In this case when redirection to to return_url is performed two additional parameters are passed: phone and status, where status parameter is always 1, which means:

**1** – unsuccessful subscription 
====== 6. After the subscription is activated – daily rebills begin: ======


  * A script requests a Result URL that is stated in sms:transit settings. Parameters described at http://smscoin.net/info/smstransit-tech/   and  subscription_id parameter.
  * Result URL should not return anything except status 200 OK. Any other text message will be ignored.


====== 7. Cancel your subscription. ======


The user can cancel the subscription by calling to the number * 152 * 2 # (call is free).

When subscription has been stopped, we pass to Status URL parameter status=stop, and parameters subscription_id and subs_sid.

====== 8. Subscription activation - МТS ======


{{:en:subs0:снимок_экрана_2013-11-07_в_12.44.04.png?200|Subscription activation - МТS}}