Интеграция VSPS: как отличить активные подписки от приостановленных

При разработке интеграции с VSPS (Visa Subscription Payment Service) для управления подписками на карты часто возникает вопрос: как программно различать активные и приостановленные подписки? В этой статье мы разберём ключевые поля API, типичные статусы и практические советы по работе с песочницей Visa.

Что такое VSPS и зачем различать статусы подписок?

VSPS - это сервис Visa для рекуррентных платежей по картам. При интеграции важно правильно обрабатывать жизненный цикл подписки: активные списания, добровольная приостановка (например, по запросу держателя карты) или блокировка. Ошибка в определении статуса может привести к неправильным списаниям или потере данных.

Основные статусы подписок в VSPS

Согласно документации Visa, подписка может находиться в одном из следующих состояний:

• ACTIVE - подписка активна, списания выполняются по расписанию.
• SUSPENDED - подписка приостановлена (например, временно по просьбе клиента или из-за проблем с картой).
• CANCELLED - подписка отменена.
• EXPIRED - срок действия подписки истёк.

Как отличить активную подписку от приостановленной через API

Для получения статуса используйте метод GET /subscriptions/{id}. В ответе ищите поле status. Если статус равен ACTIVE - подписка активна. Если SUSPENDED - приостановлена. Дополнительно можно проверить поле suspensionReason, которое содержит причину приостановки (например, cardholder_request).

Пример запроса на получение статуса:

GET /v1/subscriptions/sub_12345 HTTP/1.1
Host: api.visa.com
Authorization: Bearer <token>

Пример ответа:

{
  "id": "sub_12345",
  "status": "SUSPENDED",
  "suspensionReason": "cardholder_request",
  "startDate": "2025-01-15",
  "endDate": null
}

Проблемы с песочницей Visa: нестыковки данных

Многие разработчики жалуются, что в песочнице Visa (VISA Sandbox) данные могут не соответствовать документации. Например, подписка со статусом SUSPENDED иногда возвращает некорректные поля или отсутствующие причины приостановки. Рекомендуется:

• Тестировать на реальных данных после выхода в production, используя тестовые карты Visa.
• Верифицировать статус через вебхуки (callbacks) от Visa, которые приходят при изменении состояния подписки.
• Использовать поле nextBillingDate: если оно null или в прошлом, подписка, скорее всего, приостановлена или завершена.

Практические рекомендации по интеграции

Чтобы избежать путаницы, следуйте этим советам:

• Всегда проверяйте поле status в ответе API, а не только поле active (если оно есть).
• Логируйте все изменения статусов через вебхуки, чтобы иметь полную историю.
• Если документация непонятна, используйте официальные примеры кода из репозитория Visa на GitHub.
• Для отладки в песочнице создавайте подписки с разными сценариями (например, с истечением срока или приостановкой) и сверяйте ответы.

Заключение

Различие между активными и приостановленными подписками в VSPS сводится к анализу поля status в ответе API. Несмотря на возможные нестыковки в песочнице Visa, использование вебхуков и дополнительных полей (например, nextBillingDate) поможет избежать ошибок. Придерживайтесь документации и тестируйте на реальных данных перед запуском.