> ## Documentation Index
> Fetch the complete documentation index at: https://steamgold.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# API корзины
> Как выставить один счет сразу за несколько заказов
Корзина — это система для группировки нескольких намерений покупки (Intents) в единый заказ с общей оплатой. Система позволяет:
* Собирать несколько товаров в одну корзину
* Оплачивать все товары одним платежом
* Управлять составом корзины до момента оплаты
## Основные концепции
### Модель Корзины
Корзина представляет собой контейнер для намерений со следующими основными характеристиками:
**Статусы корзины:**
* `open` — корзина открыта для изменений
* `closed` — корзина закрыта (после оплаты или истечения времени жизненного цикла)
* `delivered` — товары доставлены
* `failed` — ошибка при обработке
**Статусы оплаты:**
* `created` — корзина создана, оплата не инициирована
* `pending` — выставлен счет, ожидается оплата
* `paid` — оплата успешно завершена
* `rejected` — оплата отклонена
* `canceled` — оплата отменена
* `refunded` — средства возвращены
* `expired` — время на оплату истекло
При [запросе корзины](/api-docs/pouch/get) возвращается полный список содержащихся в ней намерений со всей информацией по каждому.
### Особенности намерений в корзине
* **Запрет индивидуальной оплаты** — намерения, связанные с корзиной, не могут проходить через стандартный процесс чекаута. При попытке вызова `POST /(gold|items|gear)/{id}/checkout` для такого намерения возвращается ошибка.
* **Общий терминал оплаты** — все намерения в одной корзине должны использовать одинаковый платежный терминал. Это требование обеспечивает возможность создания единого счета.
* **Синхронизация статусов** — статусы намерений синхронизируются со статусом корзины:
* при оплате корзины все намерения помечаются как оплаченные;
* при отмене или истечении времени жизни корзины все намерения получают соответствующий статус;
* при изменении статуса корзины рассылаются оповещения по каждому намерению.
## Алгоритм работы
При [создании намерения](/workflow#создание-намерения) проверяется аккаунт геймера на возможность пополнения и доступность товара. В ответе на запрос содержится статус проверки намерения и его идентификатор.
Корзина может быть создана сразу при первом посещении пользователем сайта. Рекомендуется создавать корзину в момент, когда она становится необходимой.
Подробнее в соответствующем [методе создания корзины](/api-docs/pouch/create).
Используя `ID` корзины и намерения, полученные на предыдущих шагах, воспользуйтесь соответствующим [методом добавления намерения](/api-docs/pouch/add-intent), чтобы поместить намерение в корзину.
Данный этап не является обязательным, но может быть полезен для создания более отзывчивого фронтенда.
Подробнее в соответствующем [методе проверки корзины](/api-docs/pouch/verify).
Блокирует дальнейшие изменения корзины и возвращает ссылку на платежную форму.
Подробнее в соответствующем [методе выставления счета](/api-docs/pouch/checkout).
После оплаты мы обрабатываем оповещение от платежной системы и автоматически зачисляем средства на счет или отправляем покупку.
## Получение ссылки на оплату
Для получения ссылки на платежную форму воспользуйтесь методом [выставления счета за корзину](/api-docs/pouch/checkout).
```json theme={null}
{
"code": 200,
"paymentId": "b3d9f8e2-1c4e-4f5a-9f7e-2a1b0c3d4e5f",
"paymentUrl": "https://securepayments.tinkoff.ru/g0ld3Nj0y3R",
"message": "Payment initiated"
}
```
В ответе содержится ссылка на платежную форму, которую нужно передать геймеру для оплаты.
### Информация о доставки для физических товаров
Для физических товаров в данный момент доступен только один способ доставки — СДЭК.
Вам потребуется на своем сайте [установить их виджет](https://github.com/cdek-it/widget/wiki/%25D0%25A3%25D1%2581%25D1%2582%25D0%25B0%25D0%25BD%25D0%25BE%25D0%25B2%25D0%25BA%25D0%25B0-3.0) и передавать данные из него вместе с запросом чекаута корзины. Подробнее смотрите в [документации метода выставления счета](/api-docs/pouch/checkout).
Имейте в виду, что мы не занимаемся доставкой физических товаров!
## Результаты транзакции
Есть два способа узнать результат транзакции:
* **Webhook** — на ваш сервер отправляется уведомление о результате транзакции, содержащее информацию о статусе транзакции по каждому намерению. Подробнее о методе webhook можно прочитать в разделе [получение оповещений](/webhooks).
* **Проверка статуса** — вы можете отправить запрос на проверку статуса транзакции для каждого [отдельного намерения](/api-docs/gold/status) или для [корзины целиком](/api-docs/pouch/get).
## Жизненный цикл корзины
Жизненный цикл корзины отличается от [обычных намерений](/workflow#%D0%B6%D0%B8%D0%B7%D0%BD%D0%B5%D0%BD%D0%BD%D1%8B%D0%B9-%D1%86%D0%B8%D0%BA%D0%BB-%D0%BD%D0%B0%D0%BC%D0%B5%D1%80%D0%B5%D0%BD%D0%B8%D1%8F). Основное отличие в том, что старт жизненного цикла корзины запускается после выставления счета, а не после создания.
Также намерения внутри корзины перестают иметь собственный жизненный цикл и начинают зависеть от цикла корзины — в момент "протухания" корзины намерения тоже меняют свой статус на `expired`.
Корзина имеет ограниченный срок жизни — **1 час с момента выставления счета**.
Это означает:
* У пользователя есть 1 час, чтобы завершить оплату.
* По истечении времени корзина автоматически переходит в `{status: "closed", paymentStatus: "expired"}`.
А все содержащиеся в ней намерения меняют статус на `expired`, и на указанный `callbackUrl` отправляется webhook с информацией о просрочке намерения.
* Оплатить просроченную корзину невозможно — необходимо создать новую.
Если после создания корзины в течение 3 дней в нее не будут добавлены намерения, такая корзина будет удалена.