YooKassa API v3: обзор, ресурсы, аутентификация и тестовая среда

YooKassa API v3: обзор, ресурсы, аутентификация и тестовая среда

Что такое YooKassa API v3

YooKassa API v3 — это актуальная версия серверного интерфейса для приёма и управления интернет‑платежами. Если вы ищете надёжный способ подключить yookassa ru api к сайту, приложению или CRM, именно v3 обеспечивает чистую REST‑модель, прогнозируемые ответы и удобную работу с ключевыми объектами: платежами, возвратами, чеками и уведомлениями.

API v3 упрощает типовые сценарии (создание платежа, подтверждение, возврат), добавляет строгое управление идемпотентностью и улучшает совместимость со стандартными HTTP‑клиентами. Базовый адрес для работы — https api yookassa ru v3, что в связке с корректной аутентификацией и безопасной обработкой webhook‑ов делает интеграцию быстрой и защищённой.

Базовые адреса и домены

Основной корневой адрес: https://api.yookassa.ru/v3. В разговорах о подключении часто используют краткую форму api.yookassa.ru v3 — это тот же базовый хост, доступный по HTTPS 443 с современными шифрами (рекомендуется TLS 1.2+).

Рекомендации:

• Всегда используйте HTTPS — запросы по незащищённому протоколу не поддерживаются.
• Фиксируйте домены и сертификаты в инфраструктуре, избегайте экзотических прокси без необходимости.
• При сетевых проблемах и подборе стабильных эндпоинтов см. материалы о доменных конфигурациях и зеркалах: Домены и зеркала.

Основные ресурсы и эндпоинты

Ниже — ключевые ресурсы yookassa api v3. Платежи — главная сущность, но в реальной интеграции почти всегда участвуют и возвраты, и уведомления, и (опционально) чеки.

Ресурс	Пример пути	Назначение	Полезные ссылки
Платежи	/v3/payments	Создание, получение, подтверждение, листинг	API v3: Payments, Статусы платежей
Возвраты	/v3/refunds	Полные/частичные возвраты денежных средств	Справка по возвратам
Чеки	/v3/receipts	Формирование/отправка фискальных чеков (при необходимости)	—
Webhooks	/v3/webhooks	Регистрация, просмотр и удаление URL для уведомлений	Безопасность платежей

Для краткого старта с платежами см. подробный гайд: API v3: Payments.

Аутентификация и обязательные заголовки

Аутентификация в api yookassa основана на HTTP Basic. В роли имени пользователя используется идентификатор магазина, а в роли пароля — секретный ключ. Получить и управлять ключами можно через личный кабинет:

• Вход в личный кабинет
• Личный кабинет: возможности

Рекомендуемые заголовки для запросов к https api yookassa ru v3:

Заголовок	Значение	Комментарий
Authorization	Basic base64(shopId:secretKey)	Обязателен для всех защищённых эндпоинтов
Content-Type	application/json	Для POST/PUT с телом запроса
Idempotence-Key	UUID или уникальная строка	Обязателен при создании ресурсов (например, платежа)
User-Agent	Название клиента и версия	Упростит диагностику
Accept-Language	ru-RU (при необходимости)	Локализация сообщений

Советы по безопасности ключей, хранению и ротации — в разделе: Безопасность платежей.

Жизненный цикл платежа и статусы

Типовой сценарий в yookassa api v3:

1. Инициируете платеж: POST к /v3/payments с суммой, описанием, параметрами подтверждения (например, редирект на страницу банка или подтверждение в приложении).
2. Покупатель проходит подтверждение (3‑D Secure, приложение банка и т. п.).
3. API возвращает промежуточный или финальный статус. Если вы создаёте платеж с отложенным списанием, получаете waiting_for_capture и отдельно подтверждаете списание. Иначе сразу увидите succeeded.
4. По нужде делаете частичный или полный возврат через /v3/refunds.

Ключевые статусы: pending, waiting_for_capture, succeeded, canceled. Подробная расшифровка — здесь: Статусы платежей.

Webhook-уведомления: как принимать и подтверждать

Уведомления позволяют вашему бекенду мгновенно реагировать на изменения: успешное списание, ожидание захвата, отмена, завершение возврата.

Рекомендации по обработке:

• Принимайте POST‑уведомления на HTTPS‑URL, доступный из интернета.
• Проверяйте подлинность уведомления — используйте секрет для уведомлений, настроенный в кабинете. Рекомендации и меры защиты: Безопасность платежей.
• Дедуплицируйте события по их идентификаторам или идемпотентным ключам: уведомления могут приходить повторно.
• Отвечайте быстро (200 OK) и обрабатывайте бизнес‑логику асинхронно, чтобы не блокировать переотправку.
• Храните журнал уведомлений для аудита и отладки.

Типичные события: payment.pending, payment.waiting_for_capture, payment.succeeded, payment.canceled, refund.succeeded.

Тестовая среда (Sandbox) и проверка интеграции

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

Как работать:

• Включите тестовый режим в кабинете и используйте тестовые реквизиты магазина.
• Делайте запросы на тот же хост api.yookassa.ru v3 — логика идентична бою, платежи не списываются с реальных карт.
• Проверяйте обработку редиректов, webhooks и возвратов на тестовых сценариях (успех, отказ, 3‑D Secure).
• Сравнивайте статусы и поля ответов с боевыми ожиданиями.

Если не видите тестовые ключи или доступ, проверьте учётные данные: Проблемы со входом.

Идемпотентность, повторы и устойчивость

Идемпотентность гарантирует, что повторный POST не создаст два платежа. Для каждого запроса на создание ресурса задавайте уникальный Idempotence-Key. Если не получили ответ или повторили запрос из‑за сетевого сбоя, отправляйте его с тем же ключом — сервер вернёт состояние исходной операции.

Советы:

• Генерируйте ключи в формате UUID и храните их у себя вместе со статусом операции.
• Повторы выполняйте с экспоненциальной задержкой и ограничивайте общее число попыток.
• Не меняйте тело запроса при повторе: различия могут привести к конфликту и ошибке 409.

Ошибки API и коды ответов

Ниже — ориентиры по стандартным HTTP‑кодам в yookassa api v3 и как на них реагировать.

Код	Когда возникает	Что делать
200/201	Успешная операция/создание	Обрабатывайте тело ответа, сохраняйте id ресурса
400	Неверные параметры запроса	Проверьте схему, обязательные поля, типы данных
401	Неверная аутентификация	Перепроверьте shopId/secretKey, формат Basic
403	Недостаточно прав	Убедитесь, что ключ имеет доступ к ресурсу/операции
404	Ресурс не найден	Проверьте идентификатор платежа/возврата
409	Конфликт идемпотентности	Используйте тот же Idempotence-Key и идентичное тело
422	Невалидное состояние	Проверьте бизнес‑правила, статусы и суммы
429	Превышен лимит запросов	Включите backoff, уменьшите частоту
500/503	Временная ошибка сервера	Реализуйте повторы с задержкой и мониторинг

Локализованные расшифровки ошибок и рекомендации по зарплате с инцидентами — в материалах по безопасности и стабильности: Безопасность платежей.

Лимиты и производительность

Для устойчивой работы придерживайтесь следующих практик:

• Планируйте повторы запросов и обрабатывайте 429 с backoff.
• Не делайте лишних листингов — храните у себя ключевые идентификаторы платежей/возвратов.
• Используйте пагинацию и фильтры, поддерживаемые конкретным ресурсом.
• Минимизируйте задержки при обработке webhook‑ов, переносите тяжёлую работу в фоновую очередь.
• Логируйте корреляционные идентификаторы запросов для быстрой диагностики.

Миграция на yookassa api v3

Если вы уже работаете со старой версией и хотите перейти на https api yookassa ru v3:

• Сопоставьте используемые эндпоинты и поля с актуальными ресурсами v3.
• Учтите обязательность заголовка Idempotence-Key для создания ресурсов.
• Проверьте формат сумм и валют, обработку статусов и подтверждений.
• Перепройдите весь цикл в тестовом режиме: создание, подтверждение, webhook‑уведомления, возвраты.
• Обновите мониторинг и алерты под новые коды состояний и ошибок.

Чеклист интеграции api yookassa

• Получите доступы в кабинете: Вход в личный кабинет, посмотрите раздел с возможностями: Личный кабинет: возможности.
• Выберите и опишите нужные сценарии: одностадийное или двухстадийное списание, возвраты, чеки.
• Реализуйте создание платежа и обработку редиректов. Детали: API v3: Payments.
• Поднимите HTTPS‑URL для webhook‑ов, проверьте секреты и логи. Советы: Безопасность платежей.
• Настройте тестовую среду и пройдите end‑to‑end сценарии.
• Добавьте возвраты и сценарии отмены: Справка по возвратам.
• Для счетов и платежных ссылок рассмотрите: Ссылки и счета и пользовательский сценарий Мои платежи.
• Убедитесь в корректной работе на целевых доменах: Домены и зеркала.

FAQ: распространённые ошибки

• Нет заголовка Idempotence-Key при создании платежа. Итог — дубли. Решение: всегда генерируйте уникальный ключ на операцию.
• 401 Unauthorized. Проверяйте формат Basic и актуальность секретного ключа.
• Не приходят webhook‑и. Убедитесь, что URL публичен по HTTPS, сертификат валидный, а ваш сервер быстро отвечает 200 OK.
• Не обрабатываются статусы. Сверьте бизнес‑логику с актуальной схемой состояний: Статусы платежей.
• Проблемы с доступом к кабинету. Проверьте учётные данные: Проблемы со входом.

Итоги и следующий шаг

YooKassa API v3 — это надёжный фундамент для интеграции платежей: единый базовый адрес api.yookassa.ru v3, ясные ресурсы, безопасная аутентификация и продуманная идемпотентность. Следуйте рекомендациям по заголовкам, webhook‑ам и тестовой среде, чтобы запустить интеграцию быстро и без сюрпризов.

Готовы начать? Изучите детали сценариев в API v3: Payments и получите доступы в личном кабинете. Интеграция api yookassa займёт совсем немного времени, а ваши клиенты сразу оценят удобный и безопасный приём платежей.