Stripe Invoicing: от черновика счёта до оплаты и корректировок
Чем отличаются draft, open и paid, когда появляется платёжная ссылка и почему письмо, попытка списания и credit note меняют счёт по-разному.
Счёт — объект с состоянием, а не только PDF
Stripe Invoicing объединяет перечень товаров или услуг, количество, стоимость и налоги с обработкой оплаты. Счёт можно создать в Dashboard или через API, связав его с существующим клиентом и продуктами либо добавив разовые позиции. Подписка также порождает счета для своих расчётных периодов, но не превращает любой разовый счёт в подписку.
Новый объект находится в состоянии draft. После подготовки его финализируют, переводя в open. Теперь счёт ожидает расчёта: Stripe может попытаться списать деньги с сохранённого метода либо дать клиенту возможность оплатить самостоятельно. Успешное завершение отражается состоянием paid; неуспешная попытка сама по себе не отменяет счёт и обычно оставляет его open.
Дополнительно предусмотрены void и uncollectible. Первый обозначает отменённый счёт, второй — сумму, которую не ожидают получить. Это разные состояния, а не два написания «ещё не оплачено».
Что меняет финализация
Финализация разрешает оплату, обеспечивает наличие номера счёта, формирует ссылку платёжной страницы и ссылку на PDF. Одновременно часть свойств становится неизменяемой. Поэтому отправка уже подготовленного документа и свободное редактирование черновика занимают разные места в процессе: после финализации нельзя исходить из того, что все суммы и данные клиента остаются обычными редактируемыми полями.
Документация связывает переходы с отдельными API-операциями и событиями. Финализация даёт invoice.finalized, отправка — invoice.sent, удачная оплата — invoice.paid, ошибка платежа — invoice.payment_failed. У события отправки конечное состояние остаётся open: сообщение клиенту ещё не означает поступления денег. У failed-платежа также нет обязательного перехода к отмене.
При автоматическом сборе существует период ожидания после обработки события создания счёта слушающими webhook-системами. Неправильный ответ внешней интеграции может задержать дальнейшие действия; поведение live-режима и sandbox различается. В такой модели работа сервиса зависит не только от содержимого PDF, но и от состояния подключённых обработчиков уведомлений. Ручная финализация в панели и вызов API предоставляют отдельные способы выполнить переход, когда счёт подготовлен.
| Исходное состояние | Действие | Результат |
|---|---|---|
| draft | Финализировать | open |
| open | Отправить клиенту | open |
| open | Успешно оплатить | paid |
| open | Неудачная оплата | open |
| open | Отменить | void |
Источник: Stripe: Transitions and endpoints
Платёжная страница и срок жизни ссылки
Hosted invoice page даёт клиенту частный URL, где видны позиции, сумма и состояние счёта. На этой странице можно выбрать разрешённый способ оплаты и скачать PDF счёта или подтверждения расчёта. Хостинг обеспечивает Stripe; продавцу не требуется создавать собственную платёжную форму только ради этого сценария.
Ссылка содержит длинный случайный идентификатор, но не является бессрочной. В документации указано истечение через тридцать дней после срока оплаты; если срока нет — через тридцать дней после финализации. Общий интервал ограничен ста двадцатью днями. Истечение URL при этом не следует путать с уничтожением самого объекта счёта.
Для просроченной ссылки предусмотрен сценарий восстановления: адресату предлагается обратиться к продавцу или получить письмо заново через механизм, связанный с ранее известным email. Для интеграций поведение PDF-ссылок также описано отдельно. На странице можно настроить фирменный цвет, логотип и значок, но набор методов оплаты задаётся собственными настройками. Наличие общего хостинга не означает, что любой возможный платёжный метод уже включён для каждого счёта, клиента и рынка.
Повторная попытка списания не равна напоминанию
В разделе Automatic collection Stripe разделяет восстановление оплаты и коммуникацию с клиентом. Smart Retries выбирает время повторных карточных попыток по динамическим сигналам, а продавец задаёт число попыток и предельный период. Для участия счёта в автоматическом процессе используется auto_advance; сама функция повторов также должна быть включена.
Это поведение не распространяется без различий на все методы. По умолчанию для многих некарточных и Direct Debit-платежей автоматические повторы отсутствуют; ACH Direct Debit выделен отдельно, а другие сценарии могут требовать соответствующего preview. Поэтому описание retry-политики карты не следует использовать как описание любого банковского перевода.
Email о неудаче и напоминание о неоплаченном счёте являются отдельными настройками. Для разовых счетов напоминания планируются до срока, в день срока либо после него. Если в момент отправки уже обрабатывается платёж, сервис может не отправлять напоминание, чтобы не дублировать запрос. Просроченный счёт также можно оставлять просроченным или по заданному правилу переводить в uncollectible. Ни одно такое состояние само по себе не сообщает, что была выполнена новая успешная транзакция.
Какие письма сопровождают расчёт
Настройки клиентских email охватывают несколько разных событий: финализацию, ошибку оплаты, необходимость подтверждения, приближение окончания срока карты, неполный расчёт, credit note и возврат. Получатель может увидеть ссылку на страницу Stripe либо на настроенную собственную страницу продавца. Эти письма выполняют разные действия, хотя внешне все относятся к одному документу или клиенту.
Для обновления способов оплаты и управления подпиской документация предусматривает либо хостируемый портал, либо собственные URL. При использовании своего адреса Stripe добавляет параметр stripe_source, обозначающий тип сообщения. Это техническая связь с контекстом письма, а не новая строка в товарной части счёта. Смешивание вариантов URL для разных типов таких писем ограничено настройками.
Разовое повторное отправление доступно через Dashboard и API. Перед отправкой в панели можно увидеть страницу счёта и открыть его PDF. Для настроенного и подтверждённого пользовательского домена письма отправляются от этого домена. Такая настройка касается происхождения сообщения, а не автоматического признания вложенного документа подходящим для любой системы бухгалтерского учёта. В интерфейсе остаются отдельные объекты: сообщение, счёт, платёжная страница и платёж.
Credit note уменьшает сумму без подмены исходного счёта
Credit note применяется к open или paid и уменьшает сумму существующего счёта. В отличие от операции, при которой старый документ отменяют и заменяют новым, исходный счёт сохраняется. В документации приведены примеры излишнего начисления, недоступной части отгрузки и согласованной скидки. Это разные причины одной технической корректировки суммы.
Уменьшение задолженности не записывает новую оплату. Однако если credit note обнуляет остаток open-счёта, состояние может стать paid. Следовательно, значение paid в системе нельзя всегда интерпретировать как новую карточную транзакцию на всю первоначальную сумму: итог мог сложиться из платежей и корректировок.
Корректировку можно связать с фиксированной суммой строки, уменьшением её количества либо отдельной пользовательской позицией. Stripe рекомендует привязку к реальным строкам для отслеживания причины изменения. Общая сумма credit notes не должна превышать сумму счёта. Для уже оплаченного документа выбирается возврат, зачисление на баланс клиента или отражение расчёта вне Stripe. Эти варианты различаются движением средств и записью в системе, хотя начинаются из одного меню Issue a credit note.
