====== Technical description of the service «Subscription through SMS» Beeline 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 subscriber's mobile phone for activation of specific service («Subscription through SMS»).
**Rebill** — the payment for the service «Subscription through SMS» is billed to 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”, user receives a 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 correspondent field and click “Next”. When doing so, he is forwarded to the “subscription creation” page (mobile carrier gateway) “Beeline”.
- On “subscription activation” page a user enters captcha and waits for SMS which contains the code.
- The subscriber enters the received code thus activating the service.
- After service activation the user is redirected to the partner's website.
====== 4. Beeline mobile carrier subscriptions – how it works ======
- The identification of subscriber's 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 upon service creation]
**2.1.2 Parameters**
^ Parameters ^ Type ^ Description ^
| command | text | Should be 'create' |
| web_aware | int | 1 – activates subscriptions option that passes to mobile carrier gateway; |
| return_url | string | Your website address where to the subscriber is redirected from a mobile carrier payment gateway upon transaction completion. |
| phone | varchar(16) | MSISDN in international format (without + or 00) |
| ip | varchar(15) | IP-address of subscriber (mobile operator requirements) |
| 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 like the example given below.
0
code_created
link*
**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 this query our server returns a temporary link* to the payment gateway that
is generated by Beeline in parameter . Since the previously
mentioned link is an HTML in its essence, it should be decrypted using this function
html_entity_decode() prior to its redirection.\\
4. An access code to your resource is generated by you based on a successful
redirection of the subscriber from Beeline payment gateway to your return_url. This
code is valid for 30 days.\\
5. When the subscriber is transferred to return_url of your website, there are two possible
options of a response to the subscriber «your subscription was created successfully»
and «error while creating a subscription»:\\
If the subscription is created successfully, the subscriber is redirected to
return_url with additional parameters (refer to the chart below)
^ Parameter ^ Description ^
| phone | Subscriber's phone number |
| subscription_id | Subscription ID (this parameter is transferred with successful creating of subscription) |
| s_id | Subscription service ID Subscription ID (this parameter is transferred with successful creating of subscription) |
| status | Can get one of two following values: 1) **reservation** – funds are reserved, not the final status, it is required to wait at the start on Status URL. 2) **error** – subscription not created, fail. |
| hash_sign | Functionality result: md5(':-:'.subscription_id.':-:'.s_id.':-:'.phone) |
**6. After the subscription is activated – daily rebills begin on next day:**
* 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 textmessage will be ignored.
**7. Sending an SMS with a word «stop» to a short code 9105**
When subscription has been stopped, we pass to Status URL parameter status=stop, and parameters subscription_id and subs_sid.
**8. Subscription activation - Beeline**
{{:en:subs1:снимок_экрана_2013-11-20_в_14.17.37.png?200|Subscription activation - Beeline}}