Оформление подписки

Передайте один тариф в nomenclature_id или набор тарифов в nomenclature_ids. Одновременно передавать оба поля нельзя.

Параметры запроса

• nomenclature_id (integer, условно обязательно) — ID одного тарифа;
• nomenclature_ids (integer[], условно обязательно) — от 1 до 20 уникальных ID тарифов;
• autopay_consent (boolean, обязательно) — должно быть true;
• payment_method_type (string, опционально) — тип оплаты, например bank_card.

Пример запроса

{
    "nomenclature_id": 34780,
    "autopay_consent": true,
    "payment_method_type": "bank_card"
}

Ответ

{
    "order_id": 501,
    "nomenclature_id": 34780,
    "amount": "490.00",
    "currency": "RUB",
    "billing_period_months": 1,
    "payment_method_type": "bank_card",
    "payment_link": "https://yoomoney.ru/checkout/..."
}

• HTTP 201 — создан новый checkout;
• HTTP 200 — Gigma нашла такой же незавершённый checkout и вернула его повторно;
• HTTP 202 — создание платежа ещё подтверждается. В ответе нет payment_link, только message и order_id. Повторите тот же запрос через несколько секунд и не создавайте параллельный checkout.

Ошибки

• 401 — App Token или Bearer клиента отсутствует либо не распознан;
• 409 с сообщением о том, что платёж уже создаётся, — повторите тот же запрос через несколько секунд;
• другой 409 — у клиента есть несовместимый незавершённый платёж. Не повторяйте запрос автоматически: предложите завершить или отменить предыдущую оплату;
• 422 — тариф недоступен, не настроен платёжный склад, не приняты условия автосписания или платёж нельзя подготовить;
• 429 — превышен лимит 6 запросов в минуту.

Метод возвращает только подписки текущего клиента и приложения, новые сверху. Пагинации нет.

Ответ

{
    "data": [
        {
            "id": 42,
            "application_id": 17,
            "plan_slug": "nomenclature-34780",
            "nomenclature_id": 34780,
            "billing_period_months": 1,
            "amount": "490.00",
            "currency": "RUB",
            "status": "active",
            "current_period_start": "2026-08-15T10:00:00+00:00",
            "current_period_end": "2026-09-15T10:00:00+00:00",
            "next_charge_at": "2026-09-13T10:00:00+00:00",
            "saved_payment_method": {
                "id": 9,
                "payment_method_type": "bank_card",
                "card_type": "Visa",
                "card_last_4": "4242"
            },
            "latest_payment": {
                "status": "succeeded"
            },
            "latest_payment_method_change": null,
            "can_retry_payment": false,
            "retry_payment_reason": "already_paid"
        }
    ]
}

next_charge_at означает «не раньше этого времени». Фактическое списание выполняется ближайшим запуском планировщика.

Ответ содержит Cache-Control: no-store. Не сохраняйте его в браузерном или промежуточном кэше как источник актуального статуса.

Проверка оплаченного доступа

На своём backend считайте подписку действующей, только если status = "active" и current_period_end позже текущего времени. При charging, past_due или canceled доступ не выдавайте.

const accessAllowed =
	subscription.status === 'active' &&
	new Date(subscription.current_period_end).getTime() > Date.now();

latest_payment.status = "succeeded" подтверждает последнюю успешную попытку, но не заменяет проверку статуса и конца оплаченного периода.

Ошибки

• 401 — App Token или Bearer клиента отсутствует либо не распознан;
• 403 — Bearer-токен не имеет нужного права;
• 404 — клиент или токен не относится к проекту приложения.

Параметры запроса

• nomenclature_id (integer, условно обязательно) — ID тарифа;
• plan_slug (string, условно обязательно) — nomenclature-{id} вместо nomenclature_id;
• saved_payment_method_id (integer, обязательно) — активный способ оплаты этого клиента и приложения;
• autopay_consent (boolean, обязательно) — должно быть true.

Передайте хотя бы одно поле: nomenclature_id или plan_slug. Для приложения с управляемым каталогом используйте ID из каталога либо plan_slug вида nomenclature-{id}. Конфигурационные значения вроде monthly и yearly для такого приложения недоступны.

Пример запроса

{
    "nomenclature_id": 34780,
    "saved_payment_method_id": 9,
    "autopay_consent": true
}

Ответ

{
    "data": {
        "id": 42,
        "nomenclature_id": 34780,
        "amount": "490.00",
        "currency": "RUB",
        "billing_period_months": 1,
        "status": "active",
        "current_period_end": "2026-09-15T10:00:00+00:00"
    }
}

• HTTP 201 — первое списание завершилось, подписка активирована;
• HTTP 202 и status: charging — списание продолжается. Покажите обработку платежа, не выдавайте доступ и обновите список подписок позже;
• HTTP 202 и status: canceled — платёж отправлен на ручную сверку. Не запускайте бесконечный опрос и не выдавайте доступ;
• HTTP 422 — списание не прошло или данные тарифа, способа оплаты либо согласия не прошли проверку;
• HTTP 409 — предыдущий платёж ещё не завершён или требует сверки;
• HTTP 429 — превышен лимит частоты запросов.

Попытка купить тариф, по которому уже есть подписка в active, charging или past_due, возвращает 422. Это ожидаемый бизнес-сценарий: покажите существующую подписку вместо создания второй.