ЮKassa API на Python: создаём тестовый платёж и принимаем webhook

ЮKassa API можно освоить на одном небольшом проекте, если сразу видеть вход, действие и результат. Тестовый магазин позволяет пройти полный цикл платежа без реального списания: создание, переход по ссылке, уведомление и проверка статуса. Ниже вы соберёте работающий пример и проверите обычный и граничный сценарии.

Опасно считать оплату успешной только после возврата браузера или доверять любому JSON, который пришёл на webhook. Поэтому отделим настройку, входные данные, основное действие и проверку. В этой статье вы соберёте FastAPI-приложение, которое создаёт платёж с idempotence key и принимает событие payment.succeeded. Проверка: два повтора одной операции не создают дубликат, confirmation URL открывается, а webhook сверяет платёж через API.

Как устроен учебный проект ЮKassa API

ЮKassa API разделяет подготовку, основное действие, проверку ответа и сохранение результата. Держите ввод, логику и отображение раздельно: тогда каждый этап можно проверить отдельно.

Контрольные точки: создание, идемпотентность, webhook и проверка. Следующий шаг начинается после совпадения с ожидаемым результатом.

От входных данных до видимого результата. Сначала проверяется вход, затем действие и только потом интерфейс.

Собираем рабочий пример шаг за шагом

Материал сверялся с официальной документацией сервиса 21 октября 2026 года. Установите yookassa, fastapi и uvicorn. SHOP_ID и SECRET_KEY задайте через окружение. Проверьте текущую папку через pwd или Get-Location. Вставьте пример целиком, выполните один раз, затем разбирайте по частям.

import os
import uuid
from fastapi import FastAPI, Request
from yookassa import Configuration, Payment

Configuration.account_id = os.environ["YOOKASSA_SHOP_ID"]
Configuration.secret_key = os.environ["YOOKASSA_SECRET_KEY"]
app = FastAPI()

@app.post("/payments")
def create_payment():
    payment = Payment.create({
        "amount": {"value": "100.00", "currency": "RUB"},
        "confirmation": {"type": "redirect", "return_url": "https://example.test/thanks"},
        "capture": True,
        "description": "Учебный заказ CODIK-101",
        "metadata": {"order_id": "CODIK-101"},
    }, str(uuid.uuid4()))
    return {"id": payment.id, "url": payment.confirmation.confirmation_url}

@app.post("/webhook/yookassa")
async def webhook(request: Request):
    event = await request.json()
    payment_id = event.get("object", {}).get("id")
    if event.get("event") == "payment.succeeded" and payment_id:
        payment = Payment.find_one(payment_id)
        if payment.status == "succeeded":
            print("paid order:", payment.metadata.get("order_id"))
    return {"ok": True}

Код держит подготовку отдельно от внешнего действия, поэтому ошибку можно найти на конкретном шаге. Найдите в примере вход, проверку и место формирования результата.

Что отличает устойчивый проект от случайного запуска. Явные границы делают ошибку локальной и понятной.

Что происходит внутри и почему это работает

Ключ идемпотентности связывает повтор запроса с одной операцией. Redirect нужен пользователю, webhook сообщает серверу событие, а финальная проверка API подтверждает состояние. Логику держите отдельно от вывода: функция получает аргумент и возвращает значение, а интерфейс показывает его. Секреты и персональные данные не должны попадать в репозиторий, журнал или публичный скриншот.

Webhook может прийти повторно или не по порядку. Храните payment id и текущий статус заказа, делайте обновление идемпотентным и не выдавайте товар повторно. Не прячьте поток в одном обработчике: сохраните вход, проверьте его, вызовите операцию и только затем обновите интерфейс.

Проверяем проект и добавляем свою функцию

Добавьте таблицу заказов со статусами pending и paid, затем свяжите metadata.order_id с конкретной записью. До правки запишите ожидаемое поведение одним предложением. После граничного теста повторите обычный сценарий.

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

Четыре проверки перед следующим шагом. Каждый следующий этап начинается после наблюдаемого результата.

Что запомнить и куда двигаться дальше

Перед боевым запуском настройте HTTPS, журнал событий без секретов, возвраты и сверку суммы, валюты и order_id. Для закрепления откройте в первом API на FastAPI, в REST API на Express и в проверке JSON через Pydantic.

Как изучить тему в Кодике

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

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

Что получится в итоге

Финальный экран показывает результат, состояние запроса и понятное сообщение об ошибке без раскрытия секретов.