Неофициальный, полностью асинхронный клиент для работы с платежным сервисом ЮKassa (YooKassa).
Библиотека разработана с использованием современных возможностей Python, опираясь на официальную документацию API и структуру официального SDK, но переписана с нуля для обеспечения максимальной производительности и удобства использования в асинхронных приложениях.
- Полная асинхронность: Использует
httpxдля неблокирующих HTTP-запросов. - Type-Safe: Строгая типизация с использованием Pydantic v2. Весь код покрыт тайп-хинтами.
- Современный API: Удобный интерфейс через контекстный менеджер
async with. - Модульность: Структурированная архитектура, отдельные сервисы для каждой сущности API (Платежи, Возвраты, Чеки и т.д.).
- Надежность: Автоматическая обработка ошибок и повтор запросов (idempotency support).
Библиотека доступна в PyPI и может быть установлена с помощью любого пакетного менеджера.
pip install async_yookassapoetry add async_yookassauv add async_yookassaДля начала работы вам понадобятся Shop ID и Secret Key из личного кабинета ЮКассы.
import asyncio
from async_yookassa import YooKassaClient
from async_yookassa.models.payment import PaymentRequest, Amount, RedirectConfirmationRequest
async def main():
async with YooKassaClient(account_id="<SHOP_ID>", secret_key="<SECRET_KEY>") as client:
# Создаем объект запроса
request = PaymentRequest(
amount=Amount(value="100.00", currency="RUB"),
confirmation=RedirectConfirmationRequest(
type="redirect",
return_url="https://example.com/return"
),
description="Заказ №1",
capture=True
)
# Отправляем запрос
payment = await client.payment.create(request)
print(f"Платеж создан: {payment.id}")
print(f"Ссылка на оплату: {payment.confirmation.confirmation_url}")
if __name__ == "__main__":
asyncio.run(main())Библиотека поддерживает два способа аутентификации.
Используется shopId и secretKey.
client = YooKassaClient(account_id="123456", secret_key="live_...")Используется OAuth-токен.
client = YooKassaClient(auth_token="<OAUTH_TOKEN>")При инициализации YooKassaClient можно передать дополнительные параметры:
from async_yookassa import YooKassaClient
from httpx import AsyncClient
custom_httpx_client = AsyncClient()
client = YooKassaClient(
account_id="...",
secret_key="...",
timeout=60, # Таймаут запроса в секундах (по умолчанию 30)
api_url="https://api.yookassa.ru/v3", # URL API (по умолчанию продакшн)
http_client=custom_httpx_client # Свой экземпляр AsyncClient (опционально)
)Обратите внимание: Если вы передаете свой http_client, вы сами несете ответственность за его закрытие. При
использовании async with клиент async_yookassa закроет переданный http_client только если он был создан внутри (
т.е. http_client=None).
Все взаимодействие с API происходит через соответствующие сервисы внутри клиента.
Управление платежами: создание, подтверждение, отмена, получение информации.
# Получение списка платежей
payments = await client.payment.list(limit=10)
# Получение информации о платеже
payment = await client.payment.find_one("2be00000-00000-00000000")
# Подтверждение платежа (холдирование)
await client.payment.capture("2be00000-00000-00000000")
# Отмена платежа
await client.payment.cancel("2be00000-00000-00000000")Осуществление возвратов средств пользователям.
from async_yookassa.models.refund import RefundRequest, Amount
refund = await client.refund.create(
RefundRequest(
payment_id="2be00000-00000-00000000",
amount=Amount(value="50.00", currency="RUB"),
description="Возврат части средств"
)
)Работа с чеками для 54-ФЗ.
from async_yookassa.models.receipt import ReceiptRequest, ReceiptType, Customer, ReceiptItem, SettlementReceipt
receipt = await client.receipt.create(
ReceiptRequest(
customer=Customer(email="user@example.com"),
type=ReceiptType.payment,
send=True,
items=[
ReceiptItem(description="Товар 1", quantity="1", amount=Amount(value="100.00", currency="RUB"), vat_code=1)
],
settlements=[SettlementReceipt(...)]
)
)Управление подписками на уведомления о событиях.
from async_yookassa.models.webhook import WebhookRequest, WebhookEvent
# Подписка на уведомление о успешной оплате
webhook = await client.webhook.create(
WebhookRequest(
event=WebhookEvent.PAYMENT_SUCCEEDED,
url="https://example.com/webhook"
)
)
# Список активных вебхуков
webhooks = await client.webhook.list()| Сервис | Описание | Доступ через |
|---|---|---|
| Сделки | Безопасная сделка | client.deal |
| Счета | Выставление счетов | client.invoice |
| Выплаты | Выплаты на карты | client.payout |
| Способы оплаты | Сохраненные карты | client.payment_methods |
| Настройки | Информация о магазине | client.me |
| СБП | Банки участники | client.sbp_bank |
Если вы используете DI-фреймворк, например dishka, вы можете зарегистрировать клиент как провайдер.
from dishka import Provider, Scope, provide
from async_yookassa import YooKassaClient
class PaymentsProvider(Provider):
@provide(scope=Scope.APP)
async def get_client(self) -> YooKassaClient:
return YooKassaClient(
account_id="<ID>",
secret_key="<KEY>"
)Библиотека разделена на модули для удобства:
async_yookassa.client— Основной клиентYooKassaClient.async_yookassa.models— Pydantic модели запросов и ответов.async_yookassa.services— Реализация логики работы с API (методыcreate,listи т.д.).async_yookassa.exceptions— Типизированные исключения.
Если вы нашли баг или хотите добавить новую фичу:
- Создайте Issue с описанием.
- Форкните репозиторий.
- Внесите изменения и отправьте Pull Request.
Библиотека написана в рамках проекта "Код на салфетке":
- Сайт: https://pressanybutton.ru/
- Telegram-канал: https://t.me/press_any_button
Если вам нравится этот проект и вы хотите поддержать его дальнейшее развитие, рассмотрите возможность доната:
Проект распространяется под лицензией MIT. Подробнее см. файл LICENSE.