Платежи подписки

История платежей показывает каждую попытку списания: сумму, оплачиваемый период, результат и возможность ручного повтора.

Gigma сама повторяет неуспешные списания по расписанию. Ручной повтор нужен, когда клиент уже пополнил счёт или решил проблему с банком и не хочет ждать следующей автоматической попытки.

Шаг 1. Получите историю

Получение истории платежей

Метод: GET
URL: https://api.gigma.ru/api/counterparty/subscriptions/{id}/payments
Авторизация: App Token + Bearer клиента
Headers: Token: {application_token}; Authorization: Bearer {counterparty_token}
Успешный ответ: 200

Платежи возвращаются постранично, новые сверху. Запрашивайте следующие страницы по meta или links, иначе у долгоживущей подписки будет видна только часть истории.

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

page (integer, опционально) — номер страницы, начиная с 1;
per_page (integer, опционально) — от 1 до 100, по умолчанию 20.

Ответ

{
    "data": [
        {
            "id": 315,
            "subscription_id": 42,
            "order_id": 901,
            "nomenclature_id": 34780,
            "amount": "490.00",
            "currency": "RUB",
            "status": "failed",
            "period_start": "2026-09-15T10:00:00+00:00",
            "period_end": "2026-10-15T10:00:00+00:00",
            "billing_period_months": 1,
            "error_reason": "insufficient_funds",
            "can_retry": true,
            "created_at": "2026-09-13T10:05:00+00:00",
            "updated_at": "2026-09-13T10:05:10+00:00"
        }
    ],
    "links": {
        "first": "https://api.gigma.ru/api/counterparty/subscriptions/42/payments?page=1",
        "last": "https://api.gigma.ru/api/counterparty/subscriptions/42/payments?page=3",
        "prev": null,
        "next": "https://api.gigma.ru/api/counterparty/subscriptions/42/payments?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 3,
        "per_page": 20,
        "to": 20,
        "total": 53
    }
}

error_reason содержит безопасный код для интерфейса: card_declined, insufficient_funds, bank_declined или unknown. Внутренние сообщения платёжного провайдера клиенту не передаются.

Ошибки

401 — App Token или Bearer клиента отсутствует либо не распознан;
404 — подписка не принадлежит клиенту или текущему приложению;
429 — превышен лимит 60 запросов в минуту.

Шаг 2. Решите, показывать ли кнопку повтора

У платежа и подписки разные флаги:

payment.can_retry относится к конкретной строке истории. По нему показывайте кнопку «Повторить оплату» рядом с этим платежом;
subscription.can_retry_payment и subscription.retry_payment_reason описывают только последнюю попытку подписки и подходят для общей кнопки в карточке подписки.

Не разрешайте повтор произвольного старого платежа только потому, что его статус выглядит неуспешным. Условия тарифа или способ оплаты могли измениться после этой попытки.

Шаг 3. Повторите доступный платёж

Повтор неуспешной оплаты

Метод: POST
URL: https://api.gigma.ru/api/counterparty/subscriptions/{id}/payments/{payment_id}/retry
Авторизация: App Token + Bearer клиента
Headers: Token: {application_token}; Authorization: Bearer {counterparty_token}
Успешный ответ: 200 / 202

Перед вызовом убедитесь, что у выбранной записи can_retry: true. Тело запроса не нужно.

Ответ

{
    "subscription": {
        "id": 42,
        "status": "charging",
        "current_period_end": "2026-09-15T10:00:00+00:00",
        "can_retry_payment": false,
        "retry_payment_reason": "payment_pending"
    },
    "payment": {
        "id": 316,
        "subscription_id": 42,
        "amount": "490.00",
        "currency": "RUB",
        "status": "pending",
        "can_retry": false
    }
}

Ответ не обёрнут в data: subscription и payment находятся в корне.

HTTP 202 — подписка перешла в charging, списание продолжается. Обновите подписку позже;
HTTP 200 — повтор завершился без перехода в длительную обработку. Используйте статусы объектов из ответа.

Ошибки

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

Если проблема в способе оплаты

Не запускайте повтор много раз подряд. Предложите клиенту привязать новый способ оплаты, дождитесь успешного sync и только после этого повторяйте платёж или возобновляйте подписку.