API выпуска карт: что проверить до интеграции

Перед интеграцией API выпуска карт опишите нужные бизнес-операции и доказательства их корректной работы. Метод создания карты — только часть системы. Команде также нужны достоверные балансы, контроль доступа, сверка операций и обработка сбоев без повторных финансовых действий.

Это список вопросов для проектирования, а не документация API AIHUB. Публичная документация AIHUB описывает REST API как private beta, а методы — как предварительный обзор. Подтвердите актуальный доступ и поддерживаемые операции до планирования сроков. Документация AIHUB.

Начните с понятных правил работы

Опишите, кто может выпускать, просматривать, замораживать карты и управлять ими. Укажите операции, требующие подтверждения, и порядок отзыва прав после ухода сотрудника. Решите, как связать внутренние идентификаторы клиентов или команд с записями провайдера, не помещая карточные реквизиты в обычные журналы.

Запросите способы аутентификации, наборы разрешений, тестовую среду, лимиты запросов, правила версионирования и формат ошибок. Разделяйте три состояния: «есть в документации», «доступно в нашей среде» и «проверено нашей командой».

Сделайте повторные запросы безопасными

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

Уточните поддержку ключей идемпотентности: для каких операций они работают и как долго сохраняется результат. Для повторения одного намеренного действия используйте тот же идентификатор операции. Не переносите правила другого провайдера без проверки. Документация Stripe показывает один из вариантов этого подхода. Идемпотентные запросы.

Проверка готовности: имитировать тайм-аут при создании и убедиться, что в итоге появился ровно один нужный объект. Если результат неоднозначен, должен сработать описанный порядок восстановления до новой попытки.

Проверяйте и сверяйте уведомления

Запросите правила проверки подписи webhook, защиты от повторного воспроизведения, повторных доставок, порядка событий и их идентификаторов. Дубликат уведомления не должен повторно запускать бизнес-операцию. Не предполагайте, что события всегда приходят по времени возникновения.

В документации Stripe разобраны подписи, повторная доставка и порядок событий. Это полезные вопросы для любого провайдера, но не доказательство поведения AIHUB. Рекомендации по webhook.

Проверка готовности: отправить одно событие дважды, затем доставить старое событие после нового. Состояние системы должно остаться правильным, а обработка — прослеживаемой. Отдельно проверьте восстановление после недоступности получателя.

Определите источник финансовых данных

Различайте доступные средства, авторизации, окончательные списания, отмены, возвраты и комиссии по реальной модели провайдера. Сверяйте свою базу с его выгрузкой или основным API операций. Успешное действие «запросить пополнение» в вашем приложении ещё не доказывает, что карта получила деньги.

Не отправляйте чувствительные платёжные данные в аналитику и общие журналы приложения. По возможности используйте предоставленный провайдером интерфейс для работы с реквизитами. До самостоятельного хранения или обработки таких данных ответственный специалист должен определить требования к интеграции.

Объясняйте готовность владельцу простыми словами

Хороший статус может выглядеть так: «В тестовой среде выпуск карты работает. Повторный запрос не создаёт дубль. Заморозку и отзыв доступа проверили. Восстановление после пропущенных уведомлений пока не подтверждено, поэтому запуск в рабочую среду отложен».

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

Зафиксируйте границу запуска

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