Invoice Management

This guide explains how to create and manage invoices using the Invoice API.

Creating Invoices

Create an invoice via Invoice API (JWT-based):

from decimal import Decimal
from aiorobokassa import RoboKassaClient, InvoiceType
from aiorobokassa.models.requests import InvoiceItem
from aiorobokassa.enums import TaxRate, PaymentMethod, PaymentObject

async with RoboKassaClient(
    merchant_login="your_merchant_login",
    password1="password1",
    password2="password2",
) as client:
    result = await client.create_invoice(
        out_sum=Decimal("100.00"),
        description="Invoice for services",
        invoice_type=InvoiceType.ONE_TIME,
        inv_id=12345,
        culture="ru",
    )

    print(f"Invoice created: {result}")
    print(f"Invoice URL: {result['url']}")

Invoice with Fiscalization

Create invoice with fiscalization items:

invoice_items = [
    InvoiceItem(
        name="Service 1",
        quantity=1,
        cost=50.0,
        tax=TaxRate.VAT20,
        payment_method=PaymentMethod.FULL_PAYMENT,
        payment_object=PaymentObject.SERVICE,
    ),
    InvoiceItem(
        name="Service 2",
        quantity=2,
        cost=25.0,
        tax=TaxRate.VAT20,
        payment_method=PaymentMethod.FULL_PAYMENT,
        payment_object=PaymentObject.SERVICE,
    ),
]

result = await client.create_invoice(
    out_sum=Decimal("100.00"),
    description="Invoice for services",
    invoice_items=invoice_items,
)

Invoice with Custom Parameters

Add custom parameters to invoice:

result = await client.create_invoice(
    out_sum=Decimal("100.00"),
    description="Invoice for services",
    user_fields={
        "contract_id": "123",
        "project_id": "456",
    },
)

Invoice with Redirect URLs

Set success and fail redirect URLs:

result = await client.create_invoice(
    out_sum=Decimal("100.00"),
    description="Invoice for services",
    success_url="https://example.com/success",
    success_url_method="GET",
    fail_url="https://example.com/fail",
    fail_url_method="POST",
)

Response Format

The create_invoice method returns a dictionary with invoice information:

{
    "id": "invoice-id-123",  # Invoice identifier
    "url": "https://auth.robokassa.ru/merchant/Invoice/...",  # Payment URL
    "inv_id": 12345,  # Invoice ID (if specified)
    "encoded_id": "invoice-id-123",  # Encoded invoice ID
}

Deactivating Invoices

Deactivate an invoice:

# By invoice ID
await client.deactivate_invoice(inv_id=12345)

# By invoice identifier
await client.deactivate_invoice(invoice_id="invoice-id-123")

# By encoded ID (from URL)
await client.deactivate_invoice(encoded_id="invoice-id-123")

Getting Invoice List

Get list of invoices with filtering:

from datetime import datetime

result = await client.get_invoice_information_list(
    current_page=1,
    page_size=10,
    invoice_statuses=["paid", "notpaid"],
    invoice_types=["onetime"],
    keywords="services",
    date_from="2025-01-01T00:00:00+00:00",
    date_to="2025-12-31T23:59:59+00:00",
    is_ascending=True,
    sum_from=10.0,
    sum_to=1000.0,
)

Error Handling

Handle errors when creating invoices:

from aiorobokassa import APIError

try:
    result = await client.create_invoice(
        out_sum=Decimal("100.00"),
        description="Invoice",
    )
except APIError as e:
    print(f"API error: {e.status_code} - {e.response}")