### Dishka DI Integration with Async YooKassa for FastAPI

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Shows how to integrate the async_yookassa client into a FastAPI application using the Dishka dependency injection framework. This example defines a provider for the YooKassaClient and uses it in a FastAPI endpoint.

```python
from dishka import Provider, Scope, provide
from async_yookassa import YooKassaClient

class PaymentsProvider(Provider):
    @provide(scope=Scope.APP)
    async def get_yookassa_client(self) -> YooKassaClient:
        return YooKassaClient(
            account_id="123456",
            secret_key="live_secret_key"
        )

# Usage in FastAPI with Dishka
from fastapi import FastAPI
from dishka.integrations.fastapi import setup_dishka, FromDishka

app = FastAPI()

@app.post("/payments")
async def create_payment(
    client: FromDishka[YooKassaClient],
    amount: float,
    description: str
):
    from async_yookassa.models.payment import PaymentRequest, Amount, RedirectConfirmationRequest

    payment = await client.payment.create(
        PaymentRequest(
            amount=Amount(value=str(amount), currency="RUB"),
            confirmation=RedirectConfirmationRequest(
                type="redirect",
                return_url="https://example.com/return"
            ),
            description=description
        )
    )
    return {"payment_id": payment.id, "url": payment.confirmation.confirmation_url}

# Setup DI
container = make_async_container(PaymentsProvider())
setup_dishka(container, app)
```

--------------------------------

### Manage Refunds: Get and List (Python)

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Retrieves information about a specific refund using its ID or lists all refunds with filtering options like status and limit. Requires the async_yookassa library.

```python
import asyncio
from async_yookassa import YooKassaClient
from async_yookassa.models.refund import RefundListOptions

async def manage_refunds():
    async with YooKassaClient(account_id="123456", secret_key="secret") as client:
        # Get specific refund
        refund = await client.refund.find_one("2be10000-0000-0000-0000-000000000001")
        print(f"Refund {refund.id}: {refund.status}")

        # List refunds with filter
        refunds = await client.refund.list(
            RefundListOptions(limit=20, status="succeeded")
        )
        print(f"Total refunds: {len(refunds.items)}")
        for r in refunds.items:
            print(f"  - {r.id}: {r.amount.value} {r.amount.currency} ({r.status})")

asyncio.run(manage_refunds())
```

--------------------------------

### Payout Service: Get and List Payouts with Async Yookassa

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Retrieves specific payout information by ID and lists payouts with optional filtering using the async_yookassa library. Requires account ID and secret key for client initialization.

```python
import asyncio
from async_yookassa import YooKassaClient
from async_yookassa.models.payout import PayoutListOptions

async def manage_payouts():
    async with YooKassaClient(account_id="123456", secret_key="secret") as client:
        # Get specific payout
        payout = await client.payout.find_one("po-2be00000-0000-0000-0000-000000000001")
        print(f"Payout {payout.id}: {payout.status}")

        # List payouts
        payouts = await client.payout.list(PayoutListOptions(limit=10))
        print(f"Total payouts: {len(payouts.items)}")
        for p in payouts.items:
            print(f"  - {p.id}: {p.amount.value} {p.amount.currency}")

asyncio.run(manage_payouts())
```

--------------------------------

### Get Shop Information with YooKassa API (Python)

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Retrieves and displays information about the current shop or merchant account using the YooKassa Python SDK. It requires account ID and secret key for client initialization. The function fetches shop details including account ID, name, status, test mode, and fiscalization status.

```python
import asyncio
from async_yookassa import YooKassaClient

async def get_shop_info():
    async with YooKassaClient(account_id="123456", secret_key="secret") as client:
        me = await client.me.get_me()

        print(f"Account ID: {me.account_id}")
        print(f"Shop name: {me.name}")
        print(f"Status: {me.status}")
        print(f"Test mode: {me.test}")
        if me.fiscalization_enabled:
            print("Fiscalization: Enabled")

asyncio.run(get_shop_info())
```

--------------------------------

### Initialize YooKassaClient with Basic Auth or OAuth in Python

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Demonstrates how to initialize the YooKassaClient using either Basic Authentication with shop credentials or OAuth token. It utilizes the async context manager for proper resource management and shows how to access different service modules.

```python
import asyncio
from async_yookassa import YooKassaClient

async def main():
    # Basic Auth with shop credentials
    async with YooKassaClient(
        account_id="123456",
        secret_key="live_your_secret_key",
        timeout=60,  # Optional: request timeout in seconds (default: 30)
    ) as client:
        # Access services
        me = await client.me.get_me()
        print(f"Shop name: {me.name}")
        print(f"Account ID: {me.account_id}")

    # OAuth authentication (for platforms)
    async with YooKassaClient(auth_token="oauth_token_here") as client:
        me = await client.me.get_me()
        print(f"Shop status: {me.status}")

if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Create a Payment using YooKassaClient in Python

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Shows how to create a new payment request using the YooKassaClient. It includes details on specifying the amount, currency, confirmation method (redirect), return URL, description, and optional metadata. The payment is set for automatic capture.

```python
import asyncio
from async_yookassa import YooKassaClient
from async_yookassa.models.payment import (
    PaymentRequest,
    Amount,
    RedirectConfirmationRequest,
)

async def create_payment():
    async with YooKassaClient(account_id="123456", secret_key="secret") as client:
        request = PaymentRequest(
            amount=Amount(value="1500.00", currency="RUB"),
            confirmation=RedirectConfirmationRequest(
                type="redirect",
                return_url="https://example.com/payment/success"
            ),
            description="Order #12345 - Premium subscription",
            capture=True,  # Auto-capture payment
            metadata={"order_id": "12345", "user_id": "user_789"}
        )

        payment = await client.payment.create(request)

        print(f"Payment ID: {payment.id}")
        print(f"Status: {payment.status}")
        print(f"Confirmation URL: {payment.confirmation.confirmation_url}")
        # Expected output:
        # Payment ID: 2be00000-0000-0000-0000-000000000001
        # Status: pending
        # Confirmation URL: https://yoomoney.ru/checkout/payments/v2/...

asyncio.run(create_payment())

```

--------------------------------

### Create Idempotent Payment with Async YooKassa

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Demonstrates how to use idempotency keys to safely create payments with the async_yookassa library. This prevents duplicate transactions when retrying requests. It requires the `async_yookassa` library and `uuid` for key generation.

```python
import asyncio
import uuid
from async_yookassa import YooKassaClient
from async_yookassa.models.payment import PaymentRequest, Amount, RedirectConfirmationRequest

async def create_idempotent_payment():
    async with YooKassaClient(account_id="123456", secret_key="secret") as client:
        # Generate a unique idempotency key (e.g., based on order ID)
        idempotency_key = uuid.uuid5(uuid.NAMESPACE_DNS, "order-12345")

        request = PaymentRequest(
            amount=Amount(value="1500.00", currency="RUB"),
            confirmation=RedirectConfirmationRequest(
                type="redirect",
                return_url="https://example.com/return"
            ),
            description="Order #12345"
        )

        # First request creates the payment
        payment = await client.payment.create(request, idempotency_key=idempotency_key)
        print(f"Created payment: {payment.id}")

        # Retry with same key returns the same payment (no duplicate)
        same_payment = await client.payment.create(request, idempotency_key=idempotency_key)
        print(f"Same payment: {same_payment.id}")

        assert payment.id == same_payment.id  # Both are the same

asyncio.run(create_idempotent_payment())
```

--------------------------------

### Create Refund (Python)

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Creates a refund for a completed payment, supporting both full and partial refunds. Requires payment ID, amount, currency, and an optional description. Uses the async_yookassa library.

```python
import asyncio
from async_yookassa import YooKassaClient
from async_yookassa.models.refund import RefundRequest, Amount

async def create_refund():
    async with YooKassaClient(account_id="123456", secret_key="secret") as client:
        # Full refund
        refund = await client.refund.create(
            RefundRequest(
                payment_id="2be00000-0000-0000-0000-000000000001",
                amount=Amount(value="1500.00", currency="RUB"),
                description="Customer requested refund"
            )
        )

        print(f"Refund ID: {refund.id}")
        print(f"Status: {refund.status}")
        print(f"Amount: {refund.amount.value} {refund.amount.currency}")
        # Expected output:
        # Refund ID: 2be10000-0000-0000-0000-000000000001
        # Status: succeeded
        # Amount: 1500.00 RUB

asyncio.run(create_refund())
```

--------------------------------

### Deal Service: Safe Deals (Escrow) with Async Yookassa

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Creates and manages safe deals for marketplace scenarios using the async_yookassa library. Funds are held until deal completion. Requires account ID and secret key. Supports creating, retrieving, and listing deals.

```python
import asyncio
from async_yookassa import YooKassaClient
from async_yookassa.models.deal import DealRequest, DealListOptions
from async_yookassa.enums.deal_enums import DealTypeEnum, DealFeeMomentEnum

async def manage_deals():
    async with YooKassaClient(account_id="123456", secret_key="secret") as client:
        # Create a safe deal
        deal = await client.deal.create(
            DealRequest(
                type=DealTypeEnum.safe_deal,
                fee_moment=DealFeeMomentEnum.deal_closed,
                description="Marketplace order #12345",
                metadata={"seller_id": "seller_001", "buyer_id": "buyer_002"}
            )
        )

        print(f"Deal ID: {deal.id}")
        print(f"Status: {deal.status}")
        print(f"Type: {deal.type}")

        # Get deal information
        deal_info = await client.deal.find_one(deal.id)
        print(f"Deal balance: {deal_info.balance.value} {deal_info.balance.currency}")

        # List deals
        deals = await client.deal.list(DealListOptions(limit=10, status="opened"))
        print(f"Open deals: {len(deals.items)}")

asyncio.run(manage_deals())
```

--------------------------------

### Manage Customer Personal Data with YooKassa API (Python)

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Demonstrates how to create and retrieve personal data records for SBP payouts using the YooKassa Python SDK. It requires account ID and secret key for client initialization. The function handles SBPPersonalDataRequest and prints the ID and status of the created record, then retrieves and prints its type.

```python
import asyncio
from async_yookassa import YooKassaClient
from async_yookassa.models.personal_data import SBPPersonalDataRequest

async def manage_personal_data():
    async with YooKassaClient(account_id="123456", secret_key="secret") as client:
        # Create personal data record for SBP payouts
        data = await client.personal_data.create(
            SBPPersonalDataRequest(
                type="sbp_payout_recipient",
                first_name="Ivan",
                last_name="Petrov",
                middle_name="Sergeevich"
            )
        )

        print(f"Personal Data ID: {data.id}")
        print(f"Status: {data.status}")

        # Retrieve personal data
        retrieved = await client.personal_data.find_one(data.id)
        print(f"Data type: {retrieved.type}")

asyncio.run(manage_personal_data())
```

--------------------------------

### Payout Service - Create Payout

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Creates payouts to send money to user bank cards, wallets, or bank accounts.

```APIDOC
## POST /payouts

### Description
Creates payouts to send money to user bank cards, wallets, or bank accounts.

### Method
POST

### Endpoint
/payouts

### Parameters
#### Request Body
- **amount** (object) - Required - The amount to be paid out.
  - **value** (string) - Required - The monetary value.
  - **currency** (string) - Required - The currency code (e.g., 'RUB').
- **payout_destination_data** (object) - Required - Details about the payout destination.
  - **type** (string) - Required - The type of destination (e.g., 'bank_card', 'mobile_balance', 'digital_wallet').
  - **card** (object) - Required if type is 'bank_card'.
    - **number** (string) - Required - The bank card number.
- **description** (string) - Optional - A description for the payout.
- **metadata** (object) - Optional - Custom data to associate with the payout.

### Request Example
```json
{
  "amount": {
    "value": "5000.00",
    "currency": "RUB"
  },
  "payout_destination_data": {
    "type": "bank_card",
    "card": {
      "number": "4111111111111111"
    }
  },
  "description": "Seller payout for order #12345",
  "metadata": {
    "order_id": "12345"
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the payout.
- **status** (string) - The status of the payout (e.g., 'pending').
- **amount** (object) - The amount of the payout.
  - **value** (string) - The monetary value.
  - **currency** (string) - The currency code.

#### Response Example
```json
{
  "id": "po-2be00000-0000-0000-0000-000000000001",
  "status": "pending",
  "amount": {
    "value": "5000.00",
    "currency": "RUB"
  }
}
```
```

--------------------------------

### Create Payout (Python)

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Initiates a payout to a user's bank card, wallet, or bank account. This function requires the payout amount, destination details, and an optional description and metadata. It returns the payout ID, status, and amount.

```python
import asyncio
from async_yookassa import YooKassaClient
from async_yookassa.models.payout import PayoutRequest
from async_yookassa.models.payment import Amount

async def create_payout():
    async with YooKassaClient(account_id="123456", secret_key="secret") as client:
        payout = await client.payout.create(
            PayoutRequest(
                amount=Amount(value="5000.00", currency="RUB"),
                payout_destination_data={
                    "type": "bank_card",
                    "card": {
                        "number": "4111111111111111"
                    }
                },
                description="Seller payout for order #12345",
                metadata={"order_id": "12345"}
            )
        )

        print(f"Payout ID: {payout.id}")
        print(f"Status: {payout.status}")
        print(f"Amount: {payout.amount.value} {payout.amount.currency}")
        # Expected output:
        # Payout ID: po-2be00000-0000-0000-0000-000000000001
        # Status: pending
        # Amount: 5000.00 RUB

asyncio.run(create_payout())
```

--------------------------------

### Invoice Service: Create and Manage Invoices with Async Yookassa

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Creates invoices for payment requests that can be sent to customers using the async_yookassa library. Supports creating and retrieving invoice details. Requires account ID and secret key.

```python
import asyncio
from async_yookassa import YooKassaClient
from async_yookassa.models.invoice import InvoiceRequest
from async_yookassa.models.payment import Amount

async def manage_invoices():
    async with YooKassaClient(account_id="123456", secret_key="secret") as client:
        # Create invoice
        invoice = await client.invoice.create(
            InvoiceRequest(
                cart=[
                    {
                        "description": "Consulting services",
                        "quantity": "2",
                        "amount": Amount(value="5000.00", currency="RUB")
                    }
                ],
                delivery_method={
                    "type": "email",
                    "email": "customer@example.com"
                },
                metadata={"project_id": "project_123"}
            )
        )

        print(f"Invoice ID: {invoice.id}")
        print(f"Status: {invoice.status}")

        # Get invoice
        invoice_info = await client.invoice.find_one(invoice.id)
        print(f"Invoice details: {invoice_info.id}")

asyncio.run(manage_invoices())
```

--------------------------------

### Retrieve Payment Information using YooKassaClient in Python

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Demonstrates how to fetch detailed information about a specific payment using its unique ID. The code retrieves and prints details such as payment ID, status, amount, creation timestamp, paid status, and payment method type.

```python
import asyncio
from async_yookassa import YooKassaClient

async def get_payment():
    async with YooKassaClient(account_id="123456", secret_key="secret") as client:
        payment = await client.payment.find_one("2be00000-0000-0000-0000-000000000001")

        print(f"Payment ID: {payment.id}")
        print(f"Status: {payment.status}")
        print(f"Amount: {payment.amount.value} {payment.amount.currency}")
        print(f"Created: {payment.created_at}")
        print(f"Paid: {payment.paid}")
        if payment.payment_method:
            print(f"Payment method: {payment.payment_method.type}")
        # Expected output:
        # Payment ID: 2be00000-0000-0000-0000-000000000001
        # Status: succeeded
        # Amount: 1500.00 RUB
        # Created: 2024-01-15T10:30:00.000Z
        # Paid: True
        # Payment method: bank_card

asyncio.run(get_payment())

```

--------------------------------

### List Payments with Filtering (Python)

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Retrieves a paginated list of payments with optional filtering by status and other parameters. It demonstrates basic listing and pagination using cursors. Requires the async_yookassa library.

```python
import asyncio
from async_yookassa import YooKassaClient
from async_yookassa.models.payment import PaymentListOptions

async def list_payments():
    async with YooKassaClient(account_id="123456", secret_key="secret") as client:
        # List recent payments with limit
        payments = await client.payment.list(
            PaymentListOptions(limit=10, status="succeeded")
        )

        print(f"Total payments: {len(payments.items)}")
        for payment in payments.items:
            print(f"  - {payment.id}: {payment.amount.value} {payment.amount.currency}")

        # Pagination with cursor
        if payments.next_cursor:
            next_page = await client.payment.list(
                PaymentListOptions(cursor=payments.next_cursor, limit=10)
            )
            print(f"Next page: {len(next_page.items)} payments")

asyncio.run(list_payments())
```

--------------------------------

### Manage Webhooks (Python)

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Manages webhook subscriptions for receiving real-time notifications about payment events. This function demonstrates creating webhooks for specific events, listing existing webhooks, and deleting them. It requires a valid URL for receiving notifications.

```python
import asyncio
from async_yookassa import YooKassaClient
from async_yookassa.models.webhook import WebhookRequest, WebhookEvent

async def manage_webhooks():
    async with YooKassaClient(account_id="123456", secret_key="secret") as client:
        # Create webhook for successful payments
        webhook = await client.webhook.create(
            WebhookRequest(
                event=WebhookEvent.PAYMENT_SUCCEEDED,
                url="https://example.com/webhooks/payment-success"
            )
        )
        print(f"Created webhook: {webhook.id}")

        # Create webhook for refunds
        refund_webhook = await client.webhook.create(
            WebhookRequest(
                event=WebhookEvent.REFUND_SUCCEEDED,
                url="https://example.com/webhooks/refund"
            )
        )
        print(f"Refund webhook: {refund_webhook.id}")

        # List all webhooks
        webhooks = await client.webhook.list()
        print(f"Active webhooks: {len(webhooks.items)}")
        for wh in webhooks.items:
            print(f"  - {wh.id}: {wh.event} -> {wh.url}")

        # Delete webhook
        await client.webhook.delete(webhook.id)
        print(f"Deleted webhook: {webhook.id}")

# Available webhook events:
# WebhookEvent.PAYMENT_WAITING_FOR_CAPTURE
# WebhookEvent.PAYMENT_SUCCEEDED
# WebhookEvent.PAYMENT_CANCELED
# WebhookEvent.REFUND_SUCCEEDED
# WebhookEvent.PAYOUT_SUCCEEDED
# WebhookEvent.PAYOUT_CANCELED
# WebhookEvent.DEAL_CLOSED

asyncio.run(manage_webhooks())
```

--------------------------------

### Webhook Service - Manage Webhooks

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Manages webhook subscriptions for receiving real-time notifications about payment events. Allows creating, listing, and deleting webhooks.

```APIDOC
## Webhook Management

### Description
Manages webhook subscriptions for receiving real-time notifications about payment events. Allows creating, listing, and deleting webhooks.

### Method
POST (create), GET (list), DELETE (delete)

### Endpoint
/webhooks

### Parameters
#### Create Webhook
##### Request Body
- **event** (string) - Required - The event to subscribe to (e.g., 'PAYMENT_SUCCEEDED', 'REFUND_SUCCEEDED').
- **url** (string) - Required - The URL to send notifications to.

#### List Webhooks
No specific parameters required for listing.

#### Delete Webhook
##### Path Parameters
- **webhook_id** (string) - Required - The ID of the webhook to delete.

### Request Example (Create)
```json
{
  "event": "PAYMENT_SUCCEEDED",
  "url": "https://example.com/webhooks/payment-success"
}
```

### Response
#### Success Response (200 - Create/List)
- **id** (string) - The unique identifier for the webhook.
- **event** (string) - The event the webhook is subscribed to.
- **url** (string) - The URL the webhook notifications are sent to.

#### Success Response (204 - Delete)
No content on successful deletion.

#### Response Example (List)
```json
{
  "items": [
    {
      "id": "wh-12345",
      "event": "PAYMENT_SUCCEEDED",
      "url": "https://example.com/webhooks/payment-success"
    },
    {
      "id": "wh-67890",
      "event": "REFUND_SUCCEEDED",
      "url": "https://example.com/webhooks/refund"
    }
  ],
  "type": "list"
}
```

### Available Webhook Events
- `PAYMENT_WAITING_FOR_CAPTURE`
- `PAYMENT_SUCCEEDED`
- `PAYMENT_CANCELED`
- `REFUND_SUCCEEDED`
- `PAYOUT_SUCCEEDED`
- `PAYOUT_CANCELED`
- `DEAL_CLOSED`
```

--------------------------------

### Payment Methods Service: Saved Payment Methods with Async Yookassa

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Manages saved payment methods for returning customers using the async_yookassa library. Allows retrieving details of a specific saved payment method. Requires account ID and secret key.

```python
import asyncio
from async_yookassa import YooKassaClient
from async_yookassa.models.payment_method import PaymentMethodRequest

async def manage_payment_methods():
    async with YooKassaClient(account_id="123456", secret_key="secret") as client:
        # Get saved payment method
        method = await client.payment_methods.find_one("pm-2be00000-0000-0000-0000-000000000001")

        print(f"Payment Method ID: {method.id}")
        print(f"Type: {method.type}")
        print(f"Saved: {method.saved}")
        if hasattr(method, 'card') and method.card:
            print(f"Card: **** {method.card.last4}")
            print(f"Expiry: {method.card.expiry_month}/{method.card.expiry_year}")

asyncio.run(manage_payment_methods())
```

--------------------------------

### List SBP Banks with YooKassa API (Python)

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Fetches and displays a list of banks participating in Russia's Faster Payments System (SBP) using the YooKassa Python SDK. It requires account ID and secret key for client initialization. The function retrieves all SBP banks and prints the total count and details of the first five banks.

```python
import asyncio
from async_yookassa import YooKassaClient

async def list_sbp_banks():
    async with YooKassaClient(account_id="123456", secret_key="secret") as client:
        banks = await client.sbp_bank.list()

        print(f"Total SBP banks: {len(banks.items)}")
        for bank in banks.items[:5]:  # Show first 5
            print(f"  - {bank.bank_id}: {bank.name}")
        # Expected output:
        # Total SBP banks: 150+
        #   - 100000000001: Sberbank
        #   - 100000000004: Tinkoff Bank
        #   - ...

asyncio.run(list_sbp_banks())
```

--------------------------------

### Personal Data Service - Manage Customer Data

Source: https://context7.com/prodreams/async_yookassa/llms.txt

This endpoint allows for the creation and retrieval of personal data records, essential for payouts and compliance purposes.

```APIDOC
## POST /api/personal_data

### Description
Stores and retrieves personal data for payouts and compliance.

### Method
POST

### Endpoint
/api/personal_data

### Parameters
#### Request Body
- **type** (string) - Required - Type of personal data record (e.g., "sbp_payout_recipient")
- **first_name** (string) - Required - The first name of the individual.
- **last_name** (string) - Required - The last name of the individual.
- **middle_name** (string) - Optional - The middle name of the individual.

### Request Example
```json
{
  "type": "sbp_payout_recipient",
  "first_name": "Ivan",
  "last_name": "Petrov",
  "middle_name": "Sergeevich"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created personal data record.
- **status** (string) - The current status of the personal data record.

#### Response Example
```json
{
  "id": "pd_12345abcde",
  "status": "valid"
}
```

## GET /api/personal_data/{id}

### Description
Retrieves a specific personal data record by its ID.

### Method
GET

### Endpoint
/api/personal_data/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the personal data record to retrieve.

### Response
#### Success Response (200)
- **type** (string) - The type of the personal data record.
- **first_name** (string) - The first name of the individual.
- **last_name** (string) - The last name of the individual.
- **middle_name** (string) - The middle name of the individual.

#### Response Example
```json
{
  "type": "sbp_payout_recipient",
  "first_name": "Ivan",
  "last_name": "Petrov",
  "middle_name": "Sergeevich"
}
```
```

--------------------------------

### Capture Payment (Two-Stage Payments) (Python)

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Captures a previously authorized payment, supporting both full and partial captures. This is essential for two-stage payment flows. Requires the async_yookassa library and payment IDs.

```python
import asyncio
from async_yookassa import YooKassaClient
from async_yookassa.models.payment import CapturePaymentRequest, Amount

async def capture_payment():
    async with YooKassaClient(account_id="123456", secret_key="secret") as client:
        # Capture full amount
        payment = await client.payment.capture("2be00000-0000-0000-0000-000000000001")
        print(f"Captured: {payment.status}")

        # Capture partial amount
        capture_request = CapturePaymentRequest(
            amount=Amount(value="1000.00", currency="RUB")
        )
        payment = await client.payment.capture(
            "2be00000-0000-0000-0000-000000000002",
            params=capture_request
        )
        print(f"Partial capture: {payment.amount.value} {payment.amount.currency}")
        # Expected output:
        # Captured: succeeded
        # Partial capture: 1000.00 RUB

asyncio.run(capture_payment())
```

--------------------------------

### Me Service - Shop Information

Source: https://context7.com/prodreams/async_yookassa/llms.txt

This endpoint provides detailed information about the authenticated shop or merchant account, including its ID, name, status, and fiscalization settings.

```APIDOC
## GET /api/me

### Description
Retrieves information about the current shop/merchant account.

### Method
GET

### Endpoint
/api/me

### Parameters
None

### Response
#### Success Response (200)
- **account_id** (string) - The unique identifier for the shop account.
- **name** (string) - The name of the shop.
- **status** (string) - The current status of the shop account (e.g., 'active', 'blocked').
- **test** (boolean) - Indicates if the account is in test mode.
- **fiscalization_enabled** (boolean) - Indicates if fiscalization is enabled for the shop.

#### Response Example
```json
{
  "account_id": "12345678",
  "name": "My Awesome Shop",
  "status": "active",
  "test": true,
  "fiscalization_enabled": true
}
```
```

--------------------------------

### Receipt Service - Create Receipt

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Creates fiscal receipts for Russian tax compliance (54-FZ law). This is required for businesses operating in Russia.

```APIDOC
## POST /receipts

### Description
Creates fiscal receipts for Russian tax compliance (54-FZ law).

### Method
POST

### Endpoint
/receipts

### Parameters
#### Request Body
- **type** (string) - Required - Type of the receipt (e.g., 'payment', 'refund').
- **payment_id** (string) - Required (if type is 'payment') - The ID of the payment the receipt is for.
- **refund_id** (string) - Required (if type is 'refund') - The ID of the refund the receipt is for.
- **customer** (object) - Required - Customer details.
  - **email** (string) - Optional - Customer's email address.
  - **phone** (string) - Optional - Customer's phone number.
- **items** (array) - Required - List of items included in the receipt.
  - **description** (string) - Required - Description of the item.
  - **quantity** (string) - Required - Quantity of the item.
  - **amount** (object) - Required - Amount for the item.
    - **value** (string) - Required - The monetary value.
    - **currency** (string) - Required - The currency code (e.g., 'RUB').
  - **vat_code** (integer) - Required - VAT rate code (1 for no VAT).
- **settlements** (array) - Required - Settlement details.
  - **type** (string) - Required - Type of settlement (e.g., 'cashless').
  - **amount** (object) - Required - Amount for the settlement.
    - **value** (string) - Required - The monetary value.
    - **currency** (string) - Required - The currency code (e.g., 'RUB').
- **send** (boolean) - Optional - Whether to send the receipt to the customer.

### Request Example
```json
{
  "type": "payment",
  "payment_id": "2be00000-0000-0000-0000-000000000001",
  "customer": {
    "email": "customer@example.com",
    "phone": "79001234567"
  },
  "items": [
    {
      "description": "Premium Subscription - 1 month",
      "quantity": "1",
      "amount": {
        "value": "1500.00",
        "currency": "RUB"
      },
      "vat_code": 1
    }
  ],
  "settlements": [
    {
      "type": "cashless",
      "amount": {
        "value": "1500.00",
        "currency": "RUB"
      }
    }
  ],
  "send": true
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the receipt.
- **status** (string) - The status of the receipt (e.g., 'succeeded').
- **type** (string) - The type of the receipt.

#### Response Example
```json
{
  "id": "rt-2be10000-0000-0000-0000-000000000001",
  "status": "succeeded",
  "type": "payment"
}
```
```

--------------------------------

### Error Handling

Source: https://context7.com/prodreams/async_yookassa/llms.txt

The library provides specific, typed exceptions to handle various error scenarios that may occur during API interactions, ensuring robust payment processing.

```APIDOC
## API Error Handling

### Description
The Async YooKassa client library raises specific exceptions for different error types. It is recommended to catch these exceptions to handle errors gracefully.

### Exception Types
- **BadRequestError**: For invalid requests or validation errors.
- **UnauthorizedError**: For authentication failures (e.g., invalid credentials).
- **ForbiddenError**: For access denied errors (e.g., insufficient permissions).
- **NotFoundError**: For requests targeting non-existent resources.
- **TooManyRequestsError**: When the rate limit has been exceeded.
- **ResponseProcessingError**: When YooKassa is processing the response and a retry is needed later.
- **APIError**: A general catch-all for other API-related errors.

### Usage Example
```python
import asyncio
from async_yookassa import YooKassaClient
from async_yookassa.models.payment import PaymentRequest, Amount, RedirectConfirmationRequest
from async_yookassa.exceptions import (
    APIError,
    BadRequestError,
    UnauthorizedError,
    ForbiddenError,
    NotFoundError,
    TooManyRequestsError,
    ResponseProcessingError,
)

async def handle_payment_errors():
    async with YooKassaClient(account_id="123456", secret_key="secret") as client:
        try:
            payment = await client.payment.create(
                PaymentRequest(
                    amount=Amount(value="100.00", currency="RUB"),
                    confirmation=RedirectConfirmationRequest(
                        type="redirect",
                        return_url="https://example.com/return"
                    ),
                    description="Test payment"
                )
            )
            print(f"Payment created: {payment.id}")

        except BadRequestError as e:
            print(f"Invalid request: {e}")
            # Handle validation errors

        except UnauthorizedError as e:
            print(f"Authentication failed: {e}")
            # Check credentials

        except ForbiddenError as e:
            print(f"Access denied: {e}")
            # Check permissions

        except NotFoundError as e:
            print(f"Resource not found: {e}")
            # Handle missing payment/refund

        except TooManyRequestsError as e:
            print(f"Rate limited: {e}")
            # Implement backoff and retry

        except ResponseProcessingError as e:
            print(f"Processing error: {e}")
            # YooKassa is processing, retry later

        except APIError as e:
            print(f"API error: {e}")
            # Generic API error

asyncio.run(handle_payment_errors())
```
```

--------------------------------

### Handle YooKassa API Errors Gracefully (Python)

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Demonstrates how to handle various API errors provided by the YooKassa Python SDK during payment creation. It includes specific exception handling for BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, TooManyRequestsError, ResponseProcessingError, and a general APIError. This ensures robust payment processing by addressing different failure scenarios.

```python
import asyncio
from async_yookassa import YooKassaClient
from async_yookassa.models.payment import PaymentRequest, Amount, RedirectConfirmationRequest
from async_yookassa.exceptions import (
    APIError,
    BadRequestError,
    UnauthorizedError,
    ForbiddenError,
    NotFoundError,
    TooManyRequestsError,
    ResponseProcessingError,
)

async def handle_payment_errors():
    async with YooKassaClient(account_id="123456", secret_key="secret") as client:
        try:
            payment = await client.payment.create(
                PaymentRequest(
                    amount=Amount(value="100.00", currency="RUB"),
                    confirmation=RedirectConfirmationRequest(
                        type="redirect",
                        return_url="https://example.com/return"
                    ),
                    description="Test payment"
                )
            )
            print(f"Payment created: {payment.id}")

        except BadRequestError as e:
            print(f"Invalid request: {e}")
            # Handle validation errors

        except UnauthorizedError as e:
            print(f"Authentication failed: {e}")
            # Check credentials

        except ForbiddenError as e:
            print(f"Access denied: {e}")
            # Check permissions

        except NotFoundError as e:
            print(f"Resource not found: {e}")
            # Handle missing payment/refund

        except TooManyRequestsError as e:
            print(f"Rate limited: {e}")
            # Implement backoff and retry

        except ResponseProcessingError as e:
            print(f"Processing error: {e}")
            # YooKassa is processing, retry later

        except APIError as e:
            print(f"API error: {e}")
            # Generic API error

asyncio.run(handle_payment_errors())
```

--------------------------------

### Create Fiscal Receipt (Python)

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Creates fiscal receipts compliant with Russian tax law (54-FZ). This function requires payment details, customer information, itemized lists, and settlement data. It returns the created receipt's ID, status, and type.

```python
import asyncio
from async_yookassa import YooKassaClient
from async_yookassa.models.receipt import (
    ReceiptRequest,
    ReceiptType,
    Customer,
    SettlementReceipt,
)
from async_yookassa.models.payment.receipts.receipt_item import ReceiptItem
from async_yookassa.models.payment import Amount

async def create_receipt():
    async with YooKassaClient(account_id="123456", secret_key="secret") as client:
        receipt = await client.receipt.create(
            ReceiptRequest(
                type=ReceiptType.payment,
                payment_id="2be00000-0000-0000-0000-000000000001",
                customer=Customer(
                    email="customer@example.com",
                    phone="79001234567"
                ),
                items=[
                    ReceiptItem(
                        description="Premium Subscription - 1 month",
                        quantity="1",
                        amount=Amount(value="1500.00", currency="RUB"),
                        vat_code=1  # No VAT
                    )
                ],
                settlements=[
                    SettlementReceipt(
                        type="cashless",
                        amount=Amount(value="1500.00", currency="RUB")
                    )
                ],
                send=True
            )
        )

        print(f"Receipt ID: {receipt.id}")
        print(f"Status: {receipt.status}")
        print(f"Type: {receipt.type}")
        # Expected output:
        # Receipt ID: rt-2be10000-0000-0000-0000-000000000001
        # Status: succeeded
        # Type: payment

asyncio.run(create_receipt())
```

--------------------------------

### SBP Bank Service - List SBP Banks

Source: https://context7.com/prodreams/async_yookassa/llms.txt

This service retrieves a comprehensive list of banks that are part of Russia's Faster Payments System (SBP), enabling SBP-related transactions.

```APIDOC
## GET /api/sbp/banks

### Description
Retrieves the list of banks participating in Russia's Faster Payments System (SBP).

### Method
GET

### Endpoint
/api/sbp/banks

### Parameters
None

### Response
#### Success Response (200)
- **items** (array) - A list of SBP bank objects.
  - **bank_id** (string) - The unique identifier for the bank.
  - **name** (string) - The name of the bank.

#### Response Example
```json
{
  "items": [
    {
      "bank_id": "100000000001",
      "name": "Sberbank"
    },
    {
      "bank_id": "100000000004",
      "name": "Tinkoff Bank"
    }
  ]
}
```
```

--------------------------------

### Cancel Payment (Python)

Source: https://context7.com/prodreams/async_yookassa/llms.txt

Cancels a payment that is in a pending or waiting_for_capture status. This operation requires the payment ID and returns the updated payment status. Requires the async_yookassa library.

```python
import asyncio
from async_yookassa import YooKassaClient

async def cancel_payment():
    async with YooKassaClient(account_id="123456", secret_key="secret") as client:
        payment = await client.payment.cancel("2be00000-0000-0000-0000-000000000001")

        print(f"Payment ID: {payment.id}")
        print(f"Status: {payment.status}")
        if payment.cancellation_details:
            print(f"Cancellation reason: {payment.cancellation_details.reason}")
        # Expected output:
        # Payment ID: 2be00000-0000-0000-0000-000000000001
        # Status: canceled
        # Cancellation reason: canceled_by_merchant

asyncio.run(cancel_payment())
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.