YooKassa SDK Python

https://github.com/yoomoney/yookassa-sdk-python
Admin
YooKassa SDK Python is a client library used for managing payments, payouts, refunds, and receipts...
Tokens:116,196
Snippets:843
Trust Score:8.9
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install yookassa with easy_install

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/README.en.md

Installs or upgrades the yookassa package using easy_install.

```bash
easy_install --upgrade yookassa
```

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

### Manual installation of yookassa

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/README.en.md

Manually downloads, extracts, and installs the yookassa package from the PyPI tarball.

```bash
wget https://pypi.python.org/packages/5a/be/5eafdfb14aa6f32107e9feb6514ca1ad3fe56f8e5ee59d20693b32f7e79f/yookassa-1.0.0.tar.gz#md5=46595279b5578fd82a199bfd4cd51db2
tar zxf yookassa-1.0.0.tar.gz
cd yookassa-1.0.0
python setup.py install
```

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

### PaymentRequestBuilder Example

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/confirmation-and-payment-data.md

Example of building a payment request with confirmation and reading the response confirmation URL.

```APIDOC
## PaymentRequestBuilder Example

### Description
Example usage of building a payment request with confirmation and reading the response.

### Code
```python
from yookassa import Payment
from yookassa.domain.request import PaymentRequestBuilder

req = PaymentRequestBuilder() \
    .set_amount({"value": "100.00", "currency": "RUB"}) \
    .set_confirmation({"type": "redirect", "return_url": "https://merchant-site.ru/return_url", "enforce": True}) \
    .build()

payment = Payment.create(req)
redirect_url = payment.confirmation.confirmation_url  # response-side ConfirmationRedirect
```

```

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

### PaymentRequestBuilder usage example

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/request-objects.md

Shows how to use the fluent PaymentRequestBuilder. Each setter takes a value and returns self; build() returns the inner PaymentRequest. This example sets amount, confirmation, capture, and description.

```python
# Usage
from yookassa.domain.request import PaymentRequestBuilder

builder = PaymentRequestBuilder()
req = builder.set_amount({"value": 1000, "currency": "RUB"}) \
    .set_confirmation({"type": "redirect", "return_url": "https://merchant-site.ru/return_url"}) \
    .set_capture(False) \
    .set_description("Order #72") \
    .build()
```

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

### Usage example: create, find_one, list

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/deal.md

Shows how to configure the SDK, create a deal, handle errors, and list deals. Includes error handling for ValueError and NotFoundError.

```python
from yookassa import Configuration, Deal
from yookassa.domain.models import DealType, FeeMoment

Configuration.configure('shop-id', 'secret-key')

deal = Deal.create({
    "type": DealType.SAFE_DEAL,
    "fee_moment": FeeMoment.PAYMENT_SUCCEEDED,
    "description": "Deal for order #72",
    "metadata": {"orderNumber": "72"},
})
print(deal.id, deal.status, deal.balance.value)
```

```python
from yookassa import Deal
from yookassa.domain.exceptions import BadRequestError, NotFoundError

try:
    Deal.create({"fee_moment": "payment_succeeded"})  # missing type → ValueError
except ValueError as e:
    print("Validation:", e)

try:
    Deal.find_one('dl-unknown-id')
except NotFoundError as e:
    print("404:", e)

page = Deal.list({"status": "opened", "limit": 5})
print(page.next_cursor, len(page.items))
```

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

### Add webhook example

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/webhook.md

Example of adding a webhook for the PAYMENT_SUCCEEDED event. Configures an OAuth token, calls Webhook.add with a dict, and prints the resulting hook's id and event.

```python
from yookassa import Configuration, Webhook
from yookassa.domain.notification import WebhookNotificationEventType

Configuration.configure_auth_token('oauth-token-xxx')

hook = Webhook.add({
    "event": WebhookNotificationEventType.PAYMENT_SUCCEEDED,
    "url": "https://merchant-site.ru/payment-notification",
})
print(hook.id, hook.event)
```

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

### Create a simple refund

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/refund.md

Example of creating a simple refund. Configures the SDK with shop credentials, calls Refund.create with a payment_id, amount, and description, then prints the refund's id, status, and created_at.

```python
from yookassa import Configuration, Refund

Configuration.configure('shop-id', 'secret-key')

refund = Refund.create({
    "payment_id": "21b23b5b-000f-5061-a000-0674e49a8c10",
    "amount": {"value": "100.00", "currency": "RUB"},
    "description": "Refund for order #72",
})
print(refund.id, refund.status, refund.created_at)
```

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

### Create payout with payout_token

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/payout.md

Example of creating a payout using a payout_token. Configures the SDK with shop credentials, then calls Payout.create with amount, payout_token, and description. Prints the resulting payout id and status.

```python
from yookassa import Configuration, Payout

Configuration.configure('shop-id', 'secret-key')

payout = Payout.create({
    "amount": {"value": "1000.00", "currency": "RUB"},
    "payout_token": "payout-token-from-yookassa",
    "description": "Payout to seller #123",
})
print(payout.id, payout.status)
```

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

### Create a receipt with Receipt.create

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/receipt.md

Example of creating a refund receipt with customer details, items, and settlements. Requires configuration with shop ID and secret key. Prints the receipt ID, status, and fiscal attribute.

```python
from yookassa import Configuration, Receipt
from yookassa.domain.common import ReceiptType

Configuration.configure('shop-id', 'secret-key')

receipt = Receipt.create({
    "type": ReceiptType.REFUND,
    "send": True,
    "refund_id": "21b23b5b-000f-5061-a000-0674e49a8c10",
    "customer": {"email": "client@example.com", "phone": "79211234567"},
    "items": [
        {
            "description": "Product 1",
            "quantity": "1.00",
            "amount": {"value": "100.00", "currency": "RUB"},
            "vat_code": 1,
        }
    ],
    "settlements": [
        {"type": "cashless", "amount": {"value": "100.00", "currency": "RUB"}}
    ],
})
print(receipt.id, receipt.status, receipt.fiscal_attribute)
```

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

### Reconcile webhooks example

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/webhook.md

Example of reconciling existing webhooks and removing stale ones. Lists all webhooks, checks for wanted events, removes those with mismatched URLs, and adds missing ones. Catches exceptions from ApiError subclasses on non-200 responses.

```python
from yookassa import Webhook
from yookassa.domain.notification import WebhookNotificationEventType

wh_url = 'https://merchant-site.ru/payment-notification'
wanted = [WebhookNotificationEventType.PAYMENT_SUCCEEDED, WebhookNotificationEventType.PAYMENT_CANCELED]

try:
    wh_list = Webhook.list()
    for event in wanted:
        hook_is_set = False
        for wh in wh_list.items:
            if wh.event != event:
                continue
            if wh.url != wh_url:
                Webhook.remove(wh.id)
            else:
                hook_is_set = True
        if not hook_is_set:
            Webhook.add({"event": event, "url": wh_url})
except Exception as e:  # ApiError subclasses raised on non-200
    print("Webhook sync failed:", e)
```

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

### Install yookassa with pip

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/README.en.md

Installs or upgrades the yookassa package using pip.

```bash
pip install --upgrade yookassa
```

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

### GET /me

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/client.md

Documentation for the Settings.get_account_settings method, which retrieves shop information from the /me endpoint.

```APIDOC
## GET /me

### Description
Retrieves information about the current shop (account settings). This endpoint is exposed through the `Settings.get_account_settings` method.

### Method
GET

### Endpoint
/me

### Parameters
#### Query Parameters
- **on_behalf_of** (string) - Optional - The account ID of the shop to act on behalf of (for OAuth partners).

### Request Example
```python
from yookassa import Settings
me = Settings.get_account_settings()
print(me['account_id'], me['status'])

# Acting on behalf of another shop (OAuth partners)
me = Settings.get_account_settings({'on_behalf_of': '123456'})
```

### Response
#### Success Response (200)
- **account_id** (string) - The shop's account ID.
- **test** (boolean) - Whether the shop is in test mode.
- **fiscalization_enabled** (boolean) - Whether fiscalization is enabled.
- **payment_methods** (array) - List of available payment methods.
- **status** (string) - The shop's status.

#### Response Example
```json
{
  "account_id": "123456",
  "test": false,
  "fiscalization_enabled": true,
  "payment_methods": ["bank_card", "yoo_money"],
  "status": "active"
}
```

### Error Handling
Non-200 responses raise a typed exception from `yookassa.domain.exceptions`:

| HTTP code | Exception |
|-----------|-----------|
| 400 | `BadRequestError` |
| 401 | `UnauthorizedError` |
| 403 | `ForbiddenError` |
| 404 | `NotFoundError` |
| 429 | `TooManyRequestsError` |
| 202 | `ResponseProcessingError` (only reached if retries are exhausted) |
| anything else | `ApiError(raw_response.text)` |

Exceptions other than `ApiError` are constructed with `raw_response.json()` as the single argument.
```

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

### Create a payment with YooKassa

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/payment.md

Basic example of creating a payment with the YooKassa SDK. Configures the shop ID and secret key, then creates a payment with amount, redirect confirmation, capture, description, and metadata. Prints the payment ID, status, and confirmation URL.

```python
from yookassa import Configuration, Payment

Configuration.configure('shop-id', 'secret-key')

payment = Payment.create({
    "amount": {"value": "100.00", "currency": "RUB"},
    "confirmation": {"type": "redirect", "return_url": "https://merchant-site.ru/return_url"},
    "capture": True,
    "description": "Order #72",
    "metadata": {"orderNumber": "72"},
})
print(payment.id, payment.status, payment.confirmation.confirmation_url)
```

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

### Error handling for Settings.get_account_settings

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/client.md

Error handling example for Settings.get_account_settings. Catches ForbiddenError, which is raised when the token/shop pair is not allowed to fetch /me (HTTP 403).

```python
from yookassa import Settings
from yookassa.domain.exceptions import ForbiddenError

try:
    Settings.get_account_settings()
except ForbiddenError as e:
    # 403 — the token/shop pair is not allowed to fetch /me
    print(e)
```

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

### Catching SDK Exceptions

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/errors.md

Code example showing how to catch and handle the various HTTP-level exceptions raised by the YooKassa SDK.

```APIDOC
## [CATCH] SDK Exception Handling

### Description
Catch HTTP-level API errors raised by the YooKassa SDK. The example shows how to handle each specific exception type.

### Exceptions
- **ApiError** - Base class for all API errors
- **BadRequestError** - HTTP 400
- **UnauthorizedError** - HTTP 401
- **ForbiddenError** - HTTP 403
- **NotFoundError** - HTTP 404
- **TooManyRequestsError** - HTTP 429
- **ResponseProcessingError** - HTTP 202 after retries exhausted

### Code Example
```python
from yookassa import Payment
from yookassa.domain.exceptions import (ApiError, BadRequestError, NotFoundError,
                                        UnauthorizedError, ForbiddenError,
                                        TooManyRequestsError, ResponseProcessingError)

try:
    Payment.find_one('21b23b5b-000f-5061-a000-0674e49a8c10')
except NotFoundError as e:           # 404
    print('unknown payment:', e)
except UnauthorizedError as e:       # 401
    print('bad credentials')
except ForbiddenError as e:          # 403
    print('no permission')
except BadRequestError as e:         # 400
    print('invalid body:', e)
except TooManyRequestsError as e:    # 429
    print('rate limited')
except ResponseProcessingError as e: # 202 after retries
    print('still processing')
except ApiError as e:                # any other non-200
    print('API error:', e)
```
```

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

### Usage - Serialization

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/response-objects.md

Example of converting BaseObject instances to dict and JSON.

```APIDOC
## Usage - Serialization

### Description
Every BaseObject supports dict conversion and JSON serialization.

### Code Example
```python
payment = Payment.find_one('21b23b5b-000f-5061-a000-0674e49a8c10')
data_dict = dict(payment)     # nested BaseObjects become dicts
json_str = payment.json()     # json.dumps(dict(self), default=str, ensure_ascii=False)
```
```

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

### Partial refund with sources and error handling

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/refund.md

Example of error handling with a partial refund using sources for payout split. Catches BadRequestError, then demonstrates looking up the refund with find_one and listing refunds with list.

```python
from yookassa import Refund
from yookassa.domain.exceptions import BadRequestError

try:
    refund = Refund.create(
        {
            "payment_id": "21b23b5b-000f-5061-a000-0674e49a8c10",
            "amount": {"value": "50.00", "currency": "RUB"},
            "sources": [
                {"account_id": "123", "amount": {"value": "20.00", "currency": "RUB"}},
                {"account_id": "456", "amount": {"value": "30.00", "currency": "RUB"}},
            ],
        },
        idempotency_key="refund-order-72",
    )
except BadRequestError as e:
    print("Invalid refund request:", e)

# Look up and list
info = Refund.find_one(refund.id)
page = Refund.list({"payment_id": "21b23b5b-000f-5061-a000-0674e49a8c10"})
print([r.id for r in page.items])
```

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

### Handling ConfigurationError for missing credentials

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/configuration.md

Demonstrates error handling when credentials are missing. Both misconfigured states raise `ConfigurationError` when an `ApiClient` is instantiated via `Configuration.instantiate()`. The example shows the error message "account_id and secret_key are required".

```python
from yookassa import Configuration, Payment
from yookassa.configuration import ConfigurationError

try:
    Configuration.configure(None, None)          # no credentials at all
    Payment.find_one('some-id')                  # triggers Configuration.instantiate()
except ConfigurationError as e:
    print(e)  # "account_id and secret_key are required"
```

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

### GET /deals

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/endpoints.md

Retrieves a list of deals with optional filtering.

```APIDOC
## GET /deals

### Description
Retrieves a list of deals, optionally filtered by query parameters.

### Method
GET

### Endpoint
/deals

### Parameters
#### Query Parameters
- **created_at.gte** (string) - Optional - Filter by creation date greater than or equal to the specified value.
- **created_at.lt** (string) - Optional - Filter by creation date less than the specified value.
- **expires_at** (string) - Optional - Filter by expiration date.
- **status** (string) - Optional - Filter by deal status.
- **limit** (integer) - Optional - Limit the number of results.
- **cursor** (string) - Optional - Pagination cursor.

### Response
#### Success Response (200)
- **DealListResponse** (object) - The response object containing a list of deals.

#### Response Example
(Refer to the DealListResponse schema provided by the YooKassa API documentation.)

```

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

### Usage - Refund List Iteration

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/response-objects.md

Example of iterating over a multi-page refund list using a cursor.

```APIDOC
## Usage - Refund List Iteration

### Description
Example of using Refund.list with a cursor to iterate over all refunds.

### Code Example
```python
from yookassa import Refund

cursor = None
while True:
    page = Refund.list({"limit": 100, **({"cursor": cursor} if cursor else {})})
    for r in page.items:
        print(r.id, r.status, r.amount.value)
    cursor = page.next_cursor
    if not cursor:
        break
```
```

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

### Usage - Payment Retrieval

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/response-objects.md

Example of retrieving a payment and accessing its properties.

```APIDOC
## Usage - Payment Retrieval

### Description
Example of using Payment.find_one to retrieve a payment and print its properties.

### Code Example
```python
from yookassa import Payment

payment = Payment.find_one('21b23b5b-000f-5061-a000-0674e49a8c10')
print(payment.id, payment.status, payment.amount.value, payment.amount.currency)
print(payment.paid, payment.refundable, payment.test)
print(payment.payment_method.type)           # e.g. 'bank_card'
print(payment.confirmation.confirmation_url) # redirect confirmation
```
```

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

### Create bank-card payout with error handling and find_one

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/payout.md

Example of creating a payout to a bank card with error handling and then fetching the payout. Uses payout_destination_data with type 'bank_card' and a card number (only for payouts). Catches BadRequestError and prints the rejection. Then calls Payout.find_one to retrieve and print payout details including cancellation reason if present.

```python
from yookassa import Payout
from yookassa.domain.exceptions import BadRequestError

try:
    payout = Payout.create({
        "amount": {"value": "500.00", "currency": "RUB"},
        "payout_destination_data": {
            "type": "bank_card",
            "card": {"number": "5555555555554444"},  # card number only for payouts
        },
    }, idempotency_key="payout-77")
except BadRequestError as e:
    print("API rejected the payout:", e)

info = Payout.find_one(payout.id)
print(info.id, info.status, info.cancellation_details.reason if info.cancellation_details else None)
```

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

### Create a payout with YooMoney wallet destination using Payout.create()

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/confirmation-and-payment-data.md

Creates a payout of 100.00 RUB to a YooMoney wallet using the Payout.create() method. The payout_destination_data specifies the type 'yoo_money' and the account_number. This example demonstrates the request-side PayoutDestinationYooMoneyWallet class.

```python
from yookassa import Payout

payout = Payout.create({
    "amount": {"value": "100.00", "currency": "RUB"},
    "payout_destination_data": {
        "type": "yoo_money",
        "account_number": "410011161616161",
    },
})
```

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

### Settings class with get_account_settings method

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/client.md

The Settings class definition from src/yookassa/settings.py, re-exported as yookassa.Settings. It defines the base path '/me' and the get_account_settings class method that performs a GET request and returns the raw parsed JSON dict.

```python
class Settings:
    base_path = '/me'

    def __init__(self):
        self.client = ApiClient()

    @classmethod
    def get_account_settings(cls, params=None):
        """
        Shop Info

        :param params: (dict | None) Параметры поиска.
            В настоящее время доступен только {'on_behalf_of': account_id}
        :return: dict
        """
        instance = cls()
        path = cls.base_path

        response = instance.client.request(HttpVerb.GET, path, params)
        return response
```

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

### Webhook.list() method

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/webhook.md

Classmethod that retrieves all webhooks via a GET request to the base path. Returns a WebhookList containing type and items (list of WebhookResponse). Throws HTTP errors.

```python
    @classmethod
    def list(cls):
        instance = cls()
        path = cls.base_path

        response = instance.client.request(HttpVerb.GET, path)
        return WebhookList(response)
```

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

### Handle errors and advanced payment operations

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/payment.md

Advanced example showing error handling with BadRequestError and NotFoundError, explicit idempotency key for replay-safe create, capturing a payment, cancelling, and listing payments with a status filter and limit. Prints the next cursor and payment IDs from the list.

```python
from yookassa import Payment
from yookassa.domain.exceptions import BadRequestError, NotFoundError

# Explicit idempotency key → replay-safe create
try:
    payment = Payment.create(
        {"amount": {"value": "500.00", "currency": "RUB"}, "capture": False},
        idempotency_key="my-unique-key-1",
    )
    captured = Payment.capture(payment.id, {"amount": {"value": "500.00", "currency": "RUB"}})
except BadRequestError as e:
    print("400 from API:", e)
except NotFoundError as e:
    print("404:", e)

# Cancelling and listing
Payment.cancel(payment.id)
page = Payment.list({"status": "succeeded", "limit": 10})
print(page.next_cursor, [p.id for p in page.items])
```

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

### Verify webhook IP with SecurityHelper

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/common.md

Usage example to verify webhook caller IP before parsing a notification. Raises `PermissionError` if the IP is not trusted.

```python
from yookassa.domain.common import SecurityHelper

if not SecurityHelper().is_ip_trusted(request.remote_addr):
    raise PermissionError("Notification not from YooKassa")
```

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

### Refund.list method

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/refund.md

Classmethod to list refunds with query filters. Accepts a dict of parameters such as created_at, payment_id, status, limit, and cursor. Sends a GET request to /refunds and returns a RefundListResponse containing type, next_cursor, and items.

```python
    @classmethod
    def list(cls, params):
        instance = cls()
        path = cls.base_path

        response = instance.client.request(HttpVerb.GET, path, params)
        return RefundListResponse(response)
```

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

### GET /payments

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/client.md

Low-level API call to retrieve a list of payments. This is a direct usage example of the ApiClient's request method.

```APIDOC
## GET /payments

### Description
Retrieves a list of payments. This is a low-level API call that can be used directly, though the service classes typically handle this internally.

### Method
GET

### Endpoint
/payments

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of payments to return.

### Request Example
```python
from yookassa.client import ApiClient
from yookassa.domain.common import HttpVerb

client = ApiClient()
resp_json = client.request(HttpVerb.GET, '/payments', query_params={'limit': 10})
print(resp_json)
```

### Response
#### Success Response (200)
- **resp_json** (object) - The JSON response containing the list of payments.

#### Response Example
```json
{
  "type": "list",
  "items": []
}
```
```

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

### Configure client with account ID and secret key

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/README.en.md

Configures the SDK client with an account ID and secret key using the configure method.

```python
from yookassa import Configuration

Configuration.configure('<Account Id>', '<Secret Key>')
```

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

### Basic ApiClient GET request

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/client.md

Direct low-level use of ApiClient to make a GET request to the /payments endpoint with a query parameter. The service classes use this pattern internally.

```python
from yookassa.client import ApiClient
from yookassa.domain.common import HttpVerb

client = ApiClient()
resp_json = client.request(HttpVerb.GET, '/payments', query_params={'limit': 10})
print(resp_json)
```

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

### Configuration.configure

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/configuration.md

Configures the SDK with basic authentication credentials (account ID and secret key). Clears any previously set OAuth token.

```APIDOC
## Configuration.configure

### Description
Configures the SDK with basic authentication credentials (account ID and secret key). Clears any previously set OAuth token.

### Method
configure

### Parameters
- `account_id` (str) - Required - Shop identifier
- `secret_key` (str) - Required - Shop secret key
- `timeout` (int) - Optional - Retry backoff base in ms (default: 1800)
- `max_attempts` (int) - Optional - Retry count (default: 3)

### Returns
None
```

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

### Configure client by setting attributes

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/README.en.md

Configures the SDK client by directly setting the account_id and secret_key attributes.

```python
from yookassa import Configuration

Configuration.account_id = '<Account Id>'
Configuration.secret_key = '<Secret Key>'
```

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

### GET /deals/{deal_id}

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/endpoints.md

Retrieves a deal by its unique identifier.

```APIDOC
## GET /deals/{deal_id}

### Description
Retrieves information about a specific deal by its ID.

### Method
GET

### Endpoint
/deals/{deal_id}

### Parameters
#### Path Parameters
- **deal_id** (string) - Required - The unique identifier of the deal.

### Response
#### Success Response (200)
- **DealResponse** (object) - The response object containing deal details.

#### Response Example
(Refer to the DealResponse schema provided by the YooKassa API documentation.)

```

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

### Deal class definition with base_path and __init__

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/deal.md

Defines the Deal class with base_path '/deals' and initializes an ApiClient instance. All methods are classmethods that build a fresh instance and ApiClient.

```python
class Deal:
    base_path = '/deals'

    def __init__(self):
        self.client = ApiClient()
```

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

### Configure client with OAuth token

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/README.en.md

Configures the SDK client using an OAuth token.

```python
from yookassa import Configuration

Configuration.configure_auth_token('<Oauth Token>')
```

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

### GET /receipts

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/endpoints.md

Retrieves a list of receipts with optional filtering.

```APIDOC
## GET /receipts

### Description
Retrieves a list of receipts, optionally filtered by query parameters.

### Method
GET

### Endpoint
/receipts

### Parameters
#### Query Parameters
- **created_at.gte** (string) - Optional - Filter by creation date greater than or equal to the specified value.
- **created_at.lt** (string) - Optional - Filter by creation date less than the specified value.
- **payment_id** (string) - Optional - Filter by payment ID.
- **refund_id** (string) - Optional - Filter by refund ID.
- **status** (string) - Optional - Filter by receipt status.
- **limit** (integer) - Optional - Limit the number of results.
- **cursor** (string) - Optional - Pagination cursor.

### Response
#### Success Response (200)
- **ReceiptListResponse** (object) - The response object containing a list of receipts.

#### Response Example
(Refer to the ReceiptListResponse schema provided by the YooKassa API documentation.)

```

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

### GET /refunds/{refund_id}

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/endpoints.md

Retrieves a refund by its unique identifier.

```APIDOC
## GET /refunds/{refund_id}

### Description
Retrieves information about a specific refund by its ID.

### Method
GET

### Endpoint
/refunds/{refund_id}

### Parameters
#### Path Parameters
- **refund_id** (string) - Required - The unique identifier of the refund.

### Response
#### Success Response (200)
- **RefundResponse** (object) - The response object containing refund details.

#### Response Example
(Refer to the RefundResponse schema provided by the YooKassa API documentation.)

```

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

### Deal.create

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/deal.md

Creates a new deal. Accepts deal data as a dictionary or `DealRequest` object. Returns a `DealResponse` object.

```APIDOC
## POST /deals

### Description
Creates a new deal. Accepts deal data as a dictionary or `DealRequest` object. Returns a `DealResponse` object.

### Method
POST

### Endpoint
`/deals`

### Parameters
#### Request Body
- **type** (DealType) - Required - Deal type.
- **fee_moment** (FeeMoment) - Required - Fee moment.
- **description** (str) - Optional - Description (≤ 128 chars).
- **metadata** (dict) - Optional - Additional metadata.

#### Headers
- **Idempotence-Key** (str) - Optional - Idempotency key. Defaults to `uuid.uuid4()` if not provided.

### Response
#### Success Response (200)
- Returns a `DealResponse` object.

### Errors
- `TypeError` - If `params` is not a dict or `DealRequest`.
- `ValueError` - If validation fails (e.g., missing `type` or `fee_moment`, description too long).
```

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

### GET /payouts/{payout_id}

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/payout.md

Retrieves payout information by ID.

```APIDOC
## [GET] /payouts/{payout_id}

### Description
Retrieves information about a specific payout by its ID.

### Method
GET

### Endpoint
/payouts/{payout_id}

### Parameters
#### Path Parameters
- **payout_id** (str) - Required - Payout UUID

### Response
#### Success Response (200)
- **PayoutResponse** - Payout information

#### Response Example
```json
{
  "id": "plv_...",
  "status": "succeeded",
  "amount": {"value": "1000.00", "currency": "RUB"}
}
```

### Errors
- **ValueError** - If `payout_id` is not a non-empty string
- **NotFoundError** - If payout is not found
```

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

### GET /receipts/{receipt_id}

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/receipt.md

Retrieves information about a specific receipt by its UUID.

```APIDOC
## GET /receipts/{receipt_id}

### Description
Get receipt information by its UUID.

### Method
GET

### Endpoint
/receipts/{receipt_id}

### Parameters
#### Path Parameters
- **receipt_id** (str) - Required - Receipt UUID

### Response
#### Success Response (200)
- **ReceiptResponse** - Receipt information

### Errors
- **ValueError** - Invalid receipt_id value
- **NotFoundError** - Unknown receipt

```

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

### Configure client with user agent data

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/README.en.md

Configures the SDK client and submits framework, CMS, and module version data for SDK development participation.

```python
from yookassa import Configuration
from yookassa.domain.common.user_agent import Version

Configuration.configure('<Account Id>', '<Secret Key>')
Configuration.configure_user_agent(
    framework=Version('Django', '2.2.3'),
    cms=Version('Wagtail', '2.6.2'),
    module=Version('Y.CMS', '0.0.1')
)
```

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

### Configuration usage for basic auth, OAuth, and user agent

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/configuration.md

Shows how to configure the YooKassa SDK. Basic auth uses `configure` with shop ID and secret key; OAuth mode uses `configure_auth_token` and is mutually exclusive with basic auth. Optional environment reporting can be added with `configure_user_agent`.

```python
from yookassa import Configuration

# Basic auth mode
Configuration.configure('shop-id', 'live_secret_key')
Configuration.configure('shop-id', 'secret', timeout=10000, max_attempts=5)

# OAuth mode (mutually exclusive with basic auth)
Configuration.configure_auth_token('oauth-token-xxx')

# Optional environment reporting
from yookassa.domain.common.user_agent import Version
Configuration.configure_user_agent(
    framework=Version('Django', '2.2.3'),
    cms=Version('Wagtail', '2.6.2'),
    module=Version('Y.CMS', '0.0.1'),
)
```

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

### GET /payments/{payment_id}

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/client.md

Low-level API call to retrieve a specific payment by ID. Demonstrates error handling for a non-existent payment.

```APIDOC
## GET /payments/{payment_id}

### Description
Retrieves a specific payment by its ID. This is a low-level API call that can be used directly, though the service classes typically handle this internally.

### Method
GET

### Endpoint
/payments/{payment_id}

### Parameters
#### Path Parameters
- **payment_id** (string) - Required - The unique identifier of the payment to retrieve.

### Request Example
```python
from yookassa.client import ApiClient
from yookassa.domain.common import HttpVerb
from yookassa.domain.exceptions import NotFoundError

client = ApiClient()
try:
    client.request(HttpVerb.GET, '/payments/does-not-exist')
except NotFoundError as e:
    # 404 raised with the API error body as the exception argument
    print(e)
```

### Response
#### Success Response (200)
- **resp_json** (object) - The JSON response containing the payment details.

#### Error Response (404)
- **NotFoundError** - Raised when the payment does not exist. The exception argument contains the API error body.
```

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

### Configuration.instantiate() - Build Configuration from class state

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/configuration.md

Static method that builds a Configuration instance from current class attributes. The constructor runs credential validation. Used once per ApiClient construction. Returns a fresh Configuration.

```python
    @staticmethod
    def instantiate():
        return Configuration(
            shop_id=Configuration.account_id,
            shop_password=Configuration.secret_key,
            timeout=Configuration.timeout,
            max_attempts=Configuration.max_attempts,
            auth_token=Configuration.auth_token,
            agent_framework=Configuration.agent_framework,
            agent_cms=Configuration.agent_cms,
            agent_module=Configuration.agent_module
        )
```

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

### Deal.create method

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/deal.md

Creates a new deal. Accepts params as dict or DealRequest. Generates an idempotency key if not provided. Throws TypeError for invalid params type and ValueError from DealRequest.validate().

```python
    @classmethod
    def create(cls, params, idempotency_key=None):
        """
        Create receipt

        :param params: data passed to API
        :param idempotency_key:
        :return: DealResponse
        """
        instance = cls()
        path = cls.base_path

        if not idempotency_key:
            idempotency_key = uuid.uuid4()

        headers = {
            'Idempotence-Key': str(idempotency_key)
        }

        if isinstance(params, dict):
            params_object = DealRequest(params)
        elif isinstance(params, DealRequest):
            params_object = params
        else:
            raise TypeError('Invalid params value type')

        response = instance.client.request(HttpVerb.POST, path, None, headers, params_object)
        return DealResponse(response)
```

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

### HttpVerb class with HTTP method constants

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/common.md

Defines HTTP method constants used as the `method` argument to `ApiClient.request()`. The SDK itself only uses `GET`, `POST`, and `DELETE`.

```python
class HttpVerb(object):
    GET = 'get'
    POST = 'post'
    PUT = 'put'
    PATCH = 'patch'
    HEAD = 'head'
    OPTIONS = 'options'
    DELETE = 'delete'
```

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

### Usage of BaseObject with Amount

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/common.md

Shows how to use BaseObject-derived classes: create an Amount instance from a dictionary, then convert to dict and JSON. The output demonstrates the conversion behavior.

```python
from yookassa.domain.models import Amount

a = Amount({"value": "100.00", "currency": "RUB"})
print(dict(a))        # {'value': '100.00', 'currency': 'RUB'}
print(a.json())       # {"value": "100.00", "currency": "RUB"}
```

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

### Build payment request with redirect confirmation and read response

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/confirmation-and-payment-data.md

Shows how to use PaymentRequestBuilder to set an amount and a redirect confirmation with a return URL and enforce flag, create a payment, and access the confirmation URL from the response.

```python
from yookassa import Payment
from yookassa.domain.request import PaymentRequestBuilder

req = PaymentRequestBuilder() \
    .set_amount({"value": "100.00", "currency": "RUB"}) \
    .set_confirmation({"type": "redirect", "return_url": "https://merchant-site.ru/return_url", "enforce": True}) \
    .build()

payment = Payment.create(req)
redirect_url = payment.confirmation.confirmation_url  # response-side ConfirmationRedirect
```

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

### Create Amount and Receipt with YooKassa domain models

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/models.md

Shows how to instantiate an Amount with a Decimal value and currency, and build a Receipt with customer, items, and tax system code. The receipt's has_items() method returns True when items are present.

```python
from yookassa.domain.models import Amount, Receipt, ReceiptItem, Settlement, Transfer, Currency

amount = Amount({"value": "100.00", "currency": Currency.RUB})
print(amount.value, amount.currency)     # 100.00 RUB (Decimal)

receipt = Receipt()
receipt.customer = {"email": "client@example.com"}
receipt.items = [
    ReceiptItem({
        "description": "Product",
        "quantity": 2.0,
        "amount": {"value": "50.00", "currency": "RUB"},
        "vat_code": 2,
    })
]
receipt.tax_system_code = 1
print(receipt.has_items())
```

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

### Configuration and per-call options

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/configuration.md

Configuration methods and per-call options for the YooKassa SDK.

```APIDOC
## Configuration methods

### configure

**Signature:** `(account_id, secret_key, **kwargs)`

Sets basic auth; clears `auth_token`. `kwargs`: `timeout` (default 1800), `max_attempts` (default 3).

### configure_auth_token

**Signature:** `(token, **kwargs)`

Sets OAuth; clears `account_id`/`secret_key`. `kwargs`: `timeout`, `max_attempts`.

### configure_user_agent

**Signature:** `(framework=None, cms=None, module=None)`

Stores each kwarg only if it is a `Version` instance.

### instantiate

**Signature:** `()`

Returns a new `Configuration` built from current class state (used once per `ApiClient`).

### api_endpoint

**Signature:** `()`

Returns `api_url`.

### has_api_credentials

**Signature:** `()`

Returns `bool` — `account_id is not None and secret_key is not None`.

### assert_has_api_credentials

**Signature:** `()`

Raises `ConfigurationError` per the rules above.

## Per-call options

### idempotency_key

- **Where:** `Payment.create/capture/cancel`, `Refund.create`, `Receipt.create`, `Deal.create`, `Payout.create`, `Webhook.add/remove`
- **Type:** str / UUID
- **Default:** `uuid.uuid4()`
- **Description:** Sent as the `Idempotence-Key` header; supply the same value on retries to make the call replay-safe.

### headers

- **Where:** `ApiClient.request(...)`
- **Type:** dict
- **Default:** `None`
- **Description:** Merged over the default headers; caller values win.

### query_params

- **Where:** `ApiClient.request(...)` (used by all `list()` methods and `Settings.get_account_settings`)
- **Type:** dict / None
- **Default:** `None`
- **Description:** Query string; e.g. `{'status': 'succeeded', 'limit': 10, 'cursor': ...}`.
```

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

### configure_user_agent method

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/configuration.md

Sets user-agent components (framework, cms, module) only if they are instances of Version; otherwise silently ignored. Returns None.

```python
    @staticmethod
    def configure_user_agent(framework=None, cms=None, module=None):
        if isinstance(framework, Version):
            Configuration.agent_framework = framework
        if isinstance(cms, Version):
            Configuration.agent_cms = cms
        if isinstance(module, Version):
            Configuration.agent_module = module
```

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

### Iterate through refunds with pagination

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/response-objects.md

Demonstrates multi-page list iteration using the next_cursor from the response to fetch all refunds.

```python
from yookassa import Refund

cursor = None
while True:
    page = Refund.list({"limit": 100, **({"cursor": cursor} if cursor else {})})
    for r in page.items:
        print(r.id, r.status, r.amount.value)
    cursor = page.next_cursor
    if not cursor:
        break
```

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

### ApiClient.prepare_request_headers method

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/client.md

Builds request headers: Content-type application/json, Authorization as Bearer token (OAuth) or Basic base64(shop_id:secret_key), YM-User-Agent string, and merges caller headers last so they win.

```python
    def prepare_request_headers(self, headers):
        request_headers = {'Content-type': 'application/json'}
        if self.auth_token is not None:
            auth_headers = {"Authorization": "Bearer " + self.auth_token}
        else:
            auth_headers = {"Authorization": _basic_auth_str(self.shop_id, self.shop_password)}

        request_headers.update(auth_headers)

        request_headers.update({"YM-User-Agent": self.user_agent.get_header_string()})

        if isinstance(headers, dict):
            request_headers.update(headers)
        return request_headers
```

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

### Configuration.configure_auth_token

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/configuration.md

Configures the SDK with an OAuth token for authentication. Clears any previously set basic auth credentials (account ID and secret key).

```APIDOC
## Configuration.configure_auth_token

### Description
Configures the SDK with an OAuth token for authentication. Clears any previously set basic auth credentials (account ID and secret key).

### Method
configure_auth_token

### Parameters
- `token` (str) - Required - OAuth token
- `timeout` (int) - Optional - Retry backoff base in ms (default: 1800)
- `max_attempts` (int) - Optional - Retry count (default: 3)

### Returns
None
```

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

### Refund.find_one method

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/refund.md

Classmethod to retrieve a single refund by its ID. Validates that refund_id is a non-empty string, otherwise raises ValueError with the literal message 'Invalid payment_id value' (a copy-paste artifact). Sends a GET request to /refunds/{refund_id} and returns a RefundResponse.

```python
    @classmethod
    def find_one(cls, refund_id):
        """
        Get refund information

        :param refund_id:
        :return: RefundResponse
        """
        instance = cls()
        if not isinstance(refund_id, str) or not refund_id:
            raise ValueError('Invalid payment_id value')
        path = instance.base_path + '/' + refund_id
        response = instance.client.request(HttpVerb.GET, path)
        return RefundResponse(response)
```

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

### Basic call to Settings.get_account_settings

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/client.md

Basic usage of Settings.get_account_settings. The first call fetches the current shop's settings, the second passes an 'on_behalf_of' parameter to act on behalf of another shop (OAuth partners). The method returns a raw parsed JSON dict with keys like 'account_id' and 'status'.

```python
# Basic call
from yookassa import Settings
me = Settings.get_account_settings()
print(me['account_id'], me['status'])

# Acting on behalf of another shop (OAuth partners)
me = Settings.get_account_settings({'on_behalf_of': '123456'})
```

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

### Import yookassa module

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/README.en.md

Imports the yookassa module to begin using the SDK.

```python
import yookassa
```

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

### Serialize a payment to dict and JSON

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/response-objects.md

Shows how every BaseObject supports dict conversion and JSON serialization. Nested BaseObjects become dicts, and json() uses json.dumps with default=str and ensure_ascii=False.

```python
payment = Payment.find_one('21b23b5b-000f-5061-a000-0674e49a8c10')
data_dict = dict(payment)     # nested BaseObjects become dicts
json_str = payment.json()     # json.dumps(dict(self), default=str, ensure_ascii=False)
```

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

### Version class for user agent

Source: https://github.com/yoomoney/yookassa-sdk-python/blob/master/_autodocs/api-reference/common.md

Represents a name/version pair rendered as `Name/Version`. Accepted by `Configuration.configure_user_agent()`.

```python
class Version:
    __name = None
    __version = None

    def __init__(self, name, version):
        self.name = name
        self.version = version

    @property
    def name(self):
        return self.__name

    @name.setter
    def name(self, value):
        self.__name = str(value)

    @property
    def version(self):
        return self.__version

    @version.setter
    def version(self, value):
        self.__version = str(value)

    def __str__(self):
        return UserAgent.create_version(self.name, self.version)
```
Tokens:
Raw