SmsCoin Instructions

**Это старая версия документа.** ----

====== Technical description of the service «Pseudo-subscription through SMS» ====== ====== 1. General ====== The principle that lies behind the activation of the service «Pseudo-subscription through SMS» by means of phone number authorization based on a unique code, is designed for those cases when no other subscription is impossible for a certain mobile carrier. This type of subscription is available for all mobile carriers of the Russian Federation, except Tele-2. ====== 2. Terminology ====== **Pseudo-subscription** — subscription based service. **Pseudo-subscription activation code** — unique set of characters that is sent to the subscriber's mobile phone in order to activate the chosen service, known as «Pseudo-subscription through SMS». **Rebill** — the payment for the service «Pseudo-subscription through SMS» is billed to the subscriber's mobile phone account upon the expiry of the current period. The duration of the current 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 “Pseudo-subscription through SMS”, he 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 agreement terms and conditions by check-marking the box 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 are entered.)), he has to enter his mobile phone number in a correspondent form and to click “Next”. - If the service is available for the entered mobile phone number, the SMS-invitation will be sent to the user. - If the service is unavailable for a specific mobile phone number or an IP-adress of the user due to balance limit exceeding, it is required to display a message about the above-mentioned error and to provide an alternative payment method((An alternative payment method is to activate the service via SMS message (paid or free of charge) sent to a short code.)). - Following the instructions described in the SMS-invitation the user replies to it. - By sending reply SMS the user pays for the service and activates it. - Upon the expiry of the current period the user receives SMS with an offer to send reply message to extend the pseudo-subscription. ====== 4. The algorithm of implementation ====== 1. The process of identifying which mobile carrier this phone number belongs to on the partner's side. 2. If the identification process has succeeded, it is necessary to perform a GET-query such as «create». The user will receive SMS-invitation in reply. Upon this additional parameters are passed in request as pseudo_sc, which generates the cost of the service (rate), pseudo_text, which generates the text for reply SMS to send it to the user, and pseudo_no_pin=1 parameter. **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 | | pseudo_sc | int | Short code which specifies subscription cost | | pseudo_text | text | Text of the SMS-invitation | | pseudo_no_pin | int | Parameter should be = 1. | | 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 limit of active subscriptions on 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 | | pseudo_enable | int | Should be 1 — allow pseudo-subscriptions for the rest of the mobile carriers only | | pseudo_force | int | 1 — allow pseudo-subscriptions for all mobile carriers | | sid | text | ID service (provided separately) | **2.2 Reply format** Generally, response from XML looks like the example given below. <file> <response> <code>0</code> <desc>code_created</desc> <extra>123</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.** By sending reply SMS the pseudo-subscription will be activated and rebill will be executed: * The script specified in Result URL is requested((An address that points out to result.php file is stated in Result URL. The address is stated in sms:transit service settings on smscoin.com/en/ )). Except for the sms:transit service parameters, described at http://smscoin.com/info/smstransit-tech/, he parameter subscription_id, a unique subscription number for predetermined phone number, is sent to the handler, and billing parameter will always be = MO. * Result URL has to return the user a correct SMS text in UTF-8 encoding according to the initial and the subsequent rebills, depending on a contract with the mobile carrier and the cost of the subscription itself. **4.** Upon the expiry of the current period the user receives SMS with an offer to send reply message to extend the pseudo-subscription. If the user reply to SMS, rebill will be carried out again and pseudo-subscription will be extended for the next period. In order to deactivate the subscription the user ignores the received message and pseudo-subscription will be cancelled. ====== 5. Scheme for pseudo-subscriptions ====== {{:en:all:screen_shot_2013-06-16_at_4.30.11_pm.png?200| Scheme for pseudo-subscriptions }}