docs.modx.pro
  1. Extras
  2. msp3YooKassa
  3. Integration

msp3YooKassa integration ​

Quick start — install, keys, webhook.

This page lines up the YooKassa API quick start with what msp3YooKassa does in code for MiniShop3.

Mapping to the YooKassa API ​

Quick start stepIn msp3YooKassa
POST /v3/payments with amount, capture, confirmation.type = redirect, return_urlYooKassaPayment::send() → SDK createPayment(), return_url from getReturnUrl() (success_url / fail_url or MS3 thanks page)
Idempotence-KeyOrder UUID or generated key
Redirect buyer to confirmation_urlPayment handler response with redirect / payment_link for the MS3 frontend
Wait for succeeded / handle cancelPrimarily webhooks → webhook.php → WebhookHandler

User confirmation for redirect is described under Payment process. One- vs two-stage maps to API capture: true in YooKassaPayment, false in YooKassaTwoStagePayment.

HTTP notifications (webhook) ​

In the YooKassa dashboard, configure the notification URL for your site:

text
https://your-domain.com/assets/components/msp3yookassa/webhook.php

Test shop ​

Use a test shop and test keys (test_… secret key) in msp3yookassa_shop_id and msp3yookassa_secret_key. Pay with test cards only — never real cards in test mode. That restriction comes from YooKassa.

For production, switch to live Shop ID and secret key from the Quick start guidance.

54-FZ receipts ​

Enable msp3yookassa_payment_receipt and set msp3yookassa_vat_code. A receipt object is added to createPayment (order lines, delivery if delivery_cost > 0, customer email). See Receipt basics.

In the test shop you can use receipt verification mode in the dashboard: YooKassa simulates OFD interaction without a real fiscal receipt — useful to validate payload shape (see Testing).

The code sets tax_system_code to 1. To override, use a plugin on the receipt-line MODX event mspYooKassaOnPreparePaymentReceiptItem (defined in the extra) or extend ReceiptBuilder.

Payment methods shown to the buyer ​

Cards, SBP, wallets, etc. are chosen on YooKassa’s side after redirect to confirmation_url. The extra does not embed the widget or a custom card form — it uses redirect, as in the Quick start example.

One-stage payment flow ​

  1. Customer checks out and selects YooKassa payment.
  2. YooKassaPayment::send() creates a payment (capture: true), stores yookassa_payment_id in order properties, returns a redirect URL for the frontend.
  3. YooKassa sends an HTTP notification to assets/components/msp3yookassa/webhook.php.
  4. WebhookHandler resolves the order via metadata.order_id / order_num, verifies order_hash, and on succeeded sets status_id to ms3_status_paid.
  5. The buyer returns via success_url or the MiniShop3 thanks page.

The webhook is the source of truth for payment success, not the browser redirect alone.

Webhook ​

  • URL: https://<domain>/assets/components/msp3yookassa/webhook.php
  • Method: from YooKassa — POST, body: JSON (event, object with status, id, metadata).
  • Handled statuses:
    • succeeded — order set to ms3_status_paid, yookassa_payment_id updated in properties.
    • canceled — order set to ms3_status_canceled.
  • Other statuses may be logged when msp3yookassa_debug is on. They do not change the order.
  • Processing is idempotent if the order is already paid.

Security ​

order_hash in metadata is compared with getOrderHash() from the active YooKassa payment handler. Follow YooKassa webhook documentation for optional signature verification. Extend webhook.php if you enable it.

Two-stage payment ​

YooKassa payment (two-stage) (YooKassaTwoStagePayment) uses capture: false: funds are held until capture or cancellation.

MODX status behaviour ​

  • After a successful hold, YooKassa may send statuses such as waiting_for_capture. The current webhook handler does not change the MODX order status for those — the order stays as-is until succeeded or canceled.
  • Capture (see below) confirms the debit. The processor then sets ms3_status_paid.
  • Cancellation in YooKassa yields canceled — order gets ms3_status_canceled.

Plan your workflow (e.g. confirm in the MODX manager or your own tool before running Capture).

Capture processor ​

Class: Msp3YooKassa\Processors\CaptureProcessor. File: core/components/msp3yookassa/processors/capture.class.php.

Requirements:

  • Payment method class is Msp3YooKassa\Payment\YooKassaTwoStagePayment.
  • Order properties contain yookassa_payment_id.
  • msp3yookassa_shop_id and msp3yookassa_secret_key are configured.

Parameter: order_id — numeric MiniShop3 order ID.

Example PHP call:

php
$corePath = $modx->getOption('msp3yookassa_core_path', null, MODX_CORE_PATH . 'components/msp3yookassa/');
$response = $modx->runProcessor('capture', [
    'order_id' => 123,
], [
    'processors_path' => $corePath . 'processors/',
]);

if ($response->isError()) {
    $modx->log(modX::LOG_LEVEL_ERROR, $response->getMessage());
} else {
    // Capture succeeded. Order moved to ms3_status_paid
}

Error strings come from the msp3yookassa lexicon (invalid order, wrong payment type, missing payment id, etc.).

Receipt line event ​

Before each order product line is added to the receipt, a MODX system event named mspYooKassaOnPreparePaymentReceiptItem (as shipped in the extra) is fired.

Payload: order, orderProduct, item (YooKassa line array, mutable by reference). Use it to adjust descriptions, VAT, payment_subject / payment_mode.

Notes ​

  • Payment currency in code is RUB.
  • Minimum order amount for payment creation: 0.01.
  • Idempotence key for createPayment: order UUID or generated unique value.
  • vendor/autoload.php must be present in the component for the YooKassa SDK.

See also ​