Счета и статусы

Как связать заказ со счётом и не выдать товар по промежуточному состоянию.

Счёт — платёжная попытка для одного заказа. Он хранит сумму, доступные способы оплаты, ссылку на кассу и текущее состояние платежа.

Когда создавать новый счёт

Создавайте счёт, когда покупатель подтвердил заказ и готов перейти к оплате. Для повторной попытки того же HTTP-запроса используйте прежний Idempotency-Key. Новый ключ нужен только для действительно нового счёта.

Минимальная модель заказа

Сохраните invoice.id и ключ идемпотентности рядом с заказом. Собственный идентификатор положите в metadata: он вернётся в ответах и вебхуках без изменений.

{
  "amount": { "amount": "149900", "currency": "RUB" },
  "description": "Заказ 4815162342",
  "metadata": { "orderId": "4815162342" },
  "returnUrl": "https://shop.example/orders/4815162342"
}

Жизненный цикл

Статус	Что произошло	Действие магазина
`created`	Счёт создан, оплаты ещё нет	Показать кнопку оплаты
`processing`	Платёж отправлен провайдеру	Ждать событие, товар не выдавать
`success`	Деньги подтверждены	Выдать заказ один раз
`failed`	Банк, провайдер или покупатель отклонил оплату	Предложить новую попытку
`expired`	Время оплаты закончилось	Создать новый счёт при необходимости
`refunded`	Деньги возвращены	Обновить заказ и доступ к товару
`chargeback`	Банк держателя отменил платёж	Передать заказ на ручную проверку

success разрешает выдачу, но не означает, что больше событий не будет: позже возможны refunded и chargeback.

Как проверить состояние после возврата

После returnUrl запросите GET /v1/invoices/{id} для интерфейса покупателя. Серверное бизнес-действие всё равно запускайте вебхуком: вкладка может закрыться до возврата, а сам возврат может произойти без оплаты.

Что может пойти не так

Один заказ получает два счёта из-за нового ключа на каждом retry.
Заказ помечается оплаченным по processing или по открытию returnUrl.
Поздний вебхук переводит локальный заказ назад. Храните event.id и время createdAt, не применяйте старое событие поверх нового состояния.

Следующий шаг

Выберите способы оплаты и настройте доставку событий. Поля счёта: API создания счёта.