Ключ платёжного API работает как банковская карта без PIN-кода. Тот, кто его предъявит, может создавать счета, читать ваши платёжные данные и, если вы используете выплаты, выводить деньги с вашего баланса. Безопасность платёжного API, таким образом, сводится к трём привычкам: хранить ключ на собственных серверах, разрешать API принимать его только с адресов этих серверов и подтверждать каждый вебхук, перепроверяя платёж, прежде чем действовать.
Это руководство адресовано руководителям инженерных команд и руководителям платёжных направлений в PSP, EMI, банках и у мерчантов, которые подключают крипто-платёжный API с расчётами в евро. В нём показано, как ограничить ключ по IP-адресу и диапазону CIDR, где должен храниться ключ, как проверять вебхуки и какие контроли нужны вокруг выплат. Примеры используют API и панель ItisPay (демонстрационные данные).
Ключевые моменты
Коротко
- API-ключ — это учётные данные типа bearer: кто их предъявил, тот и авторизован. По данным GitGuardian, в публичные коммиты GitHub в 2025 году попало 28,65 млн новых секретов, жёстко прописанных в коде, поэтому планируйте не только то, как сохранить ключ, но и то, что он может утечь.
- IP-список разрешённых адресов делает утёкший ключ бесполезным за пределами вашей сети. Укажите наименьшие диапазоны IPv4 или IPv6, которые покрывают ваши реальные исходящие адреса; пустой список разрешает любой адрес.
- Вебхук — это уведомление, а не доказательство. Перепроверьте счёт по его ID вашим ключом, прежде чем отправлять товар или зачислять средства на счёт.
- Для выплат нужны человеческие контроли на вашей стороне: двухэтапный вход, сохранённые IBAN и кошельки получателей и второй согласующий для сумм выше заданного порога.
Почему утечка платёжного API-ключа так опасна?#
Утечка платёжного API-ключа опасна, потому что ключ — это вся идентичность вашей интеграции. API ItisPay, как и большинство платёжных API, аутентифицирует каждый запрос одним заголовком, Api-key, и одна и та же аутентификация открывает доступ к счетам, выплатам на IBAN или кошелёк и выводам криптовалюты на внешний адрес. Поэтому в документации требуется, чтобы ключ «не раскрывался в клиентском коде или публичных репозиториях».
На практике ключи утекают через обычные места: код, логи и чаты. По данным GitGuardian's State of Secrets Sprawl 2026 (март 2026 года), в публичные коммиты GitHub в 2025 году попало 28,65 млн новых секретов, жёстко прописанных в коде, что на 34 % больше, чем годом ранее. Когда GitGuardian повторно проверила секреты, утёкшие в 2022 году, более 64 % из них в январе 2026 года были всё ещё действительны. Команды публикуют ключи и потом забывают их заменить.
В списке OWASP API Security Top 10 (2023) «Broken Authentication» занимает второе место, и там предупреждается, что «механизм аутентификации — лёгкая мишень для атакующих, поскольку доступен всем». В отчёте Verizon 2025 Data Breach Investigations Report злоупотребление учётными данными названо самым частым первичным вектором атаки — 22 %. Одна секретная строка — слабая защита, поэтому остальная часть руководства добавляет слои, которые сохраняют силу даже после того, как строка попала наружу.
Как IP-список разрешённых адресов защищает API-ключ?#
Список разрешённых IP-адресов, который иногда называют IP-вайтлистом, защищает ключ, привязывая его не только к строке, но и к местам. API принимает ключ, только если запрос пришёл с адреса из вашего списка; копия ключа на ноутбуке разработчика, в логе CI или на paste-сайте не работает.
В панели ItisPay эта настройка находится в разделе Projects, затем Settings, затем Security, в поле API Allowed IPs. Поле принимает список отдельных адресов и блоков CIDR, разделённых запятыми. Подсказка в поле гласит: «Оставьте пустым, чтобы разрешить все IP-адреса. Поддерживаются IPv4 и IPv6.» Тот же список можно задать при создании проекта через API, в поле api_allowed_ips; некорректная запись, например 256.256.256.256, отклоняется с ошибкой валидации, а не сохраняется.
Пустое значение по умолчанию важно. Новый проект принимает ключ откуда угодно, пока кто-нибудь не заполнит поле, поэтому внесите этот шаг в список задач перед запуском, а не в список того, что можно поправить позже. Демонстрационные значения на скриншоте, 203.0.113.10 и 198.51.100.0/24, взяты из диапазонов, которые RFC 5737 резервирует для документации; ваш список будет содержать ваши собственные публичные адреса. У каждого проекта свой 64-символьный ключ и свой список, поэтому продакшн может быть закреплён за двумя-тремя серверами, а тестовый проект — принимать более широкий набор.
Как записывать диапазоны CIDR для IPv4 и IPv6?#
Записывайте наименьший диапазон, который покрывает каждый адрес, реально используемый вашими серверами для обращения к API. Большинство проблем со списками возникает из-за слишком широкого диапазона или из-за забытого исходящего маршрута.
Как читать префикс#
Блок CIDR — это адрес, за которым следуют косая черта и длина префикса. RFC 4632 определяет длину префикса как число значащих битов: 192.168.99.0/24 фиксирует первые 24 бита и оставляет свободными 8, что даёт 256 адресов. Каждый бит, который вы отнимаете от префикса, удваивает блок. /32 — это один адрес IPv4, /29 — 8, /24 — 256, а /16 — 65 536.
IPv6 работает так же, но с 128 битами. /128 — один адрес. RFC 4291 задаёт для большинства адресов IPv6 интерфейсную часть в 64 бита, поэтому сеть сервера обычно представляет собой /64, а хост может менять адрес внутри неё, например когда операционная система генерирует временные адреса. Если IPv6-адрес вашего хоста меняется, а этот /64 принадлежит только вам, укажите /64, а не отдельный /128. Диапазон документации для примеров IPv6 — 2001:db8::/32 (RFC 3849), поэтому никогда не копируйте его в реальный список разрешённых адресов.
Как найти реальный исходящий адрес#
Важен тот адрес, который видит API, а не тот, который сам сервер сообщает о себе. За облачным NAT-шлюзом или корпоративным файрволом многие машины делят один или два публичных адреса. Serverless-функции часто выходят из общего пула, если вы не направляете их через фиксированный выход. Проверьте из каждого окружения, обратившись к сервису «узнать мой IP» или прочитав исходящий адрес в логах файрвола, а затем внесите в список именно его.
| Конфигурация | Что добавить в список | Вердикт |
|---|---|---|
| Один сервер со статическим публичным IPv4-адресом | Этот адрес в виде /32 или без маски | Работает |
| Несколько серверов за облачным NAT-шлюзом | Публичные адреса NAT-шлюза | Работает |
| Хост с IPv6 и меняющимися адресами | /64 хоста, если его не использует никто другой | Зависит |
| Офисная сеть для ручного тестирования | Фиксированный адрес офиса, если провайдер его гарантирует | Зависит |
| Serverless-функции без фиксированного исходящего адреса | Сначала направьте их через NAT со статическим адресом | Нет |
| Весь региональный диапазон облачного провайдера | Ничего: он охватывает и других клиентов | Нет |
Прежде чем сохранить изменения, сначала добавьте новый адрес, выполните развёртывание, убедитесь, что трафик проходит, и только после этого удалите старый. Сохранение списка без ваших действующих серверов заблокирует ваш собственный процесс оплаты.
Где должен храниться API-ключ и кто его видит?#
Ключ должен храниться на ваших серверах, в хранилище секретов, и нигде больше. Никогда не встраивайте его в браузерную страницу или мобильное приложение: там его может прочитать любой. Не передавайте его и в URL: в OWASP REST Security Cheat Sheet предупреждается, что ключ в URL может попасть в журналы веб-сервера. Страница оплаты обращается к вашему бэкенду, а бэкенд — к платёжному API.
Загружайте ключ при запуске из менеджера секретов или переменных окружения, а не из конфигурационного файла в репозитории. Если код хранится на GitHub, включите push protection: согласно документации GitHub, когда она «обнаруживает потенциальный секрет при попытке отправки, она блокирует отправку».
Используйте отдельный ключ для каждой среды. Каждый проект ItisPay имеет собственный ключ и собственный список разрешённых адресов, поэтому раздельные проекты для продакшена и тестовой среды означают, что утёкший ключ тестовой среды не может повлиять на реальные платежи. Ограничьте круг лиц, которые видят продакшен-ключ. Руководящие принципы Европейского банковского органа (EBA) 2019 года по безопасности ИКТ устанавливают правило доступа «need-to-know» с «минимальными правами доступа», включая технических пользователей; с 2025 года DORA распространяет эту обязанность на большинство платёжных организаций.
Затем заранее запишите, как вы будете заменять ключ, — до того как это понадобится. OWASP Cryptographic Storage Cheat Sheet рекомендует менять ключи по истечении установленного срока и всякий раз, когда есть подозрение на компрометацию, а также следить за тем, чтобы «код и процессы, необходимые для смены ключа, были готовы до того, как они понадобятся».
Как проверять вебхуки от платёжного API?#
Относитесь к вебхуку как к уведомлению о том, что что-то изменилось, но никогда как к подтверждению оплаты. Любой, кто узнает ваш callback URL, может отправить на него поддельное сообщение о «завершении». Безопасная схема такая: запросите счёт обратно через API с вашим ключом и действуйте на основании того, что вернёт API.
При создании счёта ItisPay поле callback_url задаёт адрес для обновлений статуса. Когда приходит вебхук, возьмите из него ID счёта, выполните GET-запрос к счёту по ID и выдавайте товар или зачисляйте средства только в том случае, если ответ показывает ожидаемый вами статус и сумму, которую вы выставили. В документации этот эндпоинт описан как возвращающий статус платежа и данные блокчейна «для отображения пользователям или проверки».
Несколько правил помогут сделать обработчик надёжным:
- Принимайте вебхуки только по HTTPS и отклоняйте обычный HTTP.
- Сделайте обработчик идемпотентным: сохраняйте ID и статус каждого обработанного счёта и пропускайте повторы, поскольку провайдеры повторно отправляют уведомления.
- Отвечайте быстро и выполняйте основную работу в очереди, чтобы медленная база данных не вызывала повторных отправок.
- Если провайдер подписывает вебхуки с помощью HMAC — хеша с ключом, определённого в RFC 2104, — пересчитайте подпись и сравните её функцией с постоянным временем выполнения. OWASP Webhook Security Cheat Sheet говорит прямо: «Никогда не используйте ==: это раскрывает информацию о времени и может превратить эндпоинт в оракул подписи.» Отклоняйте сообщения, у которых подписанная метка времени слишком старая.
Проверьте перед запуском в продакшен. У ItisPay есть эндпоинт, который имитирует изменение статуса для реального тестового счёта, и ещё один, который повторно отправляет последний вебхук для счёта или заказа по ID, чтобы вы могли проверить повторные отправки и дубликаты без реальных денег.
Как защитить выплаты и доступ к панели управления?#
Выплаты — это то место, где украденный ключ превращается в потерю денег, поэтому добавьте вокруг них контроль со стороны людей. Через эндпоинт выплат ItisPay фиатная выплата уходит на IBAN получателя, а криптовыплата — на адрес кошелька; и то и другое списывается с вашего доступного баланса. API выполняет то, что сказано в запросе; решать, законен ли запрос, — ваша задача.
Меры контроля, которые работают на вашей стороне:
- Двухэтапная аутентификация для всех, у кого есть доступ к панели управления или выплатам. Законодательство ЕС о платежах уже использует эту идею для платёжных пользователей: правила PSD2 о сильной аутентификации клиента требуют минимум два независимых элемента из категорий «знание», «владение» и «присущность». Примените тот же стандарт к своим сотрудникам.
- Сохранённые получатели. Ведите собственный список одобренных IBAN и адресов кошельков и разрешите сервису выплат отправлять средства только на адреса из этого списка. Новый получатель проходит отдельное одобрение, желательно с периодом ожидания.
- Второй утверждающий сверх порога. Один человек готовит выплату, другой её утверждает. Порог задайте исходя из собственного уровня допустимого риска.
- Отдельный сервис выплат. Запускайте выплаты из одного сервиса с собственным фиксированным адресом в списке разрешённых, отдельно от серверов оплаты, которые создают счета.
| Мера контроля | Что она блокирует | Вердикт |
|---|---|---|
| Список разрешённых IP-адресов для ключа | Использование утёкшего ключа из-за пределов вашей сети | Работает |
| Ключ только на сервере | Кража ключа из браузеров, приложений и репозиториев | Работает |
| Повторное чтение счёта после webhook | Поддельные уведомления «оплачено» | Работает |
| Сохранённые получатели и второй утверждающий | Выплаты на IBAN или кошелёк злоумышленника | Работает |
| Любая из этих мер по отдельности против взломанного сервера из списка | Кража изнутри, кем-то уже проникшим в систему | Нет |
Чего DORA и PCI DSS ожидают от доступа к API?#
Если вы — регулируемая финансовая компания в ЕС, эти меры не являются необязательным дополнением. Регламент о цифровой операционной устойчивости (DORA, Регламент (ЕС) 2022/2554) применяется с 17 января 2025 г., согласно EBA. Его статья 9 требует от компаний «внедрять политики, которые ограничивают физический или логический доступ» к ИКТ-активам и «внедрять политики и протоколы для механизмов строгой аутентификации». Ключ с разрешённым списком IP-адресов, доступный только серверу, и план ротации — это именно те доказательства, которые запрашивает аудитор.
PCI DSS охватывает данные карт, а не криптосчета. Если та же команда также проводит платежи картами, требование 8.4.2 предписывает многофакторную аутентификацию для всего доступа к среде данных держателей карт, а требования версии 4.0 с отложенным сроком действия стали обязательными 31 марта 2025 г.
Где меры безопасности API для платежей перестают работать?#
Эти меры сужают способы входа. Сами по себе они не делают интеграцию безопасной. Даже для отправителей webhook лист OWASP по webhook называет разрешённый список IP-адресов «лишь дополнительным уровнем», потому что «общий выходной IP-адрес не является доказательством личности».
Где это не помогает
- Взломанный сервер из списка. Злоумышленник отправляет запросы с доверенного адреса с настоящим ключом.
- Общие исходящие адреса. Если другие клиенты выходят в облако с того же NAT-адреса, список разрешённых адресов не может отличить их от вас.
- Украденный пароль к панели без двухэтапного входа. Злоумышленник обходит API полностью.
- Персональные данные в полях счёта. Публичный эндпоинт счетов ItisPay возвращает полные данные по открытым счетам без ключа, поэтому держите имена и email клиентов вне названия заказа.
Как запустить безопасную интеграцию за полдня?#
Техническую часть безопасной интеграции можно завершить за полдня, если следовать фиксированному порядку. Шаги ниже используют ItisPay; тот же порядок работает с любым провайдером.
- Создайте тестовый проект и отдельный производственный проект, у каждого свой ключ.
- Храните оба ключа в менеджере секретов и загружайте их только на сервере.
- Найдите публичный исходящий адрес каждой среды и укажите его в API Allowed IPs.
- Создайте счёт из бэкенда: отправьте POST на https://api.itispay.com/api/v1/invoices с заголовком Api-key, уникальным order_id, fiat_amount с fiat_currency EUR, монетой в поле currency и вашим callback_url.
- Напишите обработчик webhook: только HTTPS, идемпотентный, перед любым действием повторно читающий счёт по ID.
- Запустите симуляцию webhook для каждого обрабатываемого статуса, затем эндпоинт повторной отправки, чтобы проверить дубликаты.
- Включите выплаты последними, с сохранёнными получателями и вторым утверждающим.
Для быстрого старта ассистент Ask AI в панели по запросу пишет примеры кода, например вызов создания счёта на Node.js с уже подставленным заголовком Api-key. Относитесь к нему как к черновику: сверяйте названия полей со справочником API перед выпуском, поскольку контрактом является справочник, а не сгенерированный пример. ItisPay также публикует официальный клиент TypeScript в npm — @itispay/typescript-client.
Если вы встраиваете это в более широкую настройку оркестрации платежей, выдавайте каждому провайдеру отдельный ключ, список разрешённых адресов и обработчик webhook. Та же запись, которую можно перечитать по ID, также питает сверку криптоплатежей для вашей финансовой команды.
Если вы хотите принимать платежи в стейблкоинах и получать евро без самостоятельного построения стека, ItisPay предоставляет API, выставление счетов, webhook и сверку, а также первый уровень безопасности платёжного API: ключи, которые можно ограничить вашими собственными IP-адресами. Лицензирование, KYC и расчёты на ваш IBAN проходят через нашего партнёра с лицензией в ЕС — поставщика услуг в сфере криптоактивов (CASP) и платёжного учреждения, а большинство команд проходит путь от KYB до первой транзакции менее чем за неделю.
Эта статья предназначена только для информационных целей и не является юридической или регуляторной консультацией.
