Общая информация
В системе появилась возможность принимать платежи только через одну копию биллинга, проверять и зачислять баланс на вторую и последующие копии системы.
Включение
$conf{MULTI_BILLING_SYNC} = 1;
После включения появляются новые меню:
Настройка>Финансы>Мульти-биллинг
Используется для настройки сторонних биллингов, где ищем абонента или дублируем платёж
| Поле | Описание |
|---|---|
| Название | Название стороннего сервиса, куда отправляем копию платежей и/или ищем абонента |
| Ссылка на сторонний биллинг | Указывам ссылку, по которой принимаются платежи в сторонней системе, в случае с "АСР Казна-30" - стандартная ссылка приёма платежей |
| Синхронизация | Дублирование платежи на копию биллинга (использовать только для полной копии системы) |
| Проверка пользователя (Тсходящая) | Поиск пользователя в сторонней системе, если оне не найден в основной |
| Фискализация | Фискализировать данный платёж на основном биллинге |
| Активно | Состояние сторонней системы, если стоит галочка "Активно", то использовать эту систему в поиске, иначе пропустить |
| Группы | Группы абонентов, по которым будет происходить синхронизация с полной копией системы |
| Признак поиска поиска | По какому признаку искать абонента в сторонней системе (LOGIN, CONTRACT_ID, UID) |
| Приоритет | Приоритет поиска, во время проведения платежа |
Отчёт>Финансы>Отчет по кросс-биллингу
Отчёт по финансам, выводят все платежи, которые были отправлены в другую биллинговую систему, или в любую другую систему, которая поддерживает протокол OSMP с определёнными параметрами
Настройки модуля для приема платежей на второй и последующих системах АСР "Казна-39"
Дублирование и перенос платежей делается с помощью модуля Osmp.pm.
- Добавить в платёжных системах модуль Synchron.pm - "Синхронизация"
- Указать IP адрес основного биллинга, с которого будут приходить платежи
- Указать тип платежа
- Добавить контрагентов, нужно изменить параметр PAYSYS_SYNCHRON_ACCOUNT_KEY, идентификатор нужно сделать такой же как в платежных системах основного биллинга.
- Обязательно включить добавленную систему в группу default
Описание взаимосвязи с "АСР Казна-39"
Полная инструкция по интеграции с платёжным шлюзом (Протокол Synchron)
Данная инструкция описывает протокол взаимодействия внешней платёжной системы с биллинговой системой через модуль `Synchron`. Реализация данного протокола позволит вам создать платёжный модуль на любом языке программирования (PHP, Python, Go, Java и др.), который будет восприниматься биллинговой системой как нативный.
1. Общие сведения
- Протокол передачи данных: HTTP/HTTPS
- Метод передачи параметров: GET или POST
- Формат ответа: XML
- Кодировка: UTF-8
Внешняя система отправляет HTTP-запросы на URL обработчика (обычно `.../paysys_check.cgi`).
Все ответы возвращаются в формате XML с обязательным полем `<result>`, указывающим код результата.
Структура XML-ответа
<?xml version="1.0" encoding="UTF-8"?> <response> <result>КОД_РЕЗУЛЬТАТА</result> <comment>ОПИСАНИЕ_РЕЗУЛЬТАТА</comment> <!-- Дополнительные поля --> </response>
2. Коды возврата (Result Codes)
В поле `<result>` возвращается числовой код состояния операции.
| Код | Описание (Русский) | Описание (English) | Примечание |
|---|---|---|---|
| 0 | Успешно | Success | Операция выполнена успешно |
| 1 | Временная ошибка БД | Temporary DB error | Повторите запрос позже |
| 4 | Неверный формат идентификатора | Wrong client identifier | Ошибка валидации ID абонента |
| 5 | Пользователь не найден | User not exist | Абонент с таким ID не существует |
| 6 | Неизвестный терминал | Unknown terminal | Ошибка идентификации терминала |
| 7 | Прием платежей запрещен | Payments deny | Платежи для данного абонента запрещены |
| 8 | Дубликат запроса | Double request | Транзакция с таким ID уже обрабатывается |
| 9 | Ошибка проверки подписи/ключа | Key Info mismatch | Неверный пароль или подпись (если используется) |
| 79 | Счёт абонента не активен | Account not active | Абонент отключен или удален |
| 300 | Неизвестная ошибка | Unknown error | Внутренняя ошибка сервера |
3. Описание команд (Commands)
Тип операции определяется параметром `command`.
3.1. Проверка абонента (CHECK)
Используется для проверки существования абонента перед проведением платежа.
Параметры запроса:
| Параметр | Обязательность | Описание |
|---|---|---|
| command | Да | Значение: `check` |
| account | Да | Идентификатор абонента (UID, Логин или Договор, в зависимости от настроек) |
| sum | Нет | Сумма платежа (для проверки ограничений по сумме) |
| txn_id | Да | Уникальный ID транзакции во внешней системе |
| test | Нет | Флаг тестового режима (1 - тест) |
Пример запроса:
https://billing.example.com/paysys_check.cgi?command=check&account=user123&txn_id=10001&sum=100
Пример ответа (Успех):
<?xml version="1.0" encoding="UTF-8"?> <response> <result>0</result> <fio>Иванов Иван Иванович</fio> <balance>150.00</balance> <address>ул. Ленина, д. 10, кв. 5</address> <phone>+79001234567</phone> <txn_id>10001</txn_id> <comment>Success</comment> </response>
Пример ответа (Ошибка - Абонент не найден):
<?xml version="1.0" encoding="UTF-8"?> <response> <result>5</result> <comment>User not exist</comment> </response>
3.2. Проведение платежа (PAY)
Используется для зачисления средств на счет абонента.
Параметры запроса:
| Параметр | Обязательность | Описание |
|---|---|---|
| command | Да | Значение: `pay` |
| account | Да | Идентификатор абонента |
| sum | Да | Сумма платежа (разделитель - точка) |
| txn_id | Да | Уникальный ID транзакции во внешней системе |
| txn_date | Нет | Дата транзакции в формате `YYYYMMDDHHMMSS` (например `20231025143000`) |
| servicetype | Нет | Тип услуги (1=Домофон, 2=Интернет, 3=Телефон, 4=ТВ). Используется для описания платежа. |
| test | Нет | Флаг тестового режима (1 - тест) |
Пример запроса:
https://billing.example.com/paysys_check.cgi?command=pay&account=user123&txn_id=10001&sum=100.00
Пример ответа (Успех):
<?xml version="1.0" encoding="UTF-8"?> <response> <result>0</result> <txn_id>10001</txn_id> <prv_txn>555888</prv_txn> <!-- Внутренний ID платежа в биллинге --> <sum>100.00</sum> <comment>Success</comment> </response>
3.3. Отмена платежа (CANCEL)
Используется для отмены ранее проведенного платежа.
Параметры запроса:
| Параметр | Обязательность | Описание |
|---|---|---|
| command | Да | Значение: `cancel` |
| prv_txn | Да | Внутренний ID платежа в биллинге (полученный в ответе на `pay`) |
| txn_id | Нет | ID транзакции внешней системы (для логов) |
Пример запроса:
https://billing.example.com/paysys_check.cgi?command=cancel&prv_txn=555888
Пример ответа (Успех):
<?xml version="1.0" encoding="UTF-8"?> <response> <result>0</result> <prv_txn>555888</prv_txn> <comment>Success</comment> </response>
3.4. Проверка статуса транзакции (STATUS)
Используется для проверки, прошел ли платеж с указанным ID.
Параметры запроса:
| Параметр | Обязательность | Описание |
|---|---|---|
| command | Да | Значение: `status` |
| txn_id | Да | ID транзакции внешней системы |
Пример запроса:
https://billing.example.com/paysys_check.cgi?command=status&txn_id=10001
Пример ответа (Найден):
<?xml version="1.0" encoding="UTF-8"?> <response> <result>0</result> <txn_id>10001</txn_id> <comment>Success</comment> </response>
Пример ответа (Не найден/Ошибка):
<?xml version="1.0" encoding="UTF-8"?> <response> <result>1</result> <txn_id>10001</txn_id> <comment>Temporary DB error</comment> <!-- Или другой текст ошибки --> </response>
4. Пример реализации (псевдокод)
Ниже приведен пример того, как ваша система должна формировать запросы.
4.1. Python
4.2. PHP
5. Обработка ошибок
- Если вы получили код `0`, транзакция успешна.
- Если вы получили код `1` (Временная ошибка), рекомендуется повторить запрос через некоторое время (например, через 1-5 минут).
- Если вы получили коды `4`, `5`, `6`, `7`, `9`, `79`, повтор запроса **не требуется**, так как ошибка является постоянной (неверные данные или запрет).
- Код `8` означает, что платеж уже обрабатывается или обработан. Следует проверить статус через команду `status`.
6. Важные замечания
- Уникальность `txn_id`: Каждая транзакция должна иметь уникальный ID в рамках вашей системы. Биллинг использует пару `SYSTEM_ID` + `txn_id` для предотвращения дублей.
- Формат суммы: Используйте точку как разделитель дробной части (например, `10.50`).
- Безопасность: Рекомендуется использовать HTTPS и ограничить доступ к скрипту `paysys_check.cgi` по IP-адресам ваших серверов.
Руководство по разработке сервера-эмулятора протокола Synchron
Данное руководство предназначено для разработчиков, желающих создать собственную платёжную систему или шлюз, который будет принимать запросы от основной биллинговой системы (ACP), имитируя поведение модуля `Synchron`.
В этом сценарии:
- Основная биллинговая система (Client) отправляет HTTP/HTTPS запросы на ваш сервер.
- Ваша система (Server) обрабатывает эти запросы и возвращает ответ в формате XML.
1. Общие требования
Протокол:** HTTP/HTTPS
- Метод: GET (основной) или POST
- Формат ответа: XML
- Кодировка: UTF-8
Биллинг будет обращаться к вашему скрипту (например, `https://your-system.com/api/callback`), передавая параметры в строке запроса.
2. Обработка запросов (Server Side)
Ваш сервер должен обрабатывать параметр `command`, который определяет тип операции.
2.1. Проверка пользователя (command=check)
Биллинг запрашивает информацию о пользователе перед платежом.
Входящие параметры (GET):
- `command`: `check`
- `account`: Идентификатор пользователя (Логин, UID, Договор и т.д.)
- `check_field`: (Опционально) Тип идентификатора (например, `UID`, `LOGIN`)
- `sum`: Сумма платежа (для проверки лимитов)
- `txn_id`: ID транзакции
Ожидаемый ответ (XML):
Успех (Пользователь найден):
<?xml version="1.0" encoding="UTF-8"?> <response> <result>0</result> <fio>Иванов Иван Иванович</fio> <!-- ФИО абонента --> <balance>100.00</balance> <!-- Текущий баланс --> <comment>OK</comment> </response>
Ошибка (Пользователь не найден):
<response> <result>5</result> <comment>User not found</comment> </response>
2.2. Проведение платежа (command=pay)
Биллинг уведомляет о поступлении платежа.
Входящие параметры (GET):
- `command`: `pay`
- `account`: Идентификатор пользователя
- `sum`: Сумма платежа (например, `10.50`)
- `txn_id`: ID транзакции в биллинге (External ID)
- `txn_date`: Дата транзакции (опционально)
Ожидаемый ответ (XML):
Успех:
<?xml version="1.0" encoding="UTF-8"?> <response> <result>0</result> <prv_txn>123456</prv_txn> <!-- ID платежа в ВАШЕЙ системе --> <sum>10.50</sum> <comment>Payment successful</comment> </response>
2.3. Отмена платежа (command=cancel)
Входящие параметры:
- `command`: `cancel`
- `txn_id`: ID транзакции
Ожидаемый ответ:
<response> <result>0</result> <comment>Cancelled</comment> </response>
2.4. Проверка статуса (command=status)
Входящие параметры:
- `command`: `status`
- `txn_id`: ID транзакции
Ожидаемый ответ:
<response> <result>0</result> <!-- 0 - проведен, другие коды - ошибки --> <txn_id>...</txn_id> <comment>OK</comment> </response>
3. Коды результатов (Result Codes)
Ваша система должна возвращать следующие коды в теге `<result>`:
Параметры запроса:
| Код | Значение | Описание |
|---|---|---|
| 0 | Ok | Успешная операция / Пользователь найден |
| 1 | Temp Error | Временная ошибка (БД недоступна и т.п.) |
| 5 | User Not Found | Пользователь не найден |
| 7 | Forbidden | Прием платежей запрещен |
| 300 | Unknown Error | Прочие ошибки |
4. Примеры реализации сервера
Ниже приведены примеры скриптов, которые принимают запросы от биллинга и отвечают в нужном формате.
4.1. PHP (index.php)
Разместите этот скрипт на веб-сервере (например, Nginx/Apache).
4.2. Python (Flask)
Для запуска: `pip install flask` и `python server.py`



