---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://pay.yandex.ru/docs/en/custom/integration-guide.md
  - https://pay.yandex.ru/docs/ru/custom/integration-guide.md
  - href: ru/custom/integration-guide.md
    type: text/markdown
    title: Markdown version
  - href: ../llms.txt
    type: text/markdown
    title: llms.txt
title: "Яндекс\_Пэй для интернет-магазинов\_— комплексное руководство | Документация"
description: Полное руководство по интеграции для e-commerce. Выбор способа подключения и пошаговые инструкции.
---
> **Documentation Index:** Fetch the complete configuration index at https://pay.yandex.ru/docs/ru/llms.txt


# Интеграция для онлайн-магазинов

{% note tip %}

Для полноценной интеграции используйте [API Яндекс Пэй](./back-index) вместе с [SDK Яндекс Пэй](./front-index). SDK предоставляет готовые умные бейджи, виджеты и кнопки оплаты, которые можно быстро добавить на ваш сайт или в приложение.

{% endnote %}

<!--

#### Демо {#demo}

## Подключение сервиса {#connect}

Подключение сервиса осуществляется в личном кабинете в разделе [Сервисы](https://pay.yandex.ru/docs/ru/console/registration.md).

-->

## План интеграции {#plan}

1. [Подайте заявку](https://pay.yandex.ru/docs/ru/console/registration.md#application) в личном кабинете и дождитесь письма об активации тестовой среды.

1. [Выберите и настройте](../payments/index#mechanics) подходящую платежную механику.

1. Следуйте инструкциям по установке SDK Яндекс Пэй для [Web](https://pay.yandex.ru/docs/ru/custom/web-sdk/index.md) или [Mobile](https://pay.yandex.ru/docs/ru/custom/mobile-sdk/index.yaml) в зависимости от используемой технологии, чтобы установить бейджи, виджеты и кнопки как показано в [гайде](https://pay.yandex.ru/docs/ru/custom/index.md#guide).

   {% cut "Как выглядят элементы фронтенда?" %}

   {% list tabs %}

   - Кнопки оплаты
   
     {% include notitle [_](./web-sdk/_snippets/buttons--v4.mdx) %}
   
   - Виджет
   
     {% include notitle [_](./web-sdk/_snippets/ultimate-widget.mdx) %}

     Управляйте элементом, изменяя значения в выпадающих списках **Тема виджета**, **Padding виджета** и т. д.
   
   {% endlist %}

   {% endcut %}

   {% note warning %}

   Запрещено встраивать Яндекс Пэй в WebView при подключении в мобильных приложениях. Это небезопасно.

   {% endnote %}

1. Проверьте работу сервиса в тестовой среде:

   <!-- source: ru/_includes/testing.md -->
   1. В личном кабинете выберите в [селекторе](https://pay.yandex.ru/docs/ru/console/management.md#selector) ваш магазин.
   1. Перейдите в раздел [Настройки](https://console.pay.yandex.ru/settings) и правом верхнем углу включите опцию **Тестовые данные**, чтобы посмотреть параметры интеграции для тестовой среды.
   1. [Заполните](https://pay.yandex.ru/docs/ru/console/settings-pay-split.md#callback-settings) поле **Callback URL** `Тестовый`, если хотите, чтобы Яндекс Пэй присылал [уведомления](https://pay.yandex.ru/docs/ru/custom/backend/merchant-api/webhook.md) по Merchant API.
   1. [Настройте](https://pay.yandex.ru/docs/ru/custom/backend/merchant-api/index.md) декодирование сообщений.
   1. Проведите [тестирование](https://pay.yandex.ru/docs/ru/testing.md#pay-split).
   <!-- endsource: ru/_includes/testing.md -->

1. После получения уведомления о подключении сервиса переключите среду с тестовой на боевую:

   <!-- source: ru/_includes/testing.md -->
   1. В разделе **Настройки** отключите опцию **Тестовые данные**, чтобы посмотреть параметры интеграции для боевой среды.
   1. Заполните поле **Callback URL**.
   1. Выпустите [API-ключ](https://pay.yandex.ru/docs/ru/console/settings-pay-split.md#merchant-api-keys).
   1. Проведите тестирование в боевой среде.
   <!-- endsource: ru/_includes/testing.md -->

1. Не забудьте про [фискализацию](https://pay.yandex.ru/docs/ru/fiscalization.md). Вы готовы принимать оплату.

## Способы и механики оплаты

О доступных способах и механиках оплаты для онлайн-магазинов читайте в разделе [Способы оплаты и платежные механики](https://pay.yandex.ru/docs/ru/payments/index.md).

<!--
## Доступные платежные механики {#payment}
 
{% list tabs %}

- Полная оплата

  {% note info %}
  
  Данная механика **подходит** для способов оплаты: банковской картой (в том числе **Картой Плюса**), **СБП**, в **Сплит**.

  {% endnote %}

  Клиентский путь проведения оплаты покупки выполняется в следующей последовательности:

  {% cut "Схема" %}

  ![image](./_assets/button-scheme.png)

  {% endcut %}

  1. Покупатель формирует корзину товаров на сайте продавца. По факту готовности оплатить покупатель нажимает размещенную ранее продавцом кнопку оплаты Яндекс Пэй.
  2. После нажатия кнопки оплаты Яндекс Пэй:

     1. Из Yandex Pay SDK вызывается callback на фронтенде магазина.
     2. Фронтенд магазина создает заказ на бэкенде магазина.
     3. Бэкенд магазина передает заказ в бэкенд Yandex методом [/orders](https://pay.yandex.ru/docs/ru/custom/backend/yandex-pay-api/order/merchant_v1_orders-post.md). В ответ возвращается ссылка для перенаправления покупателя на фронтенд проведения оплаты в Yandex.
     4. Фронтенд магазина получает ссылку на заказ Пэй, которую транслирует в Yandex Pay SDK.

  3. Yandex Pay SDK загружает с бэкенда Yandex информацию о корзине товаров, которую необходимо оплатить покупателю.
  4. Yandex Pay SDK отображает покупателю форму оплаты с информацией о корзине товаров.

     1. В случае Web SDK происходит перенаправление на полученную ссылку для оплаты.
     2. В случае Mobile SDK открывается формы для оплаты.

  5. Покупатель авторизуется со своим Яндекс ID, если ранее он не был авторизован на Яндексе. Подробнее про использование сервиса Яндекс ID в вашей компании читайте в [документации](https://yandex.ru/dev/id/doc/ru/).
  6. Покупатель выбирает способ оплаты покупки (Пэй или Сплит) и нажимает кнопку оплаты.
      1. {% include notitle [pay-type](../_includes/pay-type.md) %}
      2. Если выбран Сплит, то покупатель выбирает интересующее количество платежей и выполняет первый платеж со своих привязанных карт либо привязывает новую.

  7. Яндекс Пэй проводит платеж, списывая денежные средства с выбранной карты покупателя.
  8. Яндекс Пэй уведомляет продавца о статусе платежа через вызов [/webhook](https://pay.yandex.ru/docs/ru/custom/backend/merchant-api/webhook.md), если был настроен [Callback URL](https://pay.yandex.ru/docs/ru/console/settings.md#callback-settings). Также бэкенд магазина может самостоятельно получить статус заказа через запрос [/orders/\{order_id\}](https://pay.yandex.ru/docs/ru/custom/backend/yandex-pay-api/order/merchant_v1_order-get.md):

     1. `PENDING` — оплата еще в процессе, нужно запросить статус платежа позже. В нотификации данный статус не отправляется.
     2. `FAILED` — оплата завершилась неудачно. Терминальный неуспешный статус.
     3. `CAPTURED` — оплата совершена. Терминальный успешный статус.

  9. Яндекс Пэй перенаправляет покупателя на полученные в методе [/orders](https://pay.yandex.ru/docs/ru/custom/backend/yandex-pay-api/order/merchant_v1_orders-post.md) ссылки для успешных или неуспешных оплат.
  10. На следующие сутки продавцу осуществляется финансирование покупки.

- Рекуррентные платежи (Подписка)

  Если вы предлагаете своим покупателям товары или услуги по подписке, узнайте, как это работает в Яндекс Пэй.

  {% note info %}
  
  Данная механика **не подходит** для способа оплаты в **Сплит**.

  {% endnote %}

  Клиентский путь проведения оплаты рекуррентных платежей выполняется в следующей последовательности:

  {% cut "Схема" %}

  ![image.png](_assets/scheme-recurrents.png)

  {% endcut %}

  1. Покупатель формирует корзину товаров на сайте продавца. Здесь же выбирает продукт “Подписка“ и его условия. Продукты могут быть следующего вида

     1. Периодичность подписки в единицах измерения и их количество;

     2. Сумма следующих списаний;

     3. Наличие пробного периода (Триал): до конкретной даты или периодичность с единицей измерения

  2. По факту готовности оплатить покупатель нажимает размещенную ранее продавцом кнопку оплаты Яндекс Пэй.

  3. После нажатия кнопки оплаты Яндекс Пэй:

     1. Из SDK Яндекс Пэй вызывается callback на фронтенде магазина.

     2. Фронтенд магазина создает заказ на бэкенде магазина.

     3. Бэкенд магазина передает заказ в бэкенд Яндекс методом [/subscriptions](https://pay.yandex.ru/ru/docs/custom/backend/yandex-pay-api/subscriptions/merchant_v1_subscriptions-post). В ответ возвращается ссылка для перенаправления покупателя на фронтенд проведения оплаты в Яндекс.

     4. Фронтенд магазина получает ссылку на заказ Пэй, которую транслирует в SDK Яндекс Пэй.

  4. SDK Яндекс Пэй загружает с бэкенда Яндекс информацию о корзине товаров, которую необходимо оплатить покупателю.

  5. SDK Яндекс Пэй отображает покупателю форму оплаты с информацией о корзине товаров и условиями подписки.

     1. В случае Web SDK происходит перенаправление на полученную ссылку для оплаты.

     2. В случае Mobile SDK открывается формы для оплаты.

  6. Покупатель приступает к привязке карты, 
  
   - Открывает ссылку на оплату (привязку),
   - Авторизуется с [Яндекс ID](https://yandex.ru/dev/id/doc/ru/), если не был авторизован ранее,
   - Выбирает способ оплаты и нажимает кнопку оплаты (в случае полной оплаты с кешбэком выбирает сохраненную в Яндексе карту или СБП-привяку к счету),
   - В случае выбора товара или услуги с пробным периодом,  проходит процедуру привязки карты иподтверждает списание тестовой суммы (1 руб.) для проверки 3ds. Сумма (1 руб.) будет возращена после прохождения проверки.

  7. Яндекс Пэй проводит платеж, списывая денежные средства с выбранной карты покупателя.

  8. Чтобы получать уведомления о статусе оплаты, настройте бэкенд магазина так, чтобы он вызывал метод [/orders/{order_id}](./custom/backend/yandex-pay-api/order/merchant_v1_order-get) или ожидал уведомления по [/webhook](./custom/backend/merchant-api/webhook) (для этого настройте также параметр [Callback URL](https://pay.yandex.ru/docs/ru/console/settings-pay-split.md#callback-settings) в личном кабинете Яндекс Пэй).

   Статусы оплаты:

   #|
   || PENDING |

   Оплата в процессе. Повторите запрос позже.

   Статус не отправляется в уведомлениях. ||
   || FAILED |

   Оплата завершилась неудачей либо покупатель не успел привязать свою карту за отведенное ему время (параметр `ttl`).

   Терминальный неуспешный статус. ||
   || CAPTURED |

   Оплата прошла успешно.

   Терминальный успешный статус. ||
   |#

  9. Деньги за покупку поступят партнеру на следующие сутки. Если был у продукта подписки Триал, то денежные средства за покупку не перечисляются, продавцу нужно списать самостоятельно деньги в дату завершения Триала.

  <h2>Списание средств</h2>

  Продавец инициирует списание денежных средств у клиента по факту завершения предыдущей подписки или если завершился пробный период.
  
  1. Настройте бэкенд магазина так, чтобы после формирования корзины товаров для оплаты он вызывал метод [/subscriptions/recur](./custom/backend/yandex-pay-api/subscriptions/merchant_v1_subscriptions_recur-post), и передавал в поле `parentOrderId` параметр `orderId`, чтобы произошла ассоциация новой оплаты с первоначальным платежом и списание стоимости,

  1. Чтобы получать уведомления о статусе оплаты, настройте бэкенд магазина так, чтобы он вызывал метод [/orders/{order_id}](./custom/backend/yandex-pay-api/order/merchant_v1_order-get) или ожидал уведомления по [/webhook](./custom/backend/merchant-api/webhook) (для этого настройте также параметр [Callback URL](https://pay.yandex.ru/docs/ru/console/settings-pay-split.md#callback-settings) в личном кабинете Яндекс Пэй).

   Статусы оплаты:

   #|
   || PENDING |

   Оплата в процессе. Повторите запрос позже.

   Статус не отправляется в уведомлениях. ||
   || FAILED |

   Оплата завершилась неудачей либо покупатель не успел привязать свою карту за отведенное ему время (параметр `ttl`).

   Терминальный неуспешный статус. ||
   || CAPTURED |

   Оплата прошла успешно.

   Терминальный успешный статус. ||
   |#

  11. Деньги за покупку поступят партнеру на следующие сутки.

- Рекарринговый платеж (Привязка карты)

  Если вы хотите предложить вашим клиентам привязать карту для автоматических списаний, узнайте, как это работает в Яндекс Пэй.

  {% note info %}
  
  Данная механика **не подходит** для способа оплаты в **Сплит**.

  {% endnote %}

  <h2>Привязка карты</h2>

  1. Разместите кнопку привязки карты в удобном месте (например, в разделе «Способы оплаты»),

  1. Настройте бэкенд магазина так, чтобы после нажатия на кнопку он вызывал метод [/merchant_v1_subscriptions](./custom/backend/yandex-pay-api/subscriptions/merchant_v1_subscriptions-post),

  1. В ответ на метод, бэкенд магазина получит ссылку на оплату (см. параметр `paymentUrl`) и уникальный идентификатор подиски (см. параметр `subscriptionId`),

  1. Настройте бэкенд магазина так, чтобы он передавал значение параметра `paymentUrl` в SDK, а ссылка открылась в браузере покупателя.

  1. Чтобы получать уведомления о статусе оплаты, настройте бэкенд магазина так, чтобы он вызывал метод [/orders/{order_id}](./custom/backend/yandex-pay-api/order/merchant_v1_order-get) или ожидал уведомления по [/webhook](./custom/backend/merchant-api/webhook) (для этого настройте также параметр [Callback URL](https://pay.yandex.ru/docs/ru/console/settings-pay-split.md#callback-settings) в личном кабинете Яндекс Пэй).

    Статусы привязки:

     #|
     || PENDING |

   Привязка карты в процессе. Повторите запрос позже.

   Статус не отправляется в уведомлениях. ||
     || FAILED |

   Привязка карты завершилась неудачей либо покупатель не успел привязать свою карту за отведенное ему время (параметр `ttl`).

   Терминальный неуспешный статус. ||
     || CAPTURED |

   Карта привязана.

   Терминальный успешный статус. ||
     |#

  1. Покупатель приступает к привязке карты,
  
   - Открывает ссылку на оплату (привязку),
   - Авторизуется с [Яндекс ID](https://yandex.ru/dev/id/doc/ru/), если не был авторизован ранее,
   - Выбирает карту для привязки или добавляет новую,
   - Подтверждает списание тестовой суммы (1 руб.) для проверки 3ds. Сумма (1 руб.) будет возращена после прохождения проверки.
  
  1. Настройте страницу с информацией о статусе привязке карты и кнопкой возврата в магазин так, чтобы нажатие на кнопку вызывало URL, переданный ранее в параметре `redirectUrls`.

  1. Настройте отображение для пользователя информации о добавленной карте для оплаты (переданные в параметре `paymentMethod` метода [/orders/{order_id}](./custom/backend/yandex-pay-api/order/merchant_v1_order-get) и конпки для привязки новой карты при помощи Яндекс Пэй.

  Например:

   #|
   || cardLast4 | Последние 4 цифры привязанной карты ||
   || cardNetwork | Платежная система привязанной карты ||
   |#

  <h2>Списание средств</h2>
  
  1. Настройте бэкенд магазина так, чтобы после формирования корзины товаров для оплаты, он вызывал метод [/subscriptions/recur](./custom/backend/yandex-pay-api/subscriptions/merchant_v1_subscriptions_recur-post), и передавал в поле `parentOrderId` параметр `orderId`,

  1. Происходит списание стоимости заказа с карты, которая была привязана.

  1. Чтобы получать уведомления о статусе оплаты, настройте бэкенд магазина так, чтобы он вызывал метод [/orders/{order_id}](./custom/backend/yandex-pay-api/order/merchant_v1_order-get) или ожидал уведомления по [/webhook](./custom/backend/merchant-api/webhook) (для этого настройте также параметр [Callback URL](https://pay.yandex.ru/docs/ru/console/settings-pay-split.md#callback-settings) в личном кабинете Яндекс Пэй).

   Статусы оплаты:

   #|
   || PENDING |

   Оплата в процессе. Повторите запрос позже.

   Статус не отправляется в уведомлениях. ||
   || FAILED |

   Оплата завершилась неудачей либо покупатель не успел привязать свою карту за отведенное ему время (параметр `ttl`).

   Терминальный неуспешный статус. ||
   || CAPTURED |

   Оплата прошла успешно.

   Терминальный успешный статус. ||
   |#

11. Деньги за покупку поступят партнеру на следующие сутки.

{% endlist %}

## Возврат платежа {#refund}

Проведение возврата возможно двумя способами:

1. В личном кабинете в разделе [Платежи](https://pay.yandex.ru/docs/ru/custom/refund-payments.md).
1. Через [интеграцию по API](https://pay.yandex.ru/docs/ru/custom/refund-payments.md).

<!--

## Что дальше {#next-step}

{% include notitle [pay-testing](../_includes/pay-testing.md) %}

-->

{% included (./web-sdk/_snippets/buttons--v4.mdx) %}
<!-- markdownlint-disable -->

<div class="ypd-preview">
    <a href="https://yastatic.net/s3/pay-static/docs/v46.0.0/custom/buttons--v4/index.html" target="_blank">
        <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24"><path fill="currentColor" d="M18 19H6c-.55 0-1-.45-1-1V6c0-.55.45-1 1-1h5c.55 0 1-.45 1-1s-.45-1-1-1H5c-1.11 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2v-6c0-.55-.45-1-1-1s-1 .45-1 1v5c0 .55-.45 1-1 1zM14 4c0 .55.45 1 1 1h2.59l-9.13 9.13c-.39.39-.39 1.02 0 1.41.39.39 1.02.39 1.41 0L19 6.41V9c0 .55.45 1 1 1s1-.45 1-1V3h-6c-.55 0-1 .45-1 1z"></path></svg>
    </a>
    <iframe src="https://yastatic.net/s3/pay-static/docs/v46.0.0/custom/buttons--v4/index.html" style="height: 500px"></iframe>
</div>

{% endincluded %}
{% included (./web-sdk/_snippets/ultimate-widget.mdx) %}
<!-- markdownlint-disable -->

<div class="ypd-preview">
    <a href="https://yastatic.net/s3/pay-static/docs/v46.0.0/custom/ultimate-widget/index.html" target="_blank">
        <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24"><path fill="currentColor" d="M18 19H6c-.55 0-1-.45-1-1V6c0-.55.45-1 1-1h5c.55 0 1-.45 1-1s-.45-1-1-1H5c-1.11 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2v-6c0-.55-.45-1-1-1s-1 .45-1 1v5c0 .55-.45 1-1 1zM14 4c0 .55.45 1 1 1h2.59l-9.13 9.13c-.39.39-.39 1.02 0 1.41.39.39 1.02.39 1.41 0L19 6.41V9c0 .55.45 1 1 1s1-.45 1-1V3h-6c-.55 0-1 .45-1 1z"></path></svg>
    </a>
    <iframe src="https://yastatic.net/s3/pay-static/docs/v46.0.0/custom/ultimate-widget/index.html" style="height: 800px"></iframe>
</div>

{% endincluded %}