Инвойсы и платежи

Полный перечень полей — в глоссарии. Эта страница описывает, как в Yume устроены счета на оплату подписки и модулей, как проходит платёж через шлюз FreedomPay, что происходит после подтверждения оплаты и как работает автоматическое (рекуррентное) продление по сохранённой карте.

​

Что такое инвойс

Инвойс (счёт на оплату) — это счёт компании на оплату подписки, модулей, интеграций или дополнительных лимитов. Каждый счёт принадлежит одной компании, оплачивается через платёжный шлюз (сейчас поддерживается только FreedomPay) и состоит из одной или нескольких позиций. Счёт хранит две группы сумм и дат: К счёту также привязана Платёжная карта — сохранённая карта компании, если она есть. Если карту позже удалят, ссылка на неё в счёте обнуляется, но сам счёт сохраняется. Сведения о способе оплаты доступны по счёту, который был оплачен, — то есть и по подтверждённому, и по возвращённому: возвращённый счёт когда-то был оплачен, и история обязана показывать, чем именно. По отклонённому счёту таких сведений нет вовсе — данные карты пишутся только на успешном ответе шлюза.

​

Статус платежа

Каждый счёт проходит по одному из четырёх состояний:

​

Позиции счёта

Каждая позиция инвойса описывает одну оплачиваемую вещь. Тип позиции определяет, что именно покупается: По смыслу позиции делятся на две группы:

• Лимитные позиции (места, точки, три вида инвентаря) — увеличивают лимиты плана компании.
• Модули и интеграции — подключают функциональность или внешний сервис на срок.

Позиция хранит количество единиц, цену, сумму (дублирует цену), а также границы своего периода. Для модулей и интеграций к позиции привязан тарифный период интеграции — выбранный тариф с ценой и длительностью.

​

Что позиция показывает в истории

Чтобы историю счетов можно было читать без расшифровки, позиция отдаёт вместе с собой:

​

Ошибки оплаты

Если платёж отклонён, к счёту привязывается Ошибка оплаты инвойса — запись с кодом и текстовым описанием причины, полученными от FreedomPay. У одного счёта может накопиться несколько таких записей (например, при нескольких неудачных попытках).

​

Расчёт суммы счёта

Прежде чем создать счёт, система рассчитывает цену каждой позиции и итог. Расчёт выполняет единое ядро, общее для оплаты из кабинета, автопродления и регистрации оплаты в админке, — поэтому предварительная оценка, сумма счёта и сумма списания всегда совпадают. Коротко о правилах:

• Модули и интеграции тарифицируются по выбранному тарифу. Новый срок пристыковывается к концу уже оплаченного (но не раньше «сейчас»), поэтому досрочное продление не сжигает остаток. Количественные тарифы (пакеты единиц вроде SMS) стоят фиксированную цену и не имеют даты окончания.
• Лимитные позиции тарифицируются по циклу компании — длительности тарифа её подписки «аренда» (1, 3, 6 или 12 месяцев; месяц, если тарифа нет). Платят только за превышение бесплатного объёма и только за прирост к уже оплаченному количеству. Увеличение в середине действующего срока доплачивается пропорционально остатку срока; уменьшение применяется сразу, бесплатно и без возврата.
• Режим «продлить всё до даты» тарифицирует всю корзину пропорционально дням до указанной даты, автоматически подбирая месячный, трёхмесячный, полугодовой или годовой прайс по фактическому сроку.
• Цена каждой позиции округляется до десятков тенге, итог счёта — сумма цен всех позиций.

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

​

Создание и оплата счёта

​

Список и создание счетов

Список счетов компании показывает все подтверждённые, отклонённые и возвращённые счета, плюс любые свежие счета за последние 3 дня (независимо от статуса). Более старые счета «в ожидании» в списке не показываются. При создании счёта:

1. Рассчитываются позиции и итоговая сумма.
2. Формируется список позиций фискального чека для передачи в шлюз.
3. К счёту привязывается активная карта компании, если она есть.
4. Если итог меньше 1 тенге — создание отклоняется с ошибкой «Сумма счёта не может быть 0 тенге».
5. Создаётся счёт, инициируется платёж во FreedomPay, сохраняются идентификатор транзакции и ссылка на оплату.
6. Создаются позиции счёта.
7. Администраторам уходит уведомление «Попытка оплаты».

​

Деталь, обновление и удаление счёта

По конкретному счёту можно получить детали, удалить его, а также запросить обновление — при обновлении система дополнительно опрашивает FreedomPay о текущем статусе платежа (синхронизация).

​

Повторная (ручная) оплата

Если счёт остался неоплаченным, можно повторно инициировать оплату — система заново формирует ссылку на оплату по существующему счёту без автосписания с карты.

​

Оплата мимо шлюза (регистрация вручную)

Если компания заплатила банковским переводом или наличными, сотрудник Yume регистрирует такую оплату из админки. Счёт при этом создаётся сразу подтверждённым: списанная сумма равна итогу, а в данных платежа сохраняется отметка о ручной регистрации, автор и комментарий. Никакого обращения к шлюзу не происходит, но провижининг срабатывает штатно — так же, как после оплаты картой. Ручные оплаты отличимы от эквайринговых везде, где показывается способ оплаты: в карточке счёта, в истории счетов клиента, в уведомлении администраторам и в счётчике «вручную» на дашборде. Сценарий работы оператора описан на странице «Расчёт стоимости и регистрация оплаты».

​

Вебхуки платежа: проверка и результат

FreedomPay обращается к двум публичным адресам (без авторизации системы): проверка платежа — можно ли оплатить этот заказ, и результат платежа — чем всё закончилось. Оба обслуживает один обработчик, который различает их по адресу вызова.

​

Проверка подписи

Прежде чем что-либо менять, обработчик проверяет подпись входящего запроса по секрету мерчанта. Запрос с неверной подписью отклоняется, никакие статусы не меняются. Ответ шлюзу тоже подписывается.

​

Предварительная проверка платежа

На запрос проверки система отвечает, можно ли оплатить заказ:

​

Результат платежа

​

Повторные и запоздавшие колбэки

Обработчик идемпотентен по уже оплаченному счёту:

• повторный успешный колбэк по подтверждённому счёту получает ответ «уже оплачен» и ничего не переписывает — провижининг не выполняется второй раз;
• колбэк об отказе не может перевести подтверждённый счёт в «Отклонён» (запоздавший отказ не отменяет успешную оплату).

​

Что происходит при подтверждении оплаты

Как только счёт переходит в статус «Подтверждён», автоматически (при сохранении счёта) срабатывают два независимых обработчика. Оба ничего не делают, если статус не «Подтверждён».

​

Провижининг лимитов, SMS и интеграций

Первый обработчик проходит по всем позициям счёта:

• Лимитная позиция — создаёт или обновляет соответствующий лимит плана компании: объём лимита ставится равным количеству из позиции, а границы лимита — периоду позиции.
• Позиция интеграции SMS — пополняет баланс SMS компании. Баланс хранится в деньгах, поэтому количество сообщений в пакете умножается на цену одного SMS для этой компании (поле «Цена SMS» на её SMS-аккаунте, по умолчанию 27 ₸). По той же цене сообщения потом и списываются, так что количество сообщений в пакете от цены не зависит.
• Любая позиция интеграции/модуля — подключает интеграцию. Берётся существующее подключение компании (приоритет у боевого, при его отсутствии — демо-подключение) и переводится в оплаченное: новый тариф, отметка «подключено», новые даты, признак демо снимается. Если подключения нет — создаётся новое. Для количественных тарифов дата окончания не ставится вовсе: такой пакет не истекает по времени.

​

Выдача пакета документов

Второй обработчик при подтверждении оплаты выдаёт пакет подписей документов для оплаченных позиций тарифа модуля электронной подписи. Уже выданные пакеты пропускаются (повторно не создаются и не суммируются). Подробнее о жизненном цикле пакетов, балансе документов и квотах: «Пакеты подписей документов».

​

Рекуррентное (автоматическое) продление

Фоновая периодическая задача продлевает подписки по сохранённым картам с включённым автосписанием. Как она работает:

1. Отбираются активные карты с включённым автосписанием, у которых есть подключённая интеграция, истекающая в течение ближайших суток.
2. Для каждой такой карты собираются действующие сейчас модули и интеграции компании (из ранее подтверждённых счетов).
3. По ним рассчитываются новые цены и периоды (та же логика расчёта — с пристыковкой к концу текущего периода).
4. Создаётся новый счёт, привязанный к карте.
5. Платёж инициируется и сразу списывается напрямую по сохранённому токену карты — без участия пользователя.
6. Создаются позиции нового счёта.

Дальше исход списания приходит обычным вебхуком, и при подтверждении срабатывает тот же провижининг, что и при ручной оплате.

​

Связанные страницы