Instructions for Yandex Pay and Split payments

The add-on adds the Yandex Pay payment processor to CS-Cart, allows the store to accept Yandex Pay and Yandex Split payments, display Yandex widgets and badges on the storefront, and map payment results to CS-Cart order statuses.

What the add-on does

• Adds the MS: Yandex Pay payment processor for CS-Cart payment methods.
• Creates an order in the Yandex Pay API and redirects the customer to the returned payment URL.
• Lets the administrator choose available payment methods: Yandex Pay only, Yandex Split only, or both.
• Displays the payment widget on the product page and, when enabled in the payment method, on checkout.
• Displays Yandex badges in catalog and other storefront blocks.
• Sends the customer contact to Yandex for fiscalization: e-mail first, otherwise phone number.
• Updates the order status after the customer returns from the payment page using the Success / Failed status mapping.

Where to find the add-on

• Add-on settings: Add-ons → Downloaded add-ons → Yandex Pay and Split payments.
• Payment methods: Administration → Payment methods or Add-ons → Payment methods, depending on the CS-Cart version.
• Processor in the payment method form: MS: Yandex Pay.

Yandex credentials

You need the following data from the Yandex Pay dashboard:

• Merchant ID — seller identifier. It is used in add-on widget settings and in payment method parameters.
• API key — key for production mode. In production mode the add-on sends it in the Authorization: Api-Key header.
• Test mode — enabled in the payment method parameters. In test mode the add-on uses the Yandex test API URL and uses Merchant ID as the authorization key.

The add-on code has no separate Client ID field.

Add-on settings

General

• Merchant ID — Merchant ID for storefront widgets.
• Order status mapping — CS-Cart order statuses for Success and Failed results. If no status is selected, the add-on uses defaults: Open for successful payment and Failed for unsuccessful payment.

In stores with multiple storefronts, select the required storefront before configuring status mapping.

Widget

• Widget display on the product page — extended view, compact view, or do not display.
• Payment method widget methods — card, Split, or card and Split.
• Widget configuration — Yandex Pay Web SDK parameters. They can be prepared in the Yandex interactive demo and pasted into the settings field.
• Checkout widget position — do not display, under the order total, or above products.
• Checkout block display type — collapsed, expanded, or simple.

Badge

• Display badges in the product catalog — enables storefront badge output.
• Display second badge — adds an additional badge.
• Badge position — under the price or under the entire product block.
• Badge configuration and second badge configuration — Yandex appearance parameters for badges. The add-on removes merchant-id, amount and sku-id from these fields because those values are calculated on the storefront.

Creating a payment method

1. Open the payment methods section and create a new payment method.
2. Select the MS: Yandex Pay processor.
3. Enable or disable Test mode.
4. Enter Merchant ID.
5. Enter the API key for production mode.
6. In Available payment methods, choose Yandex Pay and Yandex Split, Yandex Pay, or Yandex Split.
7. If the widget should be shown inside the payment method on checkout, enable Show widget on checkout.
8. Save the payment method and check that it is available for the required storefront and shipping methods.

Payment flow

1. The customer places an order and selects the Yandex Pay payment method.
2. The add-on sends an order creation request to Yandex with amount, currency, cart items, shipping and allowed payment methods.
3. If the order contains customer e-mail, it is sent in fiscalContact. If e-mail is empty, the add-on sends the phone number. If no contact is available, the field is not sent.
4. Yandex returns paymentUrl, and the add-on redirects the customer to the payment page.
5. After successful or failed return, the add-on completes payment processing in CS-Cart and assigns the mapped order status.

Webhook, hold, refund and fiscal receipts

• Webhook. The add-on uses CS-Cart return URLs payment_notification.success and payment_notification.fail with the order ID. There is no separate webhook URL setting in the add-on interface.
• Hold / capture. The add-on has no separate settings for two-step payment, hold or capture.
• Refunds. The add-on has no separate Yandex refund interface; refunds are handled outside the add-on according to the payment service and store rules.
• Fiscal receipts / 54-FZ. The add-on sends the customer contact in fiscalContact when it is available in the order. It has no own DigitalKassa settings, VAT rate settings or receipt generation interface.

How to verify operation

1. Open a product page on the storefront and check that the widget or badge is displayed according to add-on settings.
2. Add a product to cart and proceed to checkout.
3. Select the Yandex Pay payment method and make sure the available options match the setting: Yandex Pay, Split, or both.
4. Place a test order and confirm that the customer is redirected to the Yandex payment page.
5. After returning from the payment page, check the order status in CS-Cart.
6. To verify fiscal contact transfer, place one order with e-mail and another without e-mail but with a phone number: the add-on should send e-mail in the first case and phone number in the second.