====== Описание интерфейса Pay-By-Click (PBC) HTTP API Версия 1.0 ====== ====== 1. Общие сведения ====== Услуга PBC - Pay By Click предназначена для тарификации абонентов с веб-сайта по клику абонента на кнопку "оплатить". Предварительно, каждый абонент должен быть "привязан" к сервису путем создания авторизационной записи.\\ \\ Тарификация не может пройти, если не создана авторизационная запись (исключения см. ниже). ====== 2. Терминология ====== **PBC** — общее название услуги. **Авторизационная запись** — запись, привязывающая данные абонента (его MSISDN) к проекту партнёра. Только при наличии авторизационной записи абонент может быть тарифицирован. Исключение - когда авторизация происходит на стороне партнёра (согласовывается индивидуально). **Проект** — сущность, созданная для партнёра, к которой идёт привязка всех авторизационных записей и тарификаций (транзакций). **Транзакция** — сущность, описывающая списание/зачисление денег с/на счёта партнёра в системе. **MSISDN** — номер телефона абонента, в международном формате, без "+" в начале. Например, "98765544321" ====== 3. Общие положения ====== Все запросы к API, за исключением описанных отдельно, выполняются с помощью GET- запроса. Все параметры должны быть экранированы согласно принятым стандартам.\\ \\ Ответ сервера всегда (за исключением ошибок) представляет собой данные в формате JSON.\\ \\ В случае ошибок, сервер возвращает соответствующий HTTP-код (например, 404 в случае не найденных данных или 400 В случае неправильных параметров запроса). Текст ответа может содержать ошибки (в текстовом формате).\\ \\ В каждом запросе должны присутствовать обязательные параметры:\\ ^ Параметры ^ Тип ^ Описание ^ | project | string(64) | идентификатор проекта, например, "p_proj". Выдаётся менеджером при подключении проекта. | | project_pass word | string(64) | пароль проекта, например, "pasw123". Выдаётся менеджером при подключении проекта. | | UUID | string(32) шестнадцатеричный, без дефисов | Уникальный индетификатор авторизационной записи абонента, созданной ранее. Пример: 9cf4a539dcb449708e51339c7dcda287 | ====== 4. Авторизация абонентов ====== Перед тарификацией абонентов, их необходимо авторизировать. \\ \\ Схема авторизации абонентов (см.рисунок в конце инструкции). **4.1 Создание авторизационной записи** При создании авторизационной записи, абоненту отправляется смс с паролем, который он должен ввести на следущем этапе активации (см. ниже).\\ \\ Для создания авторизационной записи нужно вызвать следущий URL: \\ [предоставляется в момент создания сервиса] \\ \\ с параметрами (метод GET): \\ ^ Параметры ^ Тип ^ Описание ^ | project | string(64) | идентификатор проекта, например, "p_someproject" | | project_pas sword | string(64) | пароль проекта, например, "phahfaeshaCh8joh" | | msisdn | string(16) | msisdn абонента, например "798764468986" | | ip | string(32) | IP-адрес абонента, с которого он инициировал создание авторизационной записи, например, "192.168.13.66" | ** 4.1.1 Ответ сервера, в случае успеха (формат JSON): ** {{{ { "auth_id": UUID } }}} **4.2 Получение информации об авторизационной записи** Для получения информации об авторизационной записи (например, проверка периода действия), нужно вызвать URL:\\ \\ [предоставляется в момент создания сервиса]\\ с следующими параметрами:\\ \\ \\ ^ Параметры ^ Тип ^ Описание ^ | UUID | string(32) шестнадцатери чный, без дефисов | Уникальный индетификатор авторизационной записи абонента, созданной ранее. Пример: 9cf4a539dcb449708e51339c7dcda287 | ** 4.2.1 Ответ сервера, в случае успеха (формат JSON): ** {{{ { "active": true, "auth_id": "389eb6cd59774e869a79dd2b5ddc70e3", "create_date": "2012-09-09T17:35:30.705322", "expire_date": "2012-10-09T17:35:30.705322", "msisdn": "987654321" } }}} Поля ответа: ^ Параметры ^ Тип ^ Описание ^ | active | boolean | флаг активности авторизационной записи абонента. Абонента можно биллить только пока авторизационная запись активна. | | auth_id | UUID | идентификатор авторизационной записи абонента | | create_date | iso8601 | дата создания авторизационной записи в стандарте ISO-8601 | | expire_date | iso8601 | дата окончания действия авторизационной записи в стандарте ISO-8601 | | msisdn | string(32) | Номер абонента в международном формате без + или 00) | **4.3 Подтверждение пароля абонента** После получения паролем абонента, он вводит его на сайте партнёра, а сервис партнёра выполняет его проверку. URL\\ \\ [предоставляется в момент создания сервиса]\\ \\ с параметрами: ^ Параметры ^ Тип ^ Описание ^ | msisdn | string(32) | MSISDN абонента | | ip | string(32) | IP-адрес абонента, с которого он ввёл пароль | | subscriber_p assword | string(16) | пароль, который ввёл абонент | | project | string(64) | идентификатор проекта, например, "p_someproject" | | project_pass word | string(64) | пароль проекта, например, "phahfaeshaCh8joh" | В случае успеха, сервер выдает ответ:\\ {{{ { "active": true, "auth_id": UUID } }}} Где UUID - идентификатор авторизации (используется при тарификации или для проверки авторизационной записи).\\ Активация допускается только один раз. При повторной попытке с теми же данными сервер вернёт ответ с кодом 400 и телом "Password not found or inactive". **4.4 Деавторизация абонента** Для блокировки PBC для абонента, вызывается URL:\\ \\ [предоставляется в момент создания сервиса]\\ \\ с параметрами: ^ Параметры ^ Тип ^ Описание ^ | msisdn | string(32) | MSISDN абонента | | ip | string(32) | IP-адрес абонента, с которого он потребовал отключение PBC | | reason | string(255) | текст, объясняющий отмену авторизации. Например, "требование пользователя". Необязательное поле. | | project | string(64) | идентификатор проекта, например, "p_someproject" | | project_pass word | string(64) | пароль проекта, например, "phahfaeshaCh8joh" | В случае успеха, сервер выдает ответ:\\ {{{ { "blocked": true, } }}} ====== 5. Тарификация абонентов ====== Тарификация инициируется абонентом при нажатии кнопки "тарификация" на сайте партнёра. Сайт партнёра в этот момент передает к нам запрос вида:\\ \\ [предоставляется в момент создания сервиса] \\ \\ с параметрами: ^ Параметры ^ Тип ^ Описание ^ | msisdn | string(32) | MSISDN абонента | | ip | string(32) | IP-адрес абонента, с которого он ввёл пароль | | rate | string(64) | идентификатор тарифа. Доступные идентификаторы тарифов указаны в приложении. | | price | string(16) | тоимость (в виде числа с плавающей запятой) тарифа в локальной валюте, без НДС. В запросе может быть указан либо идентификатор тарифа, либо стоимость, но не оба одновременно. | | project | string(64) | идентификатор проекта, например, "p_someproject" | | project_pass word | string(64) | пароль проекта, например, "phahfaeshaCh8joh" | | project_id | string(64) | идентификатор запроса со стороны проекта, для защиты от повторных запросов. Опционально. Идентификатор передаётся партнёру при отправке статуса оплаты (см. ниже) | В случае успеха, сервер возвращает id транзакции:\\ {{{ { "transaction_id": UUID } }}} Этот id будет использован при обработке статуса (см. ниже). ====== 6. Статус тарификации ====== После получения статуса тарификации, сервер вызывает ваш Status URL, передавая на него следующие параметры (в GET или POST-запросе): ^ Параметры ^ Тип ^ Описание ^ | project | string(64) | идентификатор проекта, к которому относится транзакция | | transaction_ id | UUID | идентификатор транзакции, полученный при тарификации | | status | enum('fail', 'ok') | статус тарификации - ''fail'' или ''ok'': 1. ok - абонент был успешно протарифицирован, ему может быть предоставлена запрошенная услуга 2. fail - тарификация не прошла по какой-либо причине. Транзакция не будет оплачена, услугу предоставлять нельзя. | | rate | string(64) | идентификатор тарифа | | operator | string(64) | код сотового оператора абонента | | cost_local | float | стоимость транзакции для абонента (в локальной валюте страны абонента) | | cost_usd | float | стоимость в USD по текущему курсу системы | | profit | float | процент заработка партнёра с этой транзакции | | msisdn | string(32) | номер телефона абонента | | project_id | string(64) | идентификатор запроса со стороны проекта, для защиты от повторных запросов. Опционально. Идентификатор передаётся партнёру при отправке статуса оплаты (см. ниже) | ====== 7. Схема услуги "Pay-By-Click" ===== {{:ru:subs8:снимок_экрана_2013-11-14_в_13.03.40.png?200|}}