Процессинг оплат
Роль платежа
Платёж (Payment) — попытка списания в конкретном шлюзе на сумму счёта (с учётом валюты и настроек). У платежа есть статус жизненного цикла: создан, успех, ошибка, отмена (см. Статусы).
Создание платежа по счёту
Типовой поток API:
- Есть счёт с итоговой суммой и валютой.
- Вызывается создание платежа с привязкой к шлюзу пользователя/мерчанта.
- В транзакции создаётся запись платежа; при необходимости счёт дополняется идентификатором платежа.
- Вызывается адаптер шлюза (Stripe, YooKassa и др.) — создаётся намерение платежа у провайдера.
- Клиенту возвращаются данные для редиректа или подтверждения (зависит от шлюза и режима).
Ограничения на уровне API включают поддерживаемые фиатные валюты, обязательные поля пользователя и мерчанта.
Метаданные для webhook шлюза
Для сопоставления события шлюза с внутренним платежом в метаданные провайдера передаются, в частности:
- идентификатор платежа BillBill;
- идентификатор мерчанта.
При обработке webhook (например, Stripe) проверяется соответствие MerchantId в метаданных шлюза и мерчанта у записи шлюза, затем вызывается единая цепочка обновления платежа и счёта.
Входящие webhooks vs исходящие
| Направление | Назначение |
|---|---|
| Входящий (шлюз → BillBill) | Сообщить об успехе/ошибке оплаты, возврате |
| Исходящий (BillBill → ваш сервер) | Уведомить ваш бэкенд о смене статуса подписки, счёта, платежа и др. |
Исходящие события настраиваются в эндпоинтах вебхуков мерчанта и фильтруются по списку типов (см. События вебхуков).
Ручная оплата и отложенная авторизация
Поддерживаются сценарии manual payment / checkout: платёж создаётся, но немедленное списание может не выполняться; покупателю отправляется счёт на оплату (в т.ч. письмом). Часть шлюзов требует отдельной настройки webhook URL в кабинете мерчанта — см. Подключение шлюзов.
Упрощённая схема
Дальше: Как начать в облаке.