io.github.artgas1/robokassa-mcp

Build a URL for a multi-recipient (marketplace-style) split payment. Each split: `{merchantLogin, amount, description?}`. Sum of amounts must equal out_amount.

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)`.

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.

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.

Release a hold without capturing the reserved funds.

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.

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.

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`.

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.

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>"}`.

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`.

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.

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

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}`.

Check registration status of a 54-ФЗ fiscal receipt. Use `merchant_id="robokassa_state"` for status lookups.

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`).

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.

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.