u-kassa.ru
Войти

API v3 /payments: создание, подтверждение, статусы и ошибки

Получить CloudPayments бесплатно

API v3 /payments: создание, подтверждение, статусы и ошибки

Схема процесса платежа: создание → перенаправление клиента → 3‑D Secure → статус → webhook → подтверждение capture

Обзор и назначение /payments

Эндпоинт https://api.yookassa.ru/v3/payments — центральная точка YooKassa API v3 для приема оплат: создания операций, подтверждения (capture), получения статусов и отмены. Если вы ищете, как «создать платеж API v3», «подтверждение платежа YooKassa API» или «webhooks YooKassa payments», вы находитесь в нужном месте.

Кратко о задачах /payments:

  • создание платежа с указанием суммы, валюты, способа оплаты и параметров подтверждения;
  • управление жизненным циклом (получение статуса, подтверждение списания, отмена);
  • автоматическая синхронизация состояния через вебхуки.

Если вы только начинаете работу с новой версией, начните с обзора API: API v3: обзор.

Получить CloudPayments бесплатно

Эндпоинты API v3 и базовые операции

Ниже — основные операции над ресурсом payments. Базовый URL: https api yookassa ru v3 payments.

Метод Путь Назначение
POST /v3/payments Создать платеж
GET /v3/payments/{payment_id} Получить платеж по идентификатору
POST /v3/payments/{payment_id}/capture Подтвердить (списать) платеж, если при создании capture=false
POST /v3/payments/{payment_id}/cancel Отменить платеж до списания
GET /v3/payments Список платежей с фильтрами (по дате, статусу и т. п.)

Замечания:

  • Аутентификация — HTTP Basic с вашим идентификатором магазина и секретным ключом. Храните ключи только на сервере.
  • Идемпотентность — используйте заголовок Idempotence-Key для всех операций, которые могут быть повторно отправлены клиентом или ретраями.

Быстрый старт: создать платеж (API v3)

Создание платежа — это HTTP POST к /v3/payments. Минимально указываются amount, confirmation и способ оплаты. В большинстве сценариев вы задаете confirmation.type=redirect для перенаправления клиента и capture=true для авто-списания после успешной аутентификации.

Пример тела запроса (карта, редирект):

POST /v3/payments
Idempotence-Key: 8b95c3e1-...-4a67
Content-Type: application/json

{
  "amount": { "value": "1490.00", "currency": "RUB" },
  "capture": true,
  "confirmation": {
    "type": "redirect",
    "return_url": "https://example.com/return"
  },
  "payment_method_data": { "type": "bank_card" },
  "description": "Заказ №72",
  "metadata": { "order_id": "72" },
  "receipt": {
    "customer": { "email": "[email protected]" },
    "items": [
      { "description": "Подписка", "quantity": "1.00", "amount": { "value": "1490.00", "currency": "RUB" }, "vat_code": 1 }
    ]
  }
}

В ответ вы получите объект платежа с полем confirmation.confirmation_url. Направьте пользователя по этой ссылке для завершения шага банка/3‑D Secure. После успешной авторизации платеж перейдет в статус waiting_for_capture (если capture=false) или сразу succeeded (если capture=true).

Советы по созданию:

  • Для СБП используйте payment_method_data.type="sbp"; для других способов — соответствующий type.
  • Значение metadata помогает связать платеж с заказом в вашей системе.
  • Чек (receipt) добавляйте при необходимости фискализации.

Подтверждение платежа: клиентское и серверное

Слово «подтверждение» в YooKassa встречается в двух смыслах:

  1. Клиентское подтверждение (3‑D Secure, SberPay и т. д.) — происходит автоматически после редиректа по confirmation_url. Это часть пути клиента. Вы управляете только параметрами confirmation при создании платежа.

  2. Серверное подтверждение списания (capture) — ваш явный вызов POST /v3/payments/{payment_id}/capture, если при создании capture=false (предавторизация). Этот шаг списывает средства и завершает платеж.

Пример capture:

POST /v3/payments/2f9ab4d5-.../capture
Idempotence-Key: 3f2e...
Content-Type: application/json

{
  "amount": { "value": "1490.00", "currency": "RUB" },
  "transfers": [
    { "account_id": "partner_1", "amount": { "value": "200.00", "currency": "RUB" } }
  ]
}

Если вы решили не списывать средства, отмените платеж:

POST /v3/payments/{payment_id}/cancel

Когда использовать capture=false:

  • резервирование на складе и финальная проверка перед отгрузкой;
  • платежи с переменной конечной суммой (добавление доставки, модификации заказа);
  • антифрод‑проверки.

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

Платеж проходит несколько стадий. Ниже — краткий обзор. Детально статусы разъяснены на странице Статусы платежей.

Статус Когда возникает Что делать вам
pending Платеж создан, клиент еще не подтвердил Ожидать, держать заказ в состоянии «ожидание оплаты»
waiting_for_capture Клиент подтвердил, средства предавторизованы (если capture=false) Вызвать capture или cancel в течение срока жизни платежа
succeeded Средства списаны Отдавать товар/услугу, подтверждать заказ
canceled Платеж отменен (вами или системой/банком) Сообщить клиенту, предложить повторить оплату

Получить текущий статус можно запросом:

GET /v3/payments/{payment_id}

Списки платежей и фильтры помогут вам строить отчеты и дашборды:

GET /v3/payments?created_at.gte=2025-01-01T00:00:00Z&status=succeeded&limit=50

Webhooks YooKassa Payments

Чтобы не опрашивать API по таймеру, подписывайтесь на webhook‑уведомления по ключевым событиям. Типичные события:

  • payment.waiting_for_capture
  • payment.succeeded
  • payment.canceled

Сценарии обработки:

  • При payment.waiting_for_capture создавайте резервацию заказа и запускайте бек‑процессы проверки.
  • При payment.succeeded доставляйте цифровой товар, подтверждайте заказ, отправляйте чек клиенту.
  • При payment.canceled освобождайте резерв, показывайте пользователю возможность переоплаты.

Рекомендации по безопасности вебхуков:

  • Проверяйте подпись уведомления из заголовков (сравнивайте вычисленную подпись по телу запроса и вашему секретному ключу).
  • Обрабатывайте уведомления идемпотентно (по payment_id и event_id), чтобы повторные доставки не приводили к дублям.
  • Возвращайте 2xx при успешной обработке, иначе YooKassa может повторно отправить уведомление.

Если ваш сервер за балансерами/фаерволами, добавьте доверенные домены в список разрешенных: см. Домены и зеркала.

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

Ошибки делятся на клиентские (4xx) и серверные (5xx). Ниже — ориентиры и что проверять.

  • 400 Bad Request — некорректный запрос. Проверьте обязательные поля (amount, confirmation.type и т. д.), формат суммы (строка с двумя знаками после запятой), валидность JSON.
  • 401 Unauthorized — неверные учетные данные. Обновите Basic‑авторизацию, убедитесь, что используете рабочий ключ из ЛК.
  • 403 Forbidden — операция не разрешена магазину или способ отключен. Проверьте подключенные методы оплаты в ЛК.
  • 404 Not Found — неверный payment_id или ресурс не существует.
  • 409 Conflict — нарушение идемпотентности или конфликт состояния (например, повторный capture). Проверяйте текущий статус перед операцией.
  • 429 Too Many Requests — снизьте частоту запросов, реализуйте экспоненциальный бэкофф.
  • 500/502/504 — временные проблемы. Ретраи с идемпотентностью.

Типовая структура ошибки в ответе содержит код, сообщение и, возможно, поле parameter для указания ошибочного поля. Логируйте целиком тело ответа и заголовки корреляции, чтобы быстрее находить проблемы.

Подробнее о причинах отклонений и что делать бизнесу — в разделе Безопасность платежей.

Безопасность и лучшие практики

  • Идемпотентность везде, где возможны повторы: Idempotence-Key на создание, capture, cancel.
  • Не храните и не проксируйте карточные данные через ваш бэкенд. Используйте confirmation и метод оплаты, соответствующие требованиям PCI DSS.
  • Валидируйте суммы на сервере: сверяйте сумму из платежа, заказа и чеков.
  • Используйте webhooks как «источник истины» для финализации заказа.
  • Тайминги: не блокируйте UI в ожидании статуса. Показывайте «мы обрабатываем» и дождитесь webhook или результат запроса.
  • Логи и трассировка: сохраняйте payment_id, idempotence key, корреляционные идентификаторы.
  • Переподключение и актуализация методов: если вы расширяете список способов оплаты (например, СБП, кошельки, платежные ссылки), смотрите Ссылки, MY и счета и фронтовые сценарии Оплата на сайтах.

FAQ и советы по интеграции

  • Как понять, что клиент завершил оплату? — Отслеживайте webhooks и проверяйте GET /payments/{id}. Не полагайтесь только на возврат на return_url.
  • Нужно ли всегда делать capture? — Нет. Если capture=true при создании, списание произойдет автоматически. capture=false — для предавторизации и ручного списания.
  • Сколько живет предавторизация? — Зависит от способа оплаты и банка. Не откладывайте capture надолго; автоматическая отмена приведет к статусу canceled.
  • Как делать частичный возврат? — Возвраты работают через отдельный ресурс. См. подробности: Справка по возвратам.
  • Как увидеть платежи в ЛК? — Проверьте раздел «Платежи» в личном кабинете. См. Личный кабинет — возможности и вход: Вход в личный кабинет. Если есть сложности с доступом — Проблемы со входом.
  • Где пользователю проверить оплату? — Дайте ссылку на «Мои платежи», подробнее: My payments.

Полезные ссылки и что дальше

Заключение и CTA Интеграция с https://api.yookassa.ru/v3/payments дает вам гибкий контроль над приемом оплат: от простых редирект‑сценариев до предавторизации и распределения переводов. Стройте логику вокруг статусов и webhook‑уведомлений, используйте идемпотентность и не забывайте о безопасности — и ваш процессинг будет стабильным и прогнозируемым.

Готовы подключиться или расширить текущую интеграцию? Войдите в ЛК: Вход в личный кабинет и изучите инструменты: Личный кабинет — возможности. Если вы только планируете разработку — начните с API v3: обзор и вернитесь к этому руководству для реализации /payments.

Получить CloudPayments бесплатно