> ## Documentation Index > Fetch the complete documentation index at: https://docs.yume.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Карты и автосписания > Сохранённые карты компании: статусы и безопасные реквизиты, единственная активная карта, привязка/подтверждение/переключение/удаление и роль активной карты в рекуррентных списаниях по подписке. Полный перечень полей — в [глоссарии](/ru/logic/company-billing/cards-glossary). ## Что это и зачем Раздел «Карты и автосписания» отвечает за сохранённые банковские карты компании. Одна привязанная карта позволяет системе списывать платежи по подписке автоматически, без участия человека: когда наступает срок оплаты, деньги снимаются с карты через платёжный шлюз FreedomPay. Карта хранится не целиком — сам номер и данные для оплаты остаются на стороне шлюза. В системе Yume сохраняются только «указатели» на карту в шлюзе и безопасные для показа реквизиты (маскированный номер, банк, платёжная система, срок действия). Ключевое правило: **у одной компании может быть только одна активная карта**. Именно с активной карты идут все автосписания. Остальные привязанные карты хранятся, но в списаниях не участвуют, пока их не сделают активными. ## Модель данных Карта компании описывается следующими полями. | Поле | Тип | Назначение | | --------------------------- | ------------ | ----------------------------------------------------------------------------------- | | Компания | связь | Компания, которой принадлежит карта | | Активная | флаг | Карта, с которой идут списания; активной может быть только одна на компанию | | Статус | перечисление | Состояние карты в шлюзе: «В порядке», «Подтверждена» или «Удалена» | | Идентификатор карты в шлюзе | число | Внутренний номер карты во FreedomPay; уникален глобально по всей системе | | Хэш карты | текст | Маскированный номер карты, который безопасно показывать пользователю | | Токен карты | текст | Технический токен, по которому шлюз проводит операции и удаление карты | | Профиль рекуррента | текст | Идентификатор рекуррентного профиля FreedomPay, по которому проводятся автосписания | | Разрешены автосписания | флаг | По умолчанию включён; означает, что по карте разрешены рекуррентные списания | | Банк | текст | Название банка-эмитента | | Платёжная система | текст | Бренд карты (Visa, Mastercard и т.п.) | | Год окончания | текст | Год окончания срока действия карты | | Месяц окончания | текст | Месяц окончания срока действия карты | | Дата привязки | дата/время | Момент создания записи о карте | ### Инварианты уникальности У модели два ограничения целостности, которые нельзя нарушить: 1. **Одна активная карта на компанию.** База данных физически не даст сохранить вторую карту с признаком «активная» для той же компании. Поэтому перед тем как сделать карту активной, система всегда сначала снимает флаг активности со всех прочих карт этой компании. 2. **Пара «компания + маскированный номер» уникальна.** Одну и ту же карту нельзя привязать к одной компании дважды — повторная привязка обновит уже существующую запись, а не создаст дубликат. Дата привязки задаётся вручную в момент сохранения карты (берётся текущее время), а не проставляется автоматически, как у большинства других сущностей. Год и месяц окончания хранятся как текст, а не как числа или дата. ## Жизненный цикл карты Карта проходит три этапа: инициализация привязки → подтверждение шлюзом (callback) → использование и, при необходимости, удаление. ### 1. Инициализация привязки Когда пользователь хочет привязать новую карту, он обращается к разделу инициализации привязки и передаёт **ссылку возврата** — адрес, куда его нужно вернуть после того, как он введёт данные карты на форме FreedomPay. Система обращается к шлюзу с запросом на привязку карты, передавая ему идентификатор компании, ссылку возврата и служебный адрес приёма результата привязки. В ответ шлюз возвращает: * **ссылку перенаправления** — адрес формы FreedomPay, куда нужно отправить пользователя для ввода данных карты; * **идентификатор платежа** — номер операции привязки в шлюзе. Пользователя перенаправляют на эту форму. Реальные данные карты вводятся уже на стороне шлюза — система Yume их не видит и не хранит. Запрос на привязку выполняется в две попытки: сначала используется современный способ подписи запроса, и только если шлюз его не принял — система повторяет запрос по устаревшему способу. Для пользователя это незаметно. ### 2. Приём подтверждения от шлюза (callback) После того как пользователь успешно ввёл карту, FreedomPay сам обращается к системе на служебный адрес приёма привязки и присылает XML-уведомление о результате. Обработчик реагирует **только на уведомления об успешной привязке**. Любое другое уведомление отклоняется. Из уведомления берутся: идентификатор компании, идентификатор карты в шлюзе, маскированный номер, токен, профиль рекуррента, банк и срок действия. Дальше происходит следующее: 1. Если в уведомлении нет идентификатора компании или идентификатора карты — запрос отклоняется. 2. Если компания с таким идентификатором не найдена — запрос отклоняется. 3. Со всех текущих активных карт этой компании снимается признак активности. 4. Карта создаётся заново или обновляется (если карта с таким идентификатором в шлюзе уже была). Ей проставляется статус «Подтверждена» и признак «активная». 5. Администраторам уходит уведомление о привязке карты с указанием маскированного номера и банка. Обработчик приёма привязки открыт без проверки авторизации — это внешний callback от платёжного шлюза. Сам обработчик подпись уведомления не проверяет: он лишь принимает уведомления об успешной привязке и требует, чтобы в них были идентификатор существующей компании и идентификатор карты; все реквизиты карты берутся строго из данных уведомления. ### 3. Просмотр и переключение активной карты При запросе списка карт компания видит все свои привязанные карты, отсортированные от самых свежих к самым старым. Здесь работает важное «самолечение»: **если у компании есть карты, но ни одна из них не активна, система автоматически делает активной самую свежую карту**. Это гарантирует, что при наличии хотя бы одной карты автосписания всегда есть с чего проводить. Пользователь может вручную переключить активную карту. При активации другой карты система сначала снимает признак активности со всех остальных карт компании, и только потом активирует выбранную — так соблюдается правило единственной активной карты. Все остальные поля карты доступны только для чтения: через этот механизм можно менять лишь признак активности (и, технически, флаг разрешения автосписаний). Попытка «активации», где признак активности не установлен, ничего не переключает — она просто сохраняет карту как есть, не трогая другие карты компании. ### 4. Удаление карты При удалении карты система сначала обращается к шлюзу с командой удалить карту (по её токену). Запись в системе удаляется **только если шлюз подтвердил удаление** (вернул статус «удалена»). После успешного удаления: 1. Администраторам уходит уведомление об удалении карты с маскированным номером и банком. 2. Если у компании после удаления не осталось ни одной активной карты, система берёт любую из оставшихся неактивных карт и делает её активной. Если шлюз не подтвердил удаление, запись о карте в системе сохраняется — то есть карта останется в списке. Локально «осиротевшую» карту без удаления в шлюзе этот механизм не убирает. ## Роль карты в автосписаниях Активная карта — это то, с чего идут рекуррентные (повторяющиеся) списания по подписке. Когда приходит время выставить и оплатить очередной счёт, система использует профиль рекуррента активной карты, чтобы провести списание во FreedomPay без участия пользователя. Флаг «разрешены автосписания» по умолчанию включён у каждой привязанной карты. Именно связка «активная карта + разрешённый рекуррент + профиль рекуррента» делает возможным автоматическое продление подписки. Автосписание всегда идёт с той карты, которая помечена как активная в данный момент. Поэтому переключение активной карты — это и есть смена карты, с которой будет списываться следующий платёж. ## Как это используется на практике * **Первая привязка.** Пользователь запускает привязку, вводит карту на форме шлюза, шлюз присылает подтверждение — карта становится активной автоматически. Отдельно её включать не нужно. * **Несколько карт.** Компания может привязать несколько карт «про запас», но списываться будет только с активной. Смена активной карты выполняется вручную одним переключением. * **Замена карты.** Чтобы перевести автосписания на другую карту, достаточно сделать её активной — прежняя останется привязанной, но списаний с неё больше не будет. * **Отказ от карты.** Удаление снимает карту и в шлюзе, и в системе; если это была последняя активная, роль активной автоматически переходит к другой сохранённой карте. ## Связанные страницы Полный перечень полей карты, её статусов и указателей на карту в платёжном шлюзе. Обзор всего модуля компаний и биллинга и переход к его разделам. Модель компании и её домены, генерация новой компании с дефолтными данными и регистрация владельца. Счета и их позиции, расчёт суммы, инициация оплаты через FreedomPay и обработка вебхуков проверки и результата. Интеграция с FreedomPay: подпись, инициация платежа и карты, прямые операции и возвраты. Лимиты плана по ресурсам, их цены по периодам и пересчёт фактического потребления. Шаги онбординга компании, лента новостей, снапшоты системной статистики и вспомогательные фоновые задачи.