Эндпоинт https://api.yookassa.ru/v3/payments — центральная точка YooKassa API v3 для приема оплат: создания операций, подтверждения (capture), получения статусов и отмены. Если вы ищете, как «создать платеж API v3», «подтверждение платежа YooKassa API» или «webhooks YooKassa payments», вы находитесь в нужном месте.
Кратко о задачах /payments:
Если вы только начинаете работу с новой версией, начните с обзора API: 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 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": "user@example.com" },
"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).
Советы по созданию:
Слово «подтверждение» в YooKassa встречается в двух смыслах:
Клиентское подтверждение (3‑D Secure, SberPay и т. д.) — происходит автоматически после редиректа по confirmation_url. Это часть пути клиента. Вы управляете только параметрами confirmation при создании платежа.
Серверное подтверждение списания (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
Чтобы не опрашивать API по таймеру, подписывайтесь на webhook‑уведомления по ключевым событиям. Типичные события:
Сценарии обработки:
Рекомендации по безопасности вебхуков:
Если ваш сервер за балансерами/фаерволами, добавьте доверенные домены в список разрешенных: см. Домены и зеркала.
Ошибки делятся на клиентские (4xx) и серверные (5xx). Ниже — ориентиры и что проверять.
Типовая структура ошибки в ответе содержит код, сообщение и, возможно, поле parameter для указания ошибочного поля. Логируйте целиком тело ответа и заголовки корреляции, чтобы быстрее находить проблемы.
Подробнее о причинах отклонений и что делать бизнесу — в разделе Безопасность платежей.
Заключение и CTA Интеграция с https://api.yookassa.ru/v3/payments дает вам гибкий контроль над приемом оплат: от простых редирект‑сценариев до предавторизации и распределения переводов. Стройте логику вокруг статусов и webhook‑уведомлений, используйте идемпотентность и не забывайте о безопасности — и ваш процессинг будет стабильным и прогнозируемым.
Готовы подключиться или расширить текущую интеграцию? Войдите в ЛК: Вход в личный кабинет и изучите инструменты: Личный кабинет — возможности. Если вы только планируете разработку — начните с API v3: обзор и вернитесь к этому руководству для реализации /payments.