Skip to main content
Glama
robokassa-mcp

robokassa-mcp


Comprehensive Python client and Model Context Protocol server for Robokassa — the Russian payment gateway.

Covers the full API surface: checkout, XML status interfaces, refunds, holding (pre-auth), recurring subscriptions, 54-ФЗ fiscal receipts, Partner API, and auxiliary endpoints.

Install (once published)

# As an MCP server for Claude Desktop / Claude Code / Cursor / Windsurf
uvx robokassa-mcp

# As a Python library
pip install robokassa-mcp

Related MCP server: YooKassa MCP Server

Use as a Python library

import asyncio
from decimal import Decimal
from robokassa import create_invoice, RobokassaClient

# Build a signed checkout URL (no HTTP — just URL construction).
invoice = create_invoice(
    merchant_login="my-shop",
    out_sum=Decimal("599.00"),
    inv_id=12345,
    password1="...",
    description="Premium subscription",
    email="user@example.com",
)
print(invoice.url)  # https://auth.robokassa.ru/Merchant/Index.aspx?...

# Check the state of a payment (hits the OpStateExt XML endpoint).
async def check() -> None:
    async with RobokassaClient("my-shop", password2="...") as client:
        state = await client.check_payment(inv_id=12345)
        print(state.is_paid, state.info.op_key)

asyncio.run(check())

Full refund flow

from robokassa import RobokassaClient

async def refund_flow(inv_id: int) -> None:
    async with RobokassaClient("my-shop", password2="p2", password3="p3") as client:
        # 1. Fetch the payment state to get its OpKey.
        state = await client.check_payment(inv_id)
        assert state.info.op_key, "payment not complete yet"

        # 2. Initiate a refund.
        created = await client.refund_create(state.info.op_key)
        print("refund requestId:", created.request_id)

        # 3. Poll status until finished / canceled.
        while True:
            status = await client.refund_status(created.request_id)
            if status.is_terminal:
                print("final:", status.state)
                break

Webhook signature verification (FastAPI example)

from fastapi import FastAPI, Request, HTTPException, PlainTextResponse
from robokassa import verify_result_signature, build_ok_response

app = FastAPI()

@app.post("/robokassa/result")
async def result_url(req: Request) -> PlainTextResponse:
    form = dict(await req.form())
    if not verify_result_signature(form, password2="..."):
        raise HTTPException(status_code=403, detail="Bad signature")
    # ... persist the notification, mark invoice paid ...
    return PlainTextResponse(build_ok_response(form["InvId"]))

Use as an MCP server

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "robokassa": {
      "command": "uvx",
      "args": ["robokassa-mcp"],
      "env": {
        "ROBOKASSA_LOGIN": "your-shop-login",
        "ROBOKASSA_PASSWORD1": "password1",
        "ROBOKASSA_PASSWORD2": "password2",
        "ROBOKASSA_PASSWORD3": "password3"
      }
    }
  }
}

Claude Code

claude mcp add robokassa \
  -e ROBOKASSA_LOGIN=my-shop \
  -e ROBOKASSA_PASSWORD1=... \
  -e ROBOKASSA_PASSWORD2=... \
  -e ROBOKASSA_PASSWORD3=... \
  -- uvx robokassa-mcp

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "robokassa": {
      "command": "uvx",
      "args": ["robokassa-mcp"],
      "env": {
        "ROBOKASSA_LOGIN": "your-shop-login",
        "ROBOKASSA_PASSWORD1": "password1",
        "ROBOKASSA_PASSWORD2": "password2",
        "ROBOKASSA_PASSWORD3": "password3"
      }
    }
  }
}

VS Code (GitHub Copilot)

In user or workspace settings.json:

{
  "github.copilot.chat.mcp.servers": {
    "robokassa": {
      "command": "uvx",
      "args": ["robokassa-mcp"],
      "env": {
        "ROBOKASSA_LOGIN": "your-shop-login",
        "ROBOKASSA_PASSWORD1": "password1",
        "ROBOKASSA_PASSWORD2": "password2",
        "ROBOKASSA_PASSWORD3": "password3"
      }
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "robokassa": {
      "command": "uvx",
      "args": ["robokassa-mcp"],
      "env": {
        "ROBOKASSA_LOGIN": "your-shop-login",
        "ROBOKASSA_PASSWORD1": "password1",
        "ROBOKASSA_PASSWORD2": "password2",
        "ROBOKASSA_PASSWORD3": "password3"
      }
    }
  }
}

HTTP transport (MCP Inspector, remote clients)

uvx robokassa-mcp --transport http --port 8000

Flags: --transport {stdio,http,streamable-http,sse}, --host, --port.

MCP tools exposed to agents

All 18 tools are wrapped as @mcp.tool() and available to any MCP-capable agent (Claude Desktop, Claude Code, Cursor, Windsurf, etc.).

Tool

Purpose

Auth

create_invoice

Build a signed checkout URL (optional 54-ФЗ receipt).

Password#1

check_payment

Get current state of a payment by InvId (via OpStateExt).

Password#2

list_currencies

List payment methods available to the shop.

—

calc_out_sum

Compute amount credited to shop for a given payment.

Password#1

refund_create

Initiate a refund (requires Refund API access).

Password#3 JWT

refund_status

Poll refund progress by requestId.

—

verify_result_signature

Validate a ResultURL webhook.

Password#2

verify_success_signature

Validate a SuccessURL redirect.

Password#1

hold_init / hold_confirm / hold_cancel

Two-step card pre-authorization.

Password#1

init_recurring_parent / recurring_charge

Subscription auto-charges.

Password#1

build_split_invoice

Marketplace multi-recipient checkout.

—

send_sms

Paid SMS service.

Password#1

second_receipt_create / second_receipt_status

54-ФЗ final receipt after advance.

Password#1

partner_refund

Alternative refund path for partner integrators.

Partner JWT

Low-level signature helpers are available from Python only: compute_signature, op_state_signature, build_checkout_signature, build_refund_jwt, build_sms_signature, compute_result_signature, compute_success_signature, encode_fiscal_body.

API coverage

Mapped against the 8 public Robokassa API groups:

Group

Coverage

Module

Merchant Checkout

✅ create_invoice (+ 54-ФЗ)

robokassa.checkout

XML Interfaces

✅ check_payment, list_currencies, calc_out_sum

robokassa.xml_interface

Refund API

✅ refund_create, refund_status

robokassa.refund

Holding / Pre-auth

✅ init / confirm / cancel

robokassa.holding

Recurring

✅ parent + child

robokassa.recurring

Fiscal 54-ФЗ

✅ second receipt create / status

robokassa.fiscal

Partner API

🟡 partner_refund only — see coverage notes

robokassa.partner

Auxiliary

✅ send_sms, webhook signatures, split payments

robokassa.sms, robokassa.webhooks, robokassa.split

Environment variables

Most high-level entry points fall back to these env vars when credentials aren't passed explicitly:

Variable

Required for

ROBOKASSA_LOGIN

All operations

ROBOKASSA_PASSWORD1

Checkout, webhook SuccessURL verification, CalcOutSumm, fiscal, SMS

ROBOKASSA_PASSWORD2

check_payment (OpStateExt), webhook ResultURL verification

ROBOKASSA_PASSWORD3

refund_create

Signature algorithms

All signature-producing helpers accept algorithm= with "md5" / "sha256" / "sha384" / "sha512" — match whatever is configured in your Robokassa cabinet.

Development

git clone https://github.com/artgas1/robokassa-mcp.git
cd robokassa-mcp
uv sync --all-extras --dev
uv run pytest            # 107+ unit tests
uv run ruff check .
uv run pyright

License

MIT — see LICENSE. Drop-and-forget maintenance; PRs welcome but not guaranteed to be reviewed promptly.

Available Tools

18 tools
build_split_invoiceC

Build a URL for a multi-recipient (marketplace-style) split payment.

Each split: {merchantLogin, amount, description?}. Sum of amounts must equal out_amount.

Inputs: out_amount (required), splits (required), email, inc_curr, +2 more. Returns: object

calc_out_sumA

Calculate the amount credited to the shop for a given customer payment.

Useful for showing the commission / final sum in checkout UI.

Signature: <algorithm>(MerchantLogin:IncSum:Password#1).

Inputs: inc_sum (required), merchant_login, password1, inc_curr_label, +1 more. Returns: object

check_paymentA

Check the current state of a Robokassa payment by invoice ID.

Uses the OpStateExt XML interface. Returns a structured summary including the state code (5/10/20/50/60/80/100), the OpKey (required later for initiating a refund via Refund/Create), sums, payment method, and any user-defined Shp_* parameters attached at checkout.

State codes: 5 — инициализирована, не оплачена 10 — отменена (таймаут / пользователь) 20 — HOLD (предавторизация) 50 — средства получены, зачисление магазину 60 — отказ в зачислении, средства возвращены покупателю (это НЕ пользовательский refund — для него используйте refund_status) 80 — приостановлена (security check) 100 — оплачена ✅

Credentials may be passed explicitly or via ROBOKASSA_LOGIN / ROBOKASSA_PASSWORD2 environment variables.

Note: OpStateExt does NOT reflect post-payment refunds initiated through the Robokassa cabinet or Refund/Create. For that, store the requestId from Refund/Create and poll Refund/GetState.

Inputs: inv_id (required), merchant_login, password2, algorithm. Returns: object

create_invoiceA

Build a signed Robokassa checkout URL + form fields for a new payment.

Does NOT make an HTTP request — produces the URL to redirect the user to.

Inputs: out_sum (required), inv_id (required), description, merchant_login, +9 more. Returns: object

hold_cancelC

Release a hold without capturing the reserved funds.

Inputs: inv_id (required), merchant_login, password1, algorithm. Returns: object

hold_confirmA

Capture previously-reserved funds for a held transaction.

Cart can be reduced (smaller receipt_items) before capture, but not increased. Pass the same OutSum (possibly smaller) as the original hold.

Inputs: out_sum (required), inv_id (required), merchant_login, password1, +3 more. Returns: object

hold_initA

Build a checkout URL with StepByStep=true for two-step pre-auth.

Funds are reserved on the card; use hold_confirm to capture or hold_cancel to release. Max hold window: 7 days.

Notification for successful hold is delivered to ResultURL2 (not the standard ResultURL). Requires prior agreement with Robokassa and only works with card payments.

Inputs: out_sum (required), inv_id (required), description, merchant_login, +7 more. Returns: object

init_recurring_parentA

Build a checkout URL marking the payment as a recurring parent.

After the user pays, the shop can silently charge subsequent amounts via recurring_charge citing this invoice's inv_id.

Inputs: out_sum (required), inv_id (required), description, merchant_login, +7 more. Returns: object

list_currenciesA

List payment methods / currencies available to a Robokassa shop.

Returns the full catalogue grouped by payment family (BankCard, SBP, SberPay, YandexPay, etc.) with per-method Label, Alias, Name, and min/max transaction bounds where applicable.

The Label values are what you pass as IncCurrLabel when calling create_invoice to restrict the user to a specific payment method.

No password / signature required — GetCurrencies is a public endpoint.

Inputs: merchant_login, language. Returns: object

partner_refundA

Alternative refund path via Partner API (for CPA / SaaS integrators).

Merchant-only users should prefer refund_create instead (uses Password#3). Partner API requires RoboxPartnerId and partner-specific auth headers — typically {"Authorization": "Bearer <partner-jwt>"}.

Inputs: robox_partner_id (required), op_key (required), auth_headers (required), refund_sum, +1 more. Returns: object

recurring_chargeA

Silently charge a recurring subscription payment.

previous_inv_id must be the inv_id of an already-paid parent (created with init_recurring_parent). Response "OK<InvId>" means accepted, NOT captured — verify via check_payment.

Inputs: new_inv_id (required), previous_inv_id (required), out_sum (required), description, +5 more. Returns: object

refund_createA

Initiate a refund for a successful Robokassa payment.

Requires op_key — obtained from check_payment (OpStateExt) or the Result2 webhook payload for the original operation.

Refund amount: - Omit refund_sum for a FULL refund of the original operation. - Pass a numeric amount for a partial refund.

Fiscal receipt: - Omit items to refund without emitting a fiscal receipt (appropriate when the original sale was not fiscalized through Robokassa). - Pass a list of items to emit a receipt for the refund. Each item: {name, quantity, cost, tax, payment_method, payment_object} where tax ∈ none/vat0/vat5/vat7/vat10/vat20/vat105/vat107/vat110/vat120, payment_method ∈ full_payment/advance/..., payment_object ∈ commodity/service/payment/...

Authentication: Uses JWT signed with Password#3. This is distinct from Password#1 (checkout) and Password#2 (XML status). Access to the Refund API must be enabled in the Robokassa cabinet separately.

Returns: {success: bool, request_id: str | None, message: str | None}. Store request_id to poll refund status via refund_status. Common failure messages: NotEnoughOperationFunds, OperationNotFound, AlreadyRefunded.

Credentials may be passed explicitly or via the ROBOKASSA_PASSWORD3 env var.

Inputs: op_key (required), password3, refund_sum, items, +1 more. Returns: object

refund_statusA

Check the current state of a previously-created refund request.

Inputs: request_id (required). Returns: object

second_receipt_createA

Emit a final (second) 54-ФЗ fiscal receipt after an advance/prepayment sale.

For merchants using Robokassa Fiscal. merchant_id is the Fiscal merchantId (e.g. robokassa_sell); origin_id is the InvId of the original operation. Max 2 receipts per operation.

items: [{name, quantity, sum, tax, payment_method, payment_object}]. payments: typically [{type: 2, sum: <total>}] for offsetting a prepayment. client: {email} or {phone}.

Inputs: merchant_id (required), receipt_id (required), origin_id (required), items (required), +7 more. Returns: object

second_receipt_statusA

Check registration status of a 54-ФЗ fiscal receipt.

Use merchant_id="robokassa_state" for status lookups.

Inputs: merchant_id (required), receipt_id (required), password1. Returns: object

send_smsA

Send an SMS via Robokassa's SMS service.

Paid feature — requires a non-zero SMS balance in the cabinet. Phone must be in international format (e.g. 79991234567).

Inputs: phone (required), message (required), merchant_login, password1, +1 more. Returns: object

verify_result_signatureA

Verify the SignatureValue on a Robokassa ResultURL request.

Robokassa POSTs payment notifications to the merchant's ResultURL after a successful checkout. The merchant must verify the signature to confirm the notification is authentic, then respond with the string returned by build_ok_response(inv_id) — otherwise Robokassa retries.

Inputs: params (required), password2, algorithm. Returns: object

verify_success_signatureA

Verify the SignatureValue on a Robokassa SuccessURL redirect.

SuccessURL is the browser-side redirect after payment completes. Unlike ResultURL it does NOT mean the payment is credited — only that the user returned to the success page. Still, verifying the signature guards against CSRF / tampering.

Inputs: params (required), password1, algorithm. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 18 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes (e.g., hold_init, hold_confirm, hold_cancel are separate steps). The only potential confusion is between refund_create and partner_refund, but descriptions clarify the difference. Overall, tools are well-differentiated.

    Naming Consistency4/5

    Tool names predominantly follow a verb_noun pattern (e.g., build_split_invoice, create_invoice). A few deviate (hold_cancel, hold_confirm), but the naming is still predictable and readable.

    Tool Count4/5

    With 18 tools covering standard payments, holds, recurring, refunds, fiscal receipts, and utilities, the count is slightly high but well-justified for a comprehensive payment MCP server.

    Completeness4/5

    The tool surface covers core payment lifecycle operations. Missing an explicit cancel payment tool for non-hold payments, but agents can work around via states. Overall, nearly complete for the domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server that enables AI agents to accept Bitcoin Lightning payments. It allows agents to create orders, generate invoices, check payment status, and manage the full SatsRail merchant API through natural language.
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      A local MCP server that lets AI agents interact with the Adaptis (MEG) payment gateway, enabling payment link creation, transaction queries, refunds, and integration helpers like generating signed forms and verifying callbacks.
      -