SmsCoin Instructions

Эта страница только для чтения. Вы можете посмотреть исходный текст, но не можете его изменить. Сообщите администратору, если считаете, что это неправильно.
====== Technical description of the service "Subscription through SMS". "Megafon" 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** — a subscription-based service.

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

**Rebill** — the payment for the service "Subscription through SMS" is billed to a 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 a 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 the service agreement.
  - After a subscriber has read the service agreement, he must agree to it, enter his phone number into the corresponding field and click "Next". Then he is forwarded to the subscription creation page ("Megafon" mobile carrier gateway).
  - On the subscription creation page a subscriber enters captcha and waits for SMS with password.
  - After that a subscriber is redirected to a partner's website.
  - A subscriber activates the service by entering the received password or his phone number on a partner's website.


====== 4. The algorithm of implementation ======

1. The identification of a subscriber's connection to a certain mobile carrier is performed on a partner's side.  

2. If the identification process succeeds, it is necessary to perform «create» GET-query. In addition, it is necessary to add two parameters to “create” query:
  * web_aware=1 – activates subscriptions option with forward to a mobile carrier gateway;
  * return_url – your website URL which a subscriber is redirected to from a 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 - enable subscriptions through a mobile carrier gateway        |
| return_url    | string     | The script to which return from the payment gateway will be performed        |         
| phone    | varchar(16)     | MSISDN in the international format (without + or 00)        |
| ip    | varchar(15)     | IP address of the subscriber who entered phone number (used for protection against fraud)        |
| limit_ip    | int     | Varies from zero - subscription activation limit for one IP address. Missing - 10 by default       |
| limit_phone    | int     | Varies from zero - the limit of active subscriptions for the specified phone number. Missing - 10 by default       |
| sid    | int    | Service ID (provided separately)        |


**2.2 Reply format**

Generally, XML-response looks as the example given below.

<file>
<response>
<code>0</code>
<desc>code_created</desc>
<extra>123</extra>
</response>
</file>

**2.2.1 Possible system answers**

Generally, XML-response looks as 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 one IP is exceeded        |
| error    | 4     | too_much_subs_for_phone        | The limit of subscriptions for one phone number is exceeded        |
| error    | 3     | phone_have_active_subs_already        | There is an active subscription for this phone number        |
| error    | 2     | phone_blacklisted        | The phone number is blacklisted        |
| error    | 1     | subs_not_supported_for_provider        | Subscription is not supported by the mobile carrier        |



3. In reply to this query our server returns a temporary link* to the payment gateway that is generated by "Megafon" in parameter <extra> </extra>. Since the previously mentioned link is HTML in its essence, it should be decrypted using the 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 a subscriber from "Megafon" payment gateway to your return_url. This code is valid only for the period of active subscription. If a subscriber cancels subscription, the code shouldn't be valid.\\ 

====== 5. Redirect to return_url ======

When a subscriber is redirected to return_url of your website, there are two possible options of response «subscription was created successfully» and «error while creating subscription».

**5.1 Subscription was created successfully**

If subscription is created successfully, a subscriber is redirected to return_url with additional parameters (refer to the chart below):

^ Parameter       ^ Description        ^ 
| phone    | A 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 always equals to 'OK'     | 

After this we send an access code to a subscriber to return_url with additional parameters (refer to the chart below)

^ Parameter       ^ Description        ^ 
| phone    | A subscriber's phone number     | 
| subscription_id    | Subscription ID     | 
| subs_sid    | Subscription service ID     | 
| sign    | The result of the function: md5(':-:'.subscription_id.':-:'.s_id.':-:'.phone)     | 
| status    | This parameter equals to "start"     | 
| megafon_subs_code    | An access code generated by our system    | 

After receiving the data to your Status URL, you provide access to the website through the received access code or a phone number on the page specified in return_url.\\
status=start can be passed either at the moment of redirect to return_url or a bit later, this action depends on a mobile carrier.

**5.2 Error while creating subscription **

In this case, at the time of redirection process to return_url, two additional parameters are passed: phone and status, where status parameter always equals 1, this means that:

**1 – subscription failed **

====== 6. After the subscription has been activated, daily rebills begin: ======

The script provided in Result URL is requested. All parameters described on http://smscoin.com/info/smstransit-tech/ and subscription_id parameter are passed to the handler. Please note that billing parameter is always billing = MO.


====== 7. The instruction for canceling subscription ======

Personal code for unsubscribing is issued at the time of subscription activation on "Megafon" mobile carrier side. The format is the text «stop ID» sent to a short code 5051.
 
When subscription has been stopped, we pass parameter status=stop as well as parameters subscription_id and subs_sid to Status URL.

====== 8. Subscription activation - "Megafon" ======

{{:en:subs2:screen_shot_2014-01-31_at_17.04.39.png?200|Subscription activation - Megafon}}
SmsCoin Instructions

Инструменты пользователя

Инструменты сайта

Инструменты страницы
