Сценарий оплаты через Яндекс Сплит

Схема взаимодействия покупателя, фронтенда и бэкенда магазина и API Яндекс Пэй при оплате через Сплит. Показаны четыре этапа:

1. Создание платёжной сессии и получение paymentUrl.
2. Редирект покупателя на платёжную форму и оплата.
3. Асинхронный вебхук ORDER_STATUS_UPDATED со статусом CAPTURED, основной способ узнать об оплате.
4. Резервный опрос статуса (fallback polling), если вебхук задержался.

sequenceDiagram
    autonumber
    actor User as Покупатель (Browser)
    participant FE as Фронтенд магазина
    participant BE as Бэкенд магазина
    participant YPay as API Яндекс Пэй

    rect rgba(2, 38, 110, 0.12)
        Note over User, YPay: Этап 1. Инициализация платежной сессии и получение paymentUrl
        User->>FE: Выбирает способ оплаты Яндекс Сплит и нажимает «Оформить»
        FE->>BE: Внутренний запрос: передача данных корзины
        BE->>YPay: POST /v1/orders (availablePaymentMethods: SPLIT, preferredPaymentMethod: SPLIT)
        YPay-->>BE: Response 200 OK (paymentUrl: https://pay.ya.ru/o/xxxxx)
        BE-->>FE: Передача paymentUrl
    end

    rect rgba(2, 38, 110, 0.12)
        Note over User, YPay: Этап 2. Редирект покупателя и прохождение формы Сплита
        FE->>User: Редирект на paymentUrl
        User->>YPay: Переход на платежную форму Яндекс Сплит
        User->>YPay: Выбор пользователем графика Сплита и проведение оплаты
        User->>YPay: Подтверждение оплаты первого взноса
        YPay-->>User: Редирект на merchant onSuccess URL
        User->>FE: Возврат на экран ожидания подтверждения заказа
    end

    rect rgba(2, 38, 110, 0.12)
        Note over User, YPay: Этап 3. Асинхронная доставка вебхука (основной сценарий)
        YPay->>BE: POST /v1/webhook (на Callback URL магазина), тело — JWT ES256
        Note over BE: Проверка подписи Яндекса,<br/>чтение статуса CAPTURED из тела вебхука
        BE->>BE: Обновление статуса заказа в БД → Оплачен
        BE-->>YPay: Response 200 OK (status: success)
    end

    rect rgba(2, 38, 110, 0.12)
        Note over User, YPay: Этап 4. Резервный механизм опроса (Fallback Polling)
        loop Задержка или утеря вебхука (каждые N секунд, до финального статуса или таймаута)
            FE->>BE: Запрос статуса заказа
            alt Статус в БД ещё PENDING
                BE->>YPay: GET /v1/orders/{order_id}
                YPay-->>BE: Response 200 OK (paymentStatus: PENDING или CAPTURED)
                BE->>BE: Синхронизация БД по ответу API
            end
            BE-->>FE: Текущий статус заказа
            Note over FE: PENDING — повторить опрос через N секунд,<br/>CAPTURED — выйти из цикла
        end
        FE->>User: Отображение у пользователя «Заказ успешно оплачен»
    end

Пояснения

Почему нужен резервный опрос. Вебхук асинхронный: он может прийти позже, чем покупатель вернётся на сайт, или не дойти из-за сбоя сети. Яндекс Пэй повторяет отправку до 24 часов, но покупатель не должен ждать. Поэтому страница ожидания опрашивает бэкенд, а бэкенд при необходимости сам запрашивает статус у Яндекс Пэй.

Ограничьте опрос. Задайте интервал (например, 2–3 секунды) и общий таймаут. Если статус так и не стал финальным, покажите покупателю, что оплата обрабатывается, и не создавайте заказ повторно.

Источник истины — бэкенд. Фронтенд не обращается к API Яндекс Пэй напрямую и не считает заказ оплаченным по факту редиректа на onSuccess. Статус «Оплачен» ставит только бэкенд — по проверенному вебхуку или по ответу GET /v1/orders/{order_id}.

Обработка повторов. Если вебхук пришёл после того, как статус уже обновлён опросом, бэкенд просто отвечает 200 OK — повторная обработка не нужна.