Способы оплаты

Gigma сохраняет способ оплаты после первого успешного платежа и использует его для продлений. В клиентском интерфейсе показывайте только безопасные данные: тип способа оплаты, название и последние четыре цифры карты.

Полный номер карты и CVC через API Gigma не передаются. Новую карту клиент вводит только на странице платёжного провайдера.

Получение сохранённых способов оплаты

Получение способов оплаты клиента

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

Метод возвращает активные способы оплаты текущего клиента, доступные текущему Application.

Ответ

{
    "data": [
        {
            "id": 9,
            "payment_method_type": "bank_card",
            "card_type": "Visa",
            "card_last_4": "4242",
            "title": "Visa •••• 4242",
            "is_active": true,
            "created_at": "2026-08-15T10:00:00+00:00"
        }
    ]
}

Для СБП payment_method_type будет sbp, а карточные поля могут быть null.

Ошибки

401 — App Token или Bearer клиента отсутствует либо не распознан;
429 — превышен лимит частоты запросов.

Отвязка способа оплаты

Отвязка сохранённого способа оплаты

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

Метод отвязывает способ оплаты только от текущего приложения. Если этот же способ используется другим приложением клиента, он не удаляется глобально.

Ответ

{
    "message": "Способ оплаты отвязан"
}

Ошибки

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

Смена способа оплаты подписки

Не передавайте новую карту через PATCH /subscriptions/{id}. Безопасная смена состоит из трёх шагов:

создайте попытку привязки;
перенаправьте клиента на confirmation_url;
после возврата синхронизируйте попытку и проверьте её статус.

Смена выполняется через нулевой платёж. Она не списывает стоимость подписки и не продлевает оплаченный период.

Шаг 1. Начните смену

Начало безопасной смены способа оплаты

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

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

autopay_consent (boolean, обязательно) — должно быть true после явного согласия клиента.

Не передавайте card, card_number, cvc, payment_method_data или собственный return_url: эти поля запрещены валидацией.

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

{
    "autopay_consent": true
}

Ответ

{
    "id": 31,
    "subscription_id": 42,
    "status": "pending",
    "confirmation_url": "https://yoomoney.ru/confirmation/...",
    "saved_payment_method_id": null,
    "expires_at": "2026-08-16T11:00:00+00:00"
}

Откройте confirmation_url. Не считайте способ оплаты изменённым, пока статус не станет succeeded.

Ошибки

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

После 503 вызовите GET /api/counterparty/subscriptions, возьмите latest_payment_method_change.id у нужной подписки и передайте этот ID в метод sync. Так вы продолжите уже начатую операцию, даже если первый ответ не содержал объект попытки.

Шаг 2. Подтвердите способ оплаты

Клиент вводит платёжные данные на странице провайдера. После завершения провайдер возвращает его в ваш интерфейс.

Возврат не означает успешную привязку. Используйте id попытки из первого ответа или latest_payment_method_change.id из списка подписок и вызовите sync.

Шаг 3. Синхронизируйте попытку

Синхронизация смены способа оплаты

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

Тело запроса не нужно. Метод получает актуальное состояние операции у провайдера и возвращает объект попытки.

Ответ

{
    "id": 31,
    "subscription_id": 42,
    "status": "succeeded",
    "confirmation_url": null,
    "saved_payment_method_id": 12,
    "expires_at": "2026-08-16T11:00:00+00:00"
}

Статусы попытки

Статус	Что делать
`creating`	подождать и вызвать `sync`
`pending`	открыть `confirmation_url` или продолжить синхронизацию после возврата
`creation_unknown`	не создавать новую попытку, вызвать `sync` позже
`succeeded`	способ оплаты заменён, используйте `saved_payment_method_id`
`failed`	показать ошибку и разрешить начать новую попытку
`superseded`	попытка заменена более новой, обновить подписку
`manual_review`	не повторять автоматически, дождаться сверки

Ошибки

404 — подписка или попытка не принадлежит клиенту либо текущему приложению;
409 — состояние изменилось параллельно. Снова получите подписку и последнюю попытку;
429 — превышен лимит 12 запросов в минуту;
503 — Gigma пока не может подтвердить состояние у провайдера. Сохраните ID попытки и повторите sync позже, не создавая новую операцию.

После успешной смены

Снова получите подписки клиента и обновите saved_payment_method и latest_payment_method_change.

Если подписка была canceled, успешная привязка не возобновляет её автоматически. После смены способа оплаты отдельно вызовите возобновление подписки.