Введение
Документ описывает суть сервиса мультиоплаты, механику его оказания и протокол взаимодействия в рамках электронных платежей между платформой X-BILL и ИС Партнера.
Платформа X-BILL - программно-аппаратный комплекс для обработки транзакций.
Партнер - информационная система партнера – программно-аппаратный комплекс, используемый Компанией - Партнером для подключения к Платформе X-BILL для проведения электронных платежей.
Товар - выделенная единица услуги или продукта, предоставляемая пользователю в результате оплаты.
Сервис - совокупность товаров, предоставляемых Партнером.
Транзакция - процесс оплаты товара через платформу X-BILL.
Оператор - юридическое лицо или индивидуальный предприниматель, предоставляющий услуги сотовой связи на основании соответствующих лицензий
Проект - торговая площадка зарегистрированная в платформе X-BILL
Требования
Требования к платежной странице
1.В электронном магазине должна присутствовать информация о правилах приобретения товаров (работ, услуг) — условия и сроки доставки товара/выполнения работ/оказания услуг, время приема заказов, порядок и правила возврата товаров/отказа от работ, услуг, порядок и правила возврата денежных средств и/или др.
2.Деятельность электронного магазина Поставщика должна соответствовать действующему законодательству Российской Федерации.
3.В электронном магазине обязательная должна присутствовать информация о способе списания средств, комиссии и пр.
4.На сайте продавца обязательно должна присутствовать форма обратной связи с продавцом и/или контакты для оперативной связи.
Запрещенные к обороту товары
- Наркотические, психотропные и галлюциногенные средства и вещества;
- Алкогольная продукция;
- Табачная продукция и курительные смеси;
- Азартные игры, за исключением лотерей;
- Лекарственные препараты и биологически активные добавки (БАД);
- Порнографические материалы;
- Драгоценные камни и металлы и изделия из них;
- Бывшая в употреблении косметика;
- Вредоносное программное обеспечение;
- Проституция и эскорт-услуги;
- Оружие и боеприпасы;
- Опасные и скоропортящиеся товары;
- Государственные награды и отличительные знаки;
- Удостоверения личности, дипломы и лицензии;
- Финансовые пирамиды и многоуровневый маркетинг;
- Персональные данные физических лиц;
- Товары (работы, услуги), нарушающие интеллектуальные права третьих лиц (авторское право, патентное право, право на средства индивидуализации и др.);
- Товары (работы, услуги), реализация которых в соответствии с действующим законодательством Российской Федерации возможна только при получении Предприятием специальных разрешений, сертификатов и лицензий, если Предприятие не располагает такими разрешениями, сертификатами и лицензиями;
- Другие товары (работы, услуги), нарушающие действующее законодательство Российской Федерации;
Требования к покупателю
Для абонентов Мегафон
«Мобильные платежи» доступны всем абонентам «МегаФона», за исключением юридических лиц и абонентов, обслуживающихся по кредитной системе расчетов.
- После списания суммы покупки на вашем счете должно остаться не менее 30 руб.
- Минимальная сумма единовременного платежа 1 руб.
- Максимальный разовый платеж - 5000 руб.
- Максимальная сумма платежей за сутки - 15000 руб.
- Максимальная сумма платежей за месяц – 15000 руб.
- Максимальная количество платежей за сутки - 10
- Максимальная количество платежей за неделю - 20
- Максимальная количество платежей за месяц - 50
Для абонентов Билайн
Если покупатель пользуетеся тарифом с постоплатной системой расчетов то услуга становится доступной с момента расходования вами 150 руб. за услуги связи с момента подключения к сети «Билайн».
- Услуга доступна для абонентов тарифных планов любой системы расчетов, кроме линейки тарифов «Простая логика», «Правильный», а также абонентов, у которых подключены услуги «Безлимит внутри сети» или «Безумные дни».
- Оплата возможна только со специального авансового счета.
- После списания суммы покупки на Вашем счете должно остаться не менее 50 руб.
- Услуга становится доступной с момента расходования вами 150 руб. за услуги связи с момента подключения к сети Билайн.
- Минимальная сумма платежа 10 руб.
- Максимальный разовый - 15000 руб.
- Максимальная сумма платежей за сутки - 30000 руб. Максимум 10 успешных транзакций
- Максимальная сумма платежей за месяц - 30000 руб.
Для абонентов Мтс
- Стоимость подтверждения покупки (входящая смс с номера 7663) составляет 10 рублей с НДС и взимается помимо комиссии за успешную транзакцию, вне зависимости от суммы платежа.
- Минимальная разовая сумма платежа: 10 руб.
- Максимальная разовая сумма платежа: 14 999 руб.
- При оплате услуг МТС максимальная разовая сумма платежа: 3 000 руб.
- Количество платежей в сутки не более 5 платежей
- Максимальная сумма платежей в сутки: 30 000 руб.
- Максимальная сумма платежей в месяц: 40 000 руб.
- Обязательный остаток на счете: 10 руб.
- Контракт с МТС должен быть оформлен на физическое лицо (на тарифных планах «Супер Ноль», действующем с 11.05.2011г., «Супер МТС_2011», «Супер МТС 2012» и «Супер МТС» данная услуга не предоставляется)
- Действует ограничение по незавершенным операциям (вы не можете сделать новый запрос, если предыдущий необработан)
- На номере обслуживания должны отсутствовать опции «Запрет возврата части аванса» и/или «Запрет передачи данных третьим лицам информации об абоненте»
- Невозможно использовать кредитные и бонусные средства, а также средства, начисленные по рекламным акциям, скидки, на услуги связи, предоставленные МТС, скидку на первоначальный объем услуг, предоставляемую при заключении договора (покупке комплекта) и т.п.
Для абонентов Теле2
- После списания суммы покупки на счете должно остаться не менее 20 руб.
- Cервис доступен только физическим лицам, платежи с корпоративных тарифов не разрешены.
- Невозможно использовать кредитные и бонусные средства, а также средства, начисленные по рекламным акциям, скидки, на услуги связи, предоставленные Tele2, скидку на первоначальный объем услуг, предоставляемую при заключении договора (покупке комплекта) и т.п.
- Минимальная сумма платежа: 10 руб.
- Неснижаемый остаток на лицевом счете после платежа 10 руб. (20 руб. - для абонентов Санкт-Петербурга и Ленинградской области)
- Максимальная сумма платежа 1 000 руб. - для услуг мобильной связи и Yota, 5 000 руб. - для остальных услуг и категорий
- Максимальное число платежей в сутки: 10
- Максимальное число платежей в месяц: 50
- Максимальная сумма платежей в сутки- 5 000 руб.
- Максимальная сумма платежей в месяц - 40 000 руб.
Схема взаимодействия
1.Абонент собирается оплатить услугу или товар на вашем сайте.
2.Вы отправляете запрос на наш сервер с параметрами платежа (номер телефона, сумма к списанию и др.).
3.Наша платформа направляет соответствующему оператору запрос на инициализацию мобильного платежа.
4.Оператор направляет абоненту смс-запрос на списание средств.
5.Абонент подтверждает оплату.
6.Оператор уведомляет нашу платформу об успешной оплате.
7.Наша платформа оповещает ваш обработчик об успешной оплате.
8.Деньги зачислены на ваш баланс, вы можете оказать услугу абоненту.
Описание протокола
Исходные данные
Для начала работы с платформой партнеру необходимо предоставить следующие данные:
- Адрес сайта электронного магазина;
- URL адрес обработчика для уведомления об успешных платежах;
- Краткое пояснение в счёт чего будут списываться средства;
Со стороны платформы X-BILL партнеру передаётся:
- ID проекта;
- Секретный ключ;
- Интерфейс просмотра статистики всех транзакций;
Инициализация платежа
JSON объект в теле POST запроса: https://api2.x-bill.org/?payment
| Параметр | Тип | Обязательный | Описание |
| sid | INT | | ID проекта |
| phone | STRING | | Номер телефона абонента |
| cost | FLOAT | | Сумма к оплате ( от 10 до 15 000 руб.) |
| hash | STRING | | Контрольная строка md5( sid + phone + cost + Секретный ключ ) |
| description | STRING | | Описание платежа |
| ip | STRING | | IP адрес покупателя |
| order_id | STRING | | Ваш внутренний указатель на платёж. |
| * | * | | Дополнительные параметры.
Они будут доступны в интерфейсе статистики и возвращены на ваш обработчик с сохранением ключей.
Будьте внимательны, не допустите пересечения ключей для параметров платформы X-BILL |
Для тестовой инициализации необходимо отправить параметр test со значением test.
В случае успешной инициализации запрос на обработчик будет отправлен моментально.
RESULT: { "id": 123456, "code": 0, "operator": "megafon" }
| Параметр | Тип | Обязательный | Описание |
| id | INT | | Идентификатор платежа |
| code | INT | | Код операции |
| operator | STRING | | Название оператора |
Возможные коды операций
| code | Описание |
| 0 | Платеж успешно создан и ожидает оплаты. |
| 1 | Неверное значение параметра hash |
| 2 | Неверное значение параметра sid |
| 3 | Некорректный запрос, отсутствует один или несколько обязательных параметров |
| 4 | Внутренняя ошибка обработки запроса, необходимо обратиться в техническую поддержку. |
| 5 | Запрос на инициализацию платежа не может быть принят |
| 6 | Платеж отклонен оператором (причина неизвестна) |
| 7 | Платеж отклонен оператором (ожидается подтверждение другого платежа) |
| 8 | Превышен таймаут ожидания подтверждения платежа |
| 9 | Передан некорректный идентификатор пользователя |
| 10 | Платеж отклонен оператором (абонент имеет признак - запрет возврата части аванса) |
| 11 | Платеж отклонен оператором (у абонента отсутствует разрешение на передачу персональных данных) |
| 12 | Платеж отклонен оператором (Услуга недоступна для данного источника средств) |
| 13 | Платеж отклонен оператором (Ошибка идентификации источника средств) |
| 14 | Оплата через данного оператора временно не доступна |
| 15 | Платеж отклонен оператором (причина не известна) |
| 16 | Оплату данным методом платежа невозможно провести. |
| 17 | Некорректная сумма платежа |
| 18 | Недостаточно средств для проведения платежа |
| 19 | Сумма платежа превышает допустимую сумму |
| 20 | Сумма платежа меньше минимально разрешенной |
| 21 | Некорректная валюта |
| 22 | MSISDN заблокирован |
| 23 | MSISDN внесен в черный список |
| 24 | Превышен лимит по количеству платежей за определенный период времени по данному MSISDN |
| 25 | Определение MSISDN через XBR недоступно |
| 26 | Не найден платёж с указанным идентификатором |
| 27 | Невозможно создать платёж: не заведён транзитный счёт в расчетном банке |
| 28 | Невозможно создать платёж: данный сервис неактивен (ещё не прошёл модерацию или заблокирован) |
| 29 | Не найдена компания с указанным идентификатором |
| 30 | Не корректное значение некоторых данных |
| 31 | Номер телефона указан в неверном формате (пример: 79999999999) |
| 32 | Непредвиденная ошибка в обработке запроса, срочно обратитесь в тех. поддержку. |
| 33 | Платеж не может быть создан, оператор вовремя не ответил на запрос. |
| 34 | Недопустимая операция |
Названия операторов
| operator | Название |
| megafon | Мегафон |
| beeline | Билайн |
| mts | Мтс |
| tele2 | Теле2 |
| tattelecom | Летай |
| motiv | Мотив |
| unknown(*) | Оператор не определен |
Обработчик платежа
METHOD: GET
Важно! Ваш обработчик должен ответить на запрос словом ok чтобы наша платформа поняла что вы приняли запрос успешно.
<?
// Обработка запроса
die("ok");
?>
| Параметр | Тип | Обязательный | Описание |
| order | INT | | Уникальный номер транзакции |
| phone | STRING | | Номер телефона абонента |
| order_status | INT | | Статус платежа |
| merchant_price | FLOAT | | Сумма платежа |
| paytouser | INT | | Ваш доход за вычетом комиссии оператора |
| time | INT | | Дата инициализации платежа |
| sign | STRING | | Контрольная строка md5( order + phone + merchant_price + Секретный ключ ) |
| operator | STRING | | Название оператора |
| order_id | STRING | | Ваш внутренний указатель на платеж |
| * | * | | Дополнительные параметры отправленные при инициализации платежа |
Возможные статусы платежа
| status | Описание |
| wait | Ожидает оплаты |
| success | Оплачен |
| failure | Не оплачен |
Определение оператора
GET: https://operator.x-bill.org/
| Параметр | Тип | Обязательный | Описание |
| phone | STRING | | Номер телефона |
RESULT: { "operator": "megafon", "phone": "79998887766" }
Запрос статуса платежа
JSON объект в теле POST запроса: https://api2.x-bill.org/?detail
| Параметр | Тип | Обязательный | Описание |
| id | INT | | Номер транзакции |
| user | INT | | ID пользователя |
| hash | STRING | | Контрольная строка md5( id + user + *Секретный ключ ) |
* Секретный ключ - используется от любого активного проекта.
RESULT: { "id": 1234567, "sid": 914, "phone": "79288887766", "status": 'success', "cost": 100, "income": 96.34, "operator": "megafon", "date": 11.10.2024 15:32:13, "date_pay": 11.10.2024 15:33:53, "other": {"test": "var"} }
* Если при инициализации платежа были отправлены дополнительные параметры, они так же будут отображены в RESULT
RESULT: { "id": 1234567, "code": 4 }