Client API

Main client for RoboKassa API.

class aiorobokassa.client.RoboKassaClient(merchant_login: str, password1: str, password2: str, password3: str | None = None, test_mode: bool = False, session: aiohttp.ClientSession | None = None, timeout: aiohttp.ClientTimeout | None = None, base_url_override: str | None = None)[source]

Bases: BaseAPIClient, PaymentMixin, InvoiceMixin, RefundMixin, XMLMixin

Async client for RoboKassa payment gateway.

Supports payment link generation, notification handling, invoice creation, and refunds.

PRODUCTION_BASE_URL: str = 'https://auth.robokassa.ru'
TEST_BASE_URL: str = 'https://auth.robokassa.ru'
__init__(merchant_login: str, password1: str, password2: str, password3: str | None = None, test_mode: bool = False, session: aiohttp.ClientSession | None = None, timeout: aiohttp.ClientTimeout | None = None, base_url_override: str | None = None)[source]

Initialize RoboKassa client.

Parameters:

  • merchant_login – Merchant login from RoboKassa

  • password1 – Password #1 for signature calculation

  • password2 – Password #2 for ResultURL verification

  • password3 – Password #3 for refund API (optional, required for refunds)

  • test_mode – Enable test mode

  • session – Optional aiohttp session (will be created if not provided)

  • timeout – Optional timeout for requests

  • base_url_override – Override base URL (for testing)

Raises:

ConfigurationError – If configuration is invalid

clear_sensitive_data() → None[source]

Clear sensitive data from memory.

RoboKassaClient

class aiorobokassa.client.RoboKassaClient(merchant_login: str, password1: str, password2: str, password3: str | None = None, test_mode: bool = False, session: aiohttp.ClientSession | None = None, timeout: aiohttp.ClientTimeout | None = None, base_url_override: str | None = None)[source]

Bases: BaseAPIClient, PaymentMixin, InvoiceMixin, RefundMixin, XMLMixin

Async client for RoboKassa payment gateway.

Supports payment link generation, notification handling, invoice creation, and refunds.

PRODUCTION_BASE_URL: str = 'https://auth.robokassa.ru'
TEST_BASE_URL: str = 'https://auth.robokassa.ru'
__init__(merchant_login: str, password1: str, password2: str, password3: str | None = None, test_mode: bool = False, session: aiohttp.ClientSession | None = None, timeout: aiohttp.ClientTimeout | None = None, base_url_override: str | None = None)[source]

Initialize RoboKassa client.

Parameters:

  • merchant_login – Merchant login from RoboKassa

  • password1 – Password #1 for signature calculation

  • password2 – Password #2 for ResultURL verification

  • password3 – Password #3 for refund API (optional, required for refunds)

  • test_mode – Enable test mode

  • session – Optional aiohttp session (will be created if not provided)

  • timeout – Optional timeout for requests

  • base_url_override – Override base URL (for testing)

Raises:

ConfigurationError – If configuration is invalid

clear_sensitive_data() → None[source]

Clear sensitive data from memory.

Payment Methods

Payment operations for RoboKassa API.

class aiorobokassa.api.payment.PaymentMixin[source]

Bases: object

Mixin for payment operations.

create_payment_url(out_sum: Decimal | float | int | str, description: str, inv_id: int | None = None, email: str | None = None, culture: str | None = None, encoding: str | None = None, is_test: int | None = None, expiration_date: str | None = None, user_parameters: Dict[str, str] | None = None, receipt: Receipt | str | Dict[str, Any] | None = None, signature_algorithm: str | SignatureAlgorithm = 'MD5') → str[source]

Create payment URL for RoboKassa.

Parameters:

  • out_sum – Payment amount (Decimal, float, int, or string)

  • description – Payment description

  • inv_id – Invoice ID (optional)

  • email – Customer email (optional)

  • culture – Language code (ru, en) (optional)

  • encoding – Encoding (optional, default: utf-8)

  • is_test – Test mode flag (optional)

  • expiration_date – Payment expiration date (optional)

  • user_parameters – Additional user parameters (Shp_*) (optional)

  • receipt – Receipt data for fiscalization - Receipt model, JSON string or dict (optional)

  • signature_algorithm – Signature algorithm (optional, default: MD5)

Returns:

Payment URL string

create_split_payment_url(out_amount: Decimal | float | int | str, merchant_id: str, split_merchants: list[Dict[str, Any]], merchant_comment: str | None = None, shop_params: list[Dict[str, str]] | None = None, email: str | None = None, inc_curr: str | None = None, language: str | None = None, is_test: bool | None = None, expiration_date: str | None = None, signature_algorithm: str | SignatureAlgorithm = 'MD5') → str[source]

Create split payment URL for RoboKassa.

Split payment allows distributing a payment between multiple merchants.

Parameters:

  • out_amount – Total payment amount (Decimal, float, int, or string)

  • merchant_id – Master merchant ID (initiates the split operation)

  • split_merchants – List of split merchant dictionaries, each containing: - id: Merchant ID (required) - invoice_id: Invoice ID (optional, auto-generated if not provided or 0) - amount: Amount for this merchant (required, can be 0.00) - receipt: Receipt data (optional) - Receipt model, JSON string or dict

  • merchant_comment – Order description (max 100 characters, optional)

  • shop_params – List of shop parameter dictionaries with ‘name’ and ‘value’ (optional)

  • email – Customer email (optional)

  • inc_curr – Payment method (e.g., “BankCard”) (optional)

  • language – Language code (ru, en) (optional)

  • is_test – Test mode flag (optional)

  • expiration_date – Payment expiration date in ISO 8601 format (optional)

  • signature_algorithm – Signature algorithm (optional, default: MD5)

Returns:

Split payment URL string

Raises:

ValidationError – If request data is invalid

static parse_result_url_params(params: Dict[str, str]) → Dict[str, str | Dict[str, str]][source]

Parse ResultURL parameters from request.

static parse_success_url_params(params: Dict[str, str]) → Dict[str, str | Dict[str, str]][source]

Parse SuccessURL parameters from request.

verify_result_url(out_sum: str, inv_id: str, signature_value: str, shp_params: Dict[str, str] | None = None, signature_algorithm: str | SignatureAlgorithm = 'MD5') → bool[source]

Verify ResultURL notification signature.

verify_success_url(out_sum: str, inv_id: str, signature_value: str, shp_params: Dict[str, str] | None = None, signature_algorithm: str | SignatureAlgorithm = 'MD5') → bool[source]

Verify SuccessURL redirect signature.

Invoice Methods

Invoice operations for RoboKassa API.

class aiorobokassa.api.invoice.InvoiceMixin[source]

Bases: object

Mixin for invoice operations.

async create_invoice(out_sum: Decimal | float | int | str, description: str, invoice_type: InvoiceType | str = InvoiceType.ONE_TIME, inv_id: int | None = None, culture: str | None = None, merchant_comments: str | None = None, invoice_items: List[InvoiceItem] | None = None, receipt: Receipt | str | Dict[str, Any] | None = None, user_fields: Dict[str, str] | None = None, success_url: str | None = None, success_url_method: str = 'GET', fail_url: str | None = None, fail_url_method: str = 'GET', signature_algorithm: str | SignatureAlgorithm = 'MD5') → InvoiceResponse[source]

Create invoice via Invoice API (JWT-based).

Parameters:

  • out_sum – Payment amount

  • description – Payment description

  • invoice_type – Invoice type (OneTime or Reusable)

  • inv_id – Invoice ID (optional)

  • culture – Language code (ru, en) (optional)

  • merchant_comments – Internal comment for staff (optional)

  • invoice_items – List of invoice items for fiscalization (optional)

  • receipt – Receipt data for fiscalization - Receipt model, JSON string or dict (optional). If provided and invoice_items is not, receipt items will be converted to invoice_items.

  • user_fields – Additional user parameters (optional)

  • success_url – Success redirect URL (optional)

  • success_url_method – HTTP method for success URL (GET or POST)

  • fail_url – Fail redirect URL (optional)

  • fail_url_method – HTTP method for fail URL (GET or POST)

  • signature_algorithm – Signature algorithm (optional, default: MD5)

Returns:

InvoiceResponse with invoice information (id, url, inv_id, encoded_id)

Raises:

  • APIError – If invoice creation fails

  • ValueError – If both invoice_items and receipt are provided

async deactivate_invoice(inv_id: int | None = None, invoice_id: str | None = None, encoded_id: str | None = None, signature_algorithm: str | SignatureAlgorithm = 'MD5') → None[source]

Deactivate invoice.

Parameters:

  • inv_id – Invoice ID (number specified by merchant)

  • invoice_id – Invoice identifier (returned from create_invoice)

  • encoded_id – Encoded invoice ID (last part of invoice URL)

  • signature_algorithm – Signature algorithm (optional, default: MD5)

Raises:
async get_invoice_information_list(current_page: int = 1, page_size: int = 10, invoice_statuses: List[str] | None = None, keywords: str | None = None, date_from: str | None = None, date_to: str | None = None, is_ascending: bool = True, invoice_types: List[str] | None = None, payment_aliases: List[str] | None = None, sum_from: float | None = None, sum_to: float | None = None, signature_algorithm: str | SignatureAlgorithm = 'MD5') → Dict[str, Any][source]

Get invoice information list.

Parameters:

  • current_page – Current page number (from 1)

  • page_size – Page size (number of invoices per page)

  • invoice_statuses – List of invoice statuses (paid, expired, notpaid)

  • keywords – Search keywords

  • date_from – Start date (ISO 8601 format)

  • date_to – End date (ISO 8601 format)

  • is_ascending – Sort ascending

  • invoice_types – List of invoice types (onetime, reusable)

  • payment_aliases – List of payment method aliases

  • sum_from – Minimum invoice amount

  • sum_to – Maximum invoice amount

  • signature_algorithm – Signature algorithm (optional, default: MD5)

Returns:

Dictionary with invoice list and pagination info

Raises:

APIError – If request fails

Refund Methods

Refund operations for RoboKassa API.

class aiorobokassa.api.refund.RefundMixin[source]

Bases: object

Mixin for refund operations.

async create_refund(invoice_id: int, amount: Decimal | None = None, signature_algorithm: str | SignatureAlgorithm = 'MD5') → Dict[str, str][source]

Create refund for invoice.

async create_refund_v2(op_key: str, refund_sum: Decimal | float | int | str | None = None, invoice_items: List[RefundItem] | None = None, signature_algorithm: str | SignatureAlgorithm = SignatureAlgorithm.SHA256) → RefundCreateResponse[source]

Create refund via Refund API (JWT-based).

Parameters:

  • op_key – Operation key (unique identifier from OpStateExt or Result2)

  • refund_sum – Partial refund amount (omit for full refund)

  • invoice_items – Invoice items to refund (optional)

  • signature_algorithm – Signature algorithm (HS256, HS384, or HS512, default: HS256)

Returns:

RefundCreateResponse with refund request information

Raises:
async get_refund_status(invoice_id: int, signature_algorithm: str | SignatureAlgorithm = 'MD5') → Dict[str, str][source]

Get refund status for invoice.

async get_refund_status_v2(request_id: str) → RefundStatusResponse[source]

Get refund status via Refund API.

Parameters:

request_id – Request ID (GUID) from RefundCreateResponse

Returns:

RefundStatusResponse with refund status information

Raises:

APIError – If request fails