SmsCoin Instructions

====== Услуга смс:банк ====== ===== Общая информация ===== Услуга **смс:банк** — это инструмент для реализации принципа работы платежного шлюза, позволяющий создать полностью автоматизированный процесс приема оплаты по аналогии с распространенными платежными системами. Воспользовавшись этой услугой, владелец сетевого ресурса получает простой механизм управления поступлением средств, а пользователи - удобный альтернативный способ совершения покупок или пополнения баланса. Установка **смс:банка** требует навыков работы с PHP или каким-либо другим языком исполнения сценариев на стороне сервера. При наличии необходимого опыта процесс интеграции занимает (в зависимости от объема производимых работ) от получаса до двух часов. ===== Алгоритм работы ===== - Сетевой ресурс передает на наш шлюз оплаты [[#Форма, инициирующая транзакцию|форму]], инициирующую транзакцию. - По переданному в этой [[#Форма, инициирующая транзакцию|форме]] параметру [[#Данные, передаваемые на шлюз оплаты|s_purse]] определяется соответствующий **смс:банк**, из настроек которого считывается значение параметра **Секретный код**. - С помощью этого **Секретного кода** проверяется достоверность переданных через [[#Форма, инициирующая транзакцию|форму]] данных. Для этого вычисляется MD5-хэш строки так же, как был вычислен параметр [[#Данные, передаваемые на шлюз оплаты|s_sign]] в [[#Форма, инициирующая транзакцию|форме]]. Если вычисленное значение хэша не совпадает с [[#Данные, передаваемые на шлюз оплаты|s_sign]], то на странице нашего шлюза оплаты выдается сообщение об ошибке - "Ошибка переданных данных " - и дальнейшая работа невозможна. - Если данные из [[#Форма, инициирующая транзакцию|формы]] корректны, то в нашей системе генерируется глобальный (т.е. в пределах всех услуг **смс:банк** по всем аккаунтам) уникальный номер транзакции (s_invoice) и ее MD5-хэш (s_sign). Эти данные, наряду с переданными через [[#Форма, инициирующая транзакцию|форму]], сохраняются в БД на нашем сервере. - Далее на странице нашего шлюза оплаты генерируется форма, в которой пользователю предлагается заполнить поля выбора страны/оператора для получения инструкции по отправке SMS((Внешний вид формы для всех одинаковый)), которая включает в себя: * короткий номер, на который необходимо отправить SMS; * текст SMS, состоящий из: * префикса; * сгенерированного уникального номера транзакции. * стоимость SMS, которая в зависимости от страны может как включать, так и не включать НДС; * указание о дополнительных налогах и сборах, которые могут быть установлены в выбранной стране; * дополнительная информация: правила составления текста SMS, условия ответственности, информация о технической поддержке и пр. - Если оплата нами не получена, и пользователь на странице шлюза оплаты нажимает на "Далее", то он переходит на следующую страницу с сообщением "Ваше сообщение еще не было доставлено.". На этой странице пользователь может отказаться от оплаты, нажав "Отменить операцию", либо добавить ее в [[#Закладка на страницу шлюза оплаты|закладки]], нажав соответствующую ссылку, либо нажать "Обновить", чтобы проверить поступление оплаты на сервер smscoin. Если пользователь нажмет "Отменить операцию", то будет загружена страница, указанная в параметре **Fail URL** в Панели Управления в настройках **смс:банка**. - Отправленное пользователем сообщение через оператора (и агрегатора) поступает на наш сервер. - Согласно тексту SMS определяется соответствующая запись с данными о транзакции и проверяется: * была ли транзакция оплачена ранее; * статус оплаты сообщения, принятого оператором сотовой связи; * соответствие стоимости принятого SMS-сообщения и стоимости, установленной для транзакции, - она не должна быть оплачена по меньшему тарифу (при этом по большему допускается). - Если проверка прошла успешно, на нашем сервере в базе данных фиксируется факт оплаты, и таким образом исключается возможность повторной оплаты транзакции. - Ответ от нашего сервера ("Операция прошла успешно") передается оператору сотовой связи (через агрегатора), который отправляет его пользователю в виде ответного SMS. - Когда оплата нами получена, пользователь на странице шлюза оплаты нажимает на "Далее" и переходит на следующую страницу с сообщением "Ваше сообщение было доставлено и успешно обработано.", где после нажатия на "Продолжить" будет загружена страница, указанная в параметре **Success URL** в настройке. - Через определенное время, включающее заданное в параметре **Задержка** в Панели Управления в настройках **смс:банка**, наш сервер с помощью HTTP-запроса вызывает обработчик по URL-адресу, указанному в настройках в поле **Result URL**, и передает ему необходимые [[#Данные, передаваемые на обработчик сообщений|данные]], которые владелец сервиса обрабатывает в соответствии с реализованной у него логикой. __**Примечание.**__ Если пользователь совершит оплату через SMS, но нажмет "Отменить операцию", то обработчик **Result URL** все равно будет вызван, т.е. услуга считается оплаченной. ===== Добавление услуги и настройка ===== Добавление/настройка услуги **смс:банк** производится в Панели Управления -> Услуги -> смс:банк. После добавления услуги необходимо на сетевом ресурсе разместить клиентский код скрипта, взаимодействующий с нашим сервером и реализующий [[#Реализация услуги смс:банк|соответствующую]] логику. Чтобы подключить к аккаунту новый **смс:банк**, необходимо нажать "Добавить" и заполнить предлагаемую форму. При настройке параметров **смс:банка** следует учитывать следующие особенности: - **Название**\\ Здесь необходимо указать информацию, которая дает представление о ресурсе, принимающем оплату, например, адрес сайта. Содержимое этой строки отображается в поле "Сайт:" на нашей странице оплаты. - **Секретный код**\\ Необходим для защиты данных, передаваемых на обработчики. Задается произвольным набором символов в кодировке UTF-8 длиной, не превышающей 32 символа. - **Success URL**\\ Адрес, начинающийся с <nowiki>http://</nowiki>, куда пользователь сайта вернется с нашего шлюза оплаты, если он успешно совершил оплату и нажал кнопку "Далее". - **Fail URL**\\ Адрес, начинающийся с <nowiki>http://</nowiki>, куда пользователь сайта вернется с нашего шлюза оплаты, если он отменил оплату. - **Result URL**\\ Адрес обработчика, начинающийся с <nowiki>http://</nowiki>, на который наш сервер передает данные каждого оплаченного сообщения. - **Задержка**\\ Задержка вызова **Result URL** в минутах. Для MO-тарификации возможны ситуации, когда оператор сотовой связи спустя некоторое время отменяет оплату SMS (это связано с особенностью работы его биллинга). Если до этого момента будет вызван обработчик **Result URL**, то возникает ситуация, когда услуга предоставлена, но оплату за нее владелец не получит. Чтобы это исключить, можно установить задержку, отличную от нуля. Если за это время оператор отменит оплату SMS, то вызов обработчика **Result URL** не состоится. Тем не менее, такая ситуация может возникать не часто и, если услуга предоставляется только после вызова обработчика **Result URL** (в отличие от предоставления услуги по переходу на **Success URL**), возникают дополнительные задержки, которые могут оказаться неудобными для пользователей. Поэтому мы в большинстве случаев рекомендуем выставлять этот параметр в 0. ===== Реализация услуги смс:банк ===== Для реализации услуги **смс:банк** можно выделить как минимум три необходимые части: * [[#Форма, инициирующая транзакцию|Форма]] (одна или несколько, либо генерируемая динамически), инициирующая транзакцию. * [[#Страницы выяснения статуса платежа|Страницы выяснения статуса платежа]], на одну из которых пользователь сайта вернется с нашего шлюза оплаты в зависимости от того, совершил ли он оплату или отменил ее. Их адреса указываются в Панели Управления в настройках услуги в соответствующих параметрах **Success URL** и **Fail URL**. * [[#Обработчик сообщений|Обработчик]], на который наш сервер передает данные каждого принятого нами SMS. Адрес этого обработчика указывается в Панели Управления в настройках услуги в параметре **Result URL**. Далее подробно описаны детали реализации каждой из этих частей. ==== Форма, инициирующая транзакцию ==== В общем случае HTML-разметка формы может быть реализована следующим образом: <code> <form action="http://bank.smscoin.com/bank/" method="POST"> <!-- ОБЯЗАТЕЛЬНЫЕ ПАРАМЕТРЫ --> <input name="s_purse" type="hidden" value="<ID услуги смс:банк>" /> <input name="s_order_id" type="hidden" value="<Уникальный номер операции>" /> <input name="s_amount" type="hidden" value="<Стоимость в USD>" /> <input name="s_clear_amount" type="hidden" value="<Значение 0 или 1>" /> <input name="s_description" type="hidden" value="<Краткое описание назначения платежа>" /> <input name="s_sign" type="hidden" value="<MD5-хэш строка>" /> <input type="submit" value="<Надпись на кнопке>" /> <!-- НЕОБЯЗАТЕЛЬНЫЕ ПАРАМЕТРЫ --> <input name="s_language" type="hidden" value="<Язык интерфейса по-умолчанию>" /> <input name="s_country" type="hidden" value="<Выбранная страна по-умолчанию>" /> <input name="s_provider" type="hidden" value="<Выбранный провайдер по-умолчанию>" /> <!-- ПОЛЬЗОВАТЕЛЬСКИЕ ПАРАМЕТРЫ --> <input name="user_1" type="hidden" value="<Значение 1>" /> <input name="user_2" type="hidden" value="<Значение 2>" /> ... <input name="user_n" type="hidden" value="<Значение N>" /> </form> </code> **Установка языка интерфейса по умолчанию**\\ По умолчанию используется русский язык интерфейса. Для смены языка необходимо заменить адрес запроса в приведенном ниже коде http://bank.smscoin.com/bank/ на http://bank.smscoin.com/language/english/bank/ Вместо english можно указать любой поддерживаемый язык. Поля формы, передаваемые на шлюз оплаты, описаны ниже. === Данные, передаваемые на шлюз оплаты === ^ Параметр ^ Тип ^ Описание ^ | Обязательные параметры ||| |s_purse | int |Идентификатор услуги смс:банк | |s_order_id | int |Номер операции.\\ Произвольное число, задаваемое владельцем сетевого ресурса. В целях безопасности желательно задавать уникальным, т.е. каждая новая\\ операция должна иметь новое значение. Содержимое этого параметра отображается в поле "Номер операции:" на нашей странице оплаты | |s_amount | float |Стоимость услуги, USD.\\ Конечная стоимость для каждого пользователя сайта будет варьироваться в зависимости от действующих тарифов и условий приема\\ сообщений местными сотовыми операторами. В случае, если указанная в параметре s_amount стоимость превышает максимальный\\ доступный в той или иной стране тариф, такая страна автоматически исключается из списка стран, обслуживаемых смс:банком.\\ Соответственно, если стоимость превысит максимальный допустимый тариф по всем странам, то список стран будет пустым | |s_clear_amount | int(1) |Определяет, как параметр s_amount задает стоимость.\\ Если 0, то значение s_amount представляет собой конечную стоимость для пользователя сайта.\\ Иначе - стоимость SMS для пользователя формируется таким образом, чтобы сумма дохода, выражаемая через процент\\ (поле profit в [[agregator:rates|тарифной сетке]]) от этой стоимости, была не меньше заданной в s_amount | |s_description | char(127) |Краткое описание назначения платежа.\\ Произвольная строка в кодировке UTF-8 длиной не более 127 символов. Служит для удобства разграничения целевых платежей.\\ Содержимое этой строки отображается в поле "Описание:" на нашей странице оплаты | |s_sign | char(32) |MD5-хэш строки, состоящей из соединенных через двойное двоеточие ("::") параметров\\ s_purse, s_order_id, s_amount, s_clear_amount, s_description и secret_code (в указанном порядке),\\ где secret_code - секретный код, заданный в Панели Управления в настройках услуги в параметре **Секретный код** | | Не обязательные параметры ||| |s_language | char(32) |Язык интерфейса по-умолчанию.\\ Узнать перечень поддерживаемых языков и их кодов можно, например, на [[http://smscoin.com/demo/key/normal/|демо-странице]] услуги смс:ключ | |s_country | char(2) |Двухбуквенный код страны, выбранной по-умолчанию.\\ Узнать перечень стран и их двухбуквенные коды можно из своей [[agregator:rates|тарифной сетки]] (поле country) | |s_provider | char(16) |Код выбранного провайдера по-умолчанию.\\ Узнать перечень провайдеров и их коды можно из своей [[agregator:rates|тарифной сетки]] (поле code) | | Пользовательские параметры ||| |user_1\\ user_2\\ ...\\ user_n | |Не обязательный перечень параметров, определяемый владельцем сетевого ресурса, который будет возвращен в ответе на его сервер.\\ Суммарное ограничение размера всех пар "поле-значение" составляет 155 символов.\\ \\ __**Внимание!**__\\ Пользовательские параметры не должны начинаться с префикса s_ - его использование зарезервировано для наших внутренних нужд. | ==== Страницы выяснения статуса платежа ==== Страницы выяснения статуса платежа, указанные в Панели Управления в настройках услуги в соответствующих параметрах **Success URL** и **Fail URL**, принимают от нашего сервера следующие данные: === Данные, передаваемые на cтраницу выяснения статуса платежа === ^ Параметр ^ Тип ^ Описание ^ |s_purse | int |Идентификатор услуги смс:банк | |s_order_id | int |Номер операции.\\ Имеет то же значение, какое было в [[#Данные, передаваемые на шлюз оплаты|форме]], переданной на шлюз оплаты | |s_amount | float |Стоимость, фактически оплаченная через SMS, USD | |s_clear_amount | int(1) |Определяет, какая стоимость содержится в s_amount.\\ Если 0, то значение s_amount представляет собой конечную стоимость SMS. Иначе - чистый доход,\\ т.е. процент (поле profit в [[agregator:rates|тарифной сетке]]) от общей стоимости SMS | |s_status | int(1) |Статус платежа: 1 - прошел, 0 - не прошел | |s_sign | char(32) |MD5-хэш строки, состоящей из соединенных через двойное двоеточие ("::") параметров\\ secret_code, s_purse, s_order_id, s_amount, s_clear_amount и s_status (в указанном порядке),\\ где secret_code - секретный код, заданный в Панели Управления в настройках услуги в параметре **Секретный код** | | Пользовательские параметры ||| |user_1\\ user_2\\ ...\\ user_n ||Пользовательские параметры, переданные на шлюз оплаты | В подавляющем большинстве случаев параметры **Success URL** и **Fail URL** ссылаются по одному и тому же адресу. Пример реализации такого случая приведен ниже. === Пример PHP-скрипта cтраницы выяснения статуса платежа === <code> <?php // ПРЕДВАРИТЕЛЬНЫЙ КОД // the function returns an MD5 of parameters passed // функция возвращает MD5 переданных ей параметров function ref_sign() { $params = func_get_args(); $prehash = implode("::", $params); return md5($prehash); } // filtering junk off acquired parameters // парсим полученные параметры на предмет мусора foreach($_REQUEST as $request_key => $request_value) { $_REQUEST[$request_key] = substr(strip_tags(trim($request_value)), 0, 250); } // collecting required data // собираем необходимые данные $purse = $_REQUEST["s_purse"]; $order_id = $_REQUEST["s_order_id"]; $amount = $_REQUEST["s_amount"]; $clear_amount = $_REQUEST["s_clear_amount"]; $status = $_REQUEST["s_status"]; $sign = $_REQUEST["s_sign"]; // users data // пользовательские данные $user_1 = $_REQUEST["user_1"]; $user_2 = $_REQUEST["user_2"]; ... $user_n = $_REQUEST["user_n"]; // making the reference signature // создаем эталонную подпись $reference = ref_sign($secret_code, $purse, $order_id, $amount, $clear_amount, $status) // validating the signature // проверяем, верна ли подпись if($sign == $reference) { // success, proceeding // обрабатываем полученные данные if ($status == '1') { // The operation has succeeded // Операция прошла успешно } else { // The operation has been canсelled // Операция была отменена } } else { // failure, reporting error // неправильно составлен запрос } // ЗАВЕРШАЮЩИЙ КОД ?> </code> ==== Обработчик сообщений ==== Обработчик сообщений, указанный в Панели Управления в настройках услуги в параметре **Result URL**, принимает от нашего сервера следующие данные: === Данные, передаваемые на обработчик сообщений === ^ Параметр ^ Тип ^ Описание ^ |s_purse | int |Идентификатор услуги смс:банк | |s_order_id | int |Номер операции.\\ Имеет то же значение, какое было в [[#Данные, передаваемые на шлюз оплаты|форме]], переданной на шлюз оплаты | |s_amount | float |Стоимость, фактически оплаченная через SMS, USD | |s_clear_amount | int(1) |Определяет, какая стоимость содержится в s_amount.\\ Если 0, то значение s_amount представляет собой конечную стоимость SMS. Иначе - чистый доход,\\ т.е. процент (поле profit в [[agregator:rates|тарифной сетке]]) от общей стоимости SMS | |s_inv | int |Уникальный номер транзакции в нашей системе | |s_phone | char(32) |Номер телефона, с которого была отправлена SMS | |s_sign_v2 | char(32) |MD5-хэш строки, состоящей из соединенных через двойное двоеточие ("::") параметров\\ secret_code, s_purse, s_order_id, s_amount, s_clear_amount, s_inv и s_phone (в указанном порядке),\\ где secret_code - секретный код, заданный в Панели Управления в настройках услуги в параметре **Секретный код** | | Пользовательские параметры ||| |user_1\\ user_2\\ ...\\ user_n ||Пользовательские параметры, переданные на шлюз оплаты | === Пример PHP-скрипта обработчика сообщений === <code> <?php // ПРЕДВАРИТЕЛЬНЫЙ КОД // the function returns an MD5 of parameters passed // функция возвращает MD5 переданных ей параметров function ref_sign() { $params = func_get_args(); $prehash = implode("::", $params); return md5($prehash); } // filtering junk off acquired parameters // парсим полученные параметры на предмет мусора foreach($_REQUEST as $request_key => $request_value) { $_REQUEST[$request_key] = substr(strip_tags(trim($request_value)), 0, 250); } $purse = $_REQUEST["s_purse"]; $order_id = $_REQUEST["s_order_id"]; $amount = $_REQUEST["s_amount"]; $clear_amount = $_REQUEST["s_clear_amount"]; $inv = $_REQUEST["s_inv"]; $phone = $_REQUEST["s_phone"]; $sign = $_REQUEST["s_sign_v2"]; // users data // пользовательские данные $user_1 = $_REQUEST["user_1"]; $user_2 = $_REQUEST["user_2"]; ... $user_n = $_REQUEST["user_n"]; // making the reference signature // создаем эталонную подпись $reference = ref_sign($secret_code, $purse, $order_id, $amount, $clear_amount, $inv, $phone); // validating the signature // проверяем, верна ли подпись if($sign == $reference) { // success, proceeding // обрабатываем полученные данные if ($status == '1') { // The operation has succeeded // Операция прошла успешно } else { // The operation has been canсelled // Операция была отменена } } else { // failure, reporting error // неправильно составлен запрос } // ЗАВЕРШАЮЩИЙ КОД ?> </code> ===== Тарифная сетка ===== Тарифную сетку для услуги **смс:банк** можно получить по следующим адресам: в формате XML: http://service.smscoin.com/xml2/bank/идентификатор банка/ в формате JSON: http://service.smscoin.com/json/bank/идентификатор банка/ ===== Примеры работы и готовые скрипты ===== ==== Примеры работы ==== ^ Ссылка ^ Описание ^ |[[http://smscoin.com/demo/bank/]] |Стандартная версия | |[[http://demo.sms-payment-scripts.com/]] |Услуги, реализованные с помощью [[http://smscoin.com/software/|Библиотеки готовых скриптов]] | |[[http://demo.sms-payment-scripts.com/smsbank/]] |Версия с возможностью выбора стоимости | ==== Готовые скрипты ==== ^ Ссылка ^ Описание ^ |[[http://smscoin.com/mediabank/examples/smsbank_php.zip]] |PHP-версия стандартного скрипта | |[[http://smscoin.com/mediabank/examples/smsbank_perl.zip]] |Perl версия стандартного скрипта | |[[http://smscoin.com/mediabank/examples/smsbank_aspx.zip]] |ASP.NET версия стандартного скрипта | |[[http://smscoin.com/mediabank/examples/smsbank_python.zip]] |Python версия стандартного скрипта | |[[http://smscoin.com/mediabank/examples/smsbank_json.zip]] |PHP-версия скрипта с тарифной сеткой | |[[http://smscoin.com/mediabank/examples/smsbank_json_redirect.zip]] |PHP-версия скрипта с тарифной сеткой и автопереадресацией |