====== Собственная платежная система/терминал API (pay api) ======

Для чего это нужно:
  * вы можете сами наладить связь между вашей платёжной системой/терминалом и биллингом;
  * можете заполнять таблицу на списание средств с пользователя (доп. услуги);
  * возвращение средств пользователю по акции (например, за покупку роутера).

При запуске обработчика Pay API, через cron или консольную команду, проводятся все платежи, у которых:
  * атрибут `status` = 0 и
  * атрибут `creation_time` меньше текущего времени сервера.

===== Описание =====

В базе данных создана таблица "addons_pay_api". Вы её заполняете, а cron проводит платежи на пополнение/списание средств с пользователя в соответствием с наполнением таблицы с частотой раз в 5 минут (зависит от настройки в cron). Также можно вызвать обработку таблицы в "ручном режиме" из админки: "Дополнительно" -> "Консольные команды" - написать "do_api_terminal_payments".
<WRAP center round alert 40%>
Мы настоятельно рекомендуем **НЕ вызывать обработчик запланированных платежей отдельно от cron**, так как это может привести к клонированию пополнений/списаний при одновременном запуске обработчика несколько раз.
</WRAP>


Добавлять записи в таблицу `addons_pay_api` необходимо со `status` = 0. Пример кода SQL запроса для добавления в таблицу:
<sxh language width classes>
INSERT INTO `addons_pay_api` (`record_id`, `transaction_id`, `misc_id`, `category`, `user_ref`, `amount`, `creation_time`, `update_time`, `status`, `comment`)
  VALUES (NULL , 1333 , '' , 28 , 162 , 20.50 , NOW() , NOW() , 0 , 'спасибо, что Вы 2 года с нами');
</sxh>

Содержимое атрибута `comment` попадёт в комментарий проведённого платежа и будет видно в Личном Кабинете.

Если атрибут `amount` положительный, то сумма будет начислена на счёт абонента, если отрицательный - будет списана со счёта.

Отчёты по "Терминал API" можно посмотреть в админке:
  * "Отчёты" -> "pay API" -> "Общий отчёт" - все транзакции, дата создания которых припадает на выбранный период;
  * "Отчёты" -> "pay API" -> "Суммарный отчёт" - суммы по всем категориям (даже тем, которых нет в справочнике) за выбранный период.

===== Структура таблицы `addons_pay_api` =====

Описание полей:
^  Атрибут      ^  Тип данных   ^  Default Value        ^  Описание  ^
| record_id     | BIGINT        |                   AI  | уникальный идентификатор платежа |
| transaction_id| BIGINT        |         0             | ссылка на платеж во внешней системе |
| misc_id       | VARCHAR(128)  |         ''            | разное, например ссылка на терминал во внешней системе|
| category      | SMALLINT      |         0             | категория платежа во внешней системе, несет чисто информационный характер, означает "за что этот платеж" |
| user_ref      | BIGINT        |                       | UID пользователя, которому должен быть зачислен платеж |
| amount        | DECIMAL(19,4) |                       | сумма платежа, положительная либо отрицательная |
| creation_time | TIMESTAMP     | 0000-00-00 00:00:00   | время, после которого платёж будет активирован |
| update_time   | TIMESTAMP     | 0000-00-00 00:00:00   | время последнего обновления статуса платежа в этой таблице |
| status        | SMALLINT      |  0                    | статус платежа |
| comment       | VARCHAR(128)  |                       | комментарий к платежу |

Если система присылает уникальный идентификатор транзакции в виде строки, а не числа, то можно использовать атрибут `misc_id` для его хранения.

===== Статусы =====

В поле `статус` отражается, в каком состоянии был пользователь, когда ему на счёт была зачислена/списана сумма.

Атрибут `status` (значение статуса платежа можно посмотреть в справочнике 'pay API статусы'):
^ Числовое значение^ Пояснение                             ^
|       0          | Ожидает обработки                     |
|       1          | Зачислен активному пользователю       |
|       2          | Зачислен замороженному пользователю   |
|       3          | Зачислен отключенному пользователю    |
|       4          | Зачислен удаленному пользователю      |
|       5          | Не обработан (пользователь не найден) |

===== Категории платежей =====

Категории платежей заполняются вручную в справочниках: 'Настройки' -> 'Справочники' -> 'pay API категории'.

ID категории может принимать значение от -32768 до 32767.

Рекомендуется использовать "отрицательные ID" для "не прибыльных" платежей, например: "возвращаем 20 грн. за покупку роутера каждый месяц".

===== Обработчик =====

Обработчик такой же, как и для всех остальных консольных команд. Добавьте вызов консольной команды "do_api_terminal_payments" в необходимый Вам скрипт, который вызывается cron'ом.
\\ [[:billing:preferences:management:console#запуск_из_косноли|]]

===== Дальнейшие планы =====

Добавить сумму категорий по следующим правилам:
  * Прибыль - суммирование по категориям, которые > 0
  * Списано - суммирование по категориям, которые < 0 и сама сумма < 0
  * Начислено - суммирование по категориям, которые < 0 и сама сумма > 0 (т.е. это не прибыль, а подарок пользователю на счёт)