Самостоятельная интеграция

QR‑код от Яндекс Пэй со Сплитом — сервис для оплаты покупок через СБП и частями в Сплит с помощью статического или динамического QR-кода.

Статический QR-код размещается в офлайн-магазине у кассы в виде специальной таблички, которую выдает Яндекс. Динамический QR-код можно отобразить на экране.

Покупатели могут проводить оплату по QR-коду:

• через СБП в любом банковском приложении;
• частями в Сплит через сервисы Яндекса (только для авторизованных пользователей).

Для интеграции с QR‑код от Яндекс Пэй со Сплитом вы можете использовать готовые решения из списка поддерживаемых кассовых ПО или настроить интеграцию самостоятельно через Cash Register API.

Интеграция доступна для кассового ПО и касс самообслуживания (КСО).

Подключение сервиса

Шаг 1. Регистрация и подача заявки

1. Зарегистрируйтесь в личном кабинете Яндекс Пэй.

2. Подайте заявку на подключение сервиса QR‑код от Яндекс Пэй.

   Важно

   В поле Кассовое ПО выберите значение Другое.

Шаг 2. Заполнение реестра обмена информацией

1. После подачи заявки предоставьте данные о ваших кассах и магазинах — заполните и отправьте менеджеру интеграции реестр для обмена информацией о магазинах.

   Какие данные необходимо заполнить

   • merchant_id — Merchant ID из личного кабинета Яндекс Пэй — идентификатор бренда или направления, к которому будет привязан магазин;
   • partner_alias — ИНН организации;
   • name — название магазина;
   • branch_id — уникальный код магазина в вашей системе;
   • offline_pos_legal_address — фактический адрес магазина (только для офлайн-магазинов);
   • tmid — идентификатор кассы или терминала, на которые будет крепиться физически QR-табличка;
   • contact_phone — контактный телефон ответственного лица в магазине;
   • QRID (заполняет Яндекс) — идентификатор QR-кода, напечатанный на QR-табличке, которая будет наклеена на кассе.

2. На основании данных реестра Яндекс доставит QR-таблички в указанные магазины.

3. Менеджер интеграции отправит вам обновленный реестр.

Шаг 3. Привязка QR-кода

После того как вы получите QR-таблички и обновленный реестр, привяжите QR-коды в двух местах:

Шаг 4. Получение параметров интеграции

Для интеграции вам обязательно понадобятся два токена:

• Токен для кассового ПО
• Ключ Merchant API (API-ключ)

Дополнительно вам понадобятся:

• Merchant ID для идентификации магазина.
• Callback URL для получения нотификаций о статусе платежей — /webhook. Если получение нотификаций невозможно, используйте поллинг.

Получение токена для кассового ПО

Получите токен у менеджера интеграции.

Используйте для аутентификации запросов.

Выпуск API-ключа

Для работы в боевой среде необходимо выпустить собственный API-ключ в личном кабинете Яндекс Пэй:

1. Проверьте, что в селекторе выбран нужный магазин, и перейдите в раздел Настройки → Выпустить ключ Merchant API.

2. В открывшемся окне отобразится API-ключ. Скопируйте и сохраните его.

   Совет

   После создания ключа рекомендуем сразу сохранить его, так как полное значение отображается только один раз — в момент создания. Повторно просмотреть уже созданный ключ не получится.

3. Если ранее вы использовали другой API-ключ для тестирования или работы, в коде бэкенда магазина замените текущий API-ключ на новый.

Если вы потеряете или забудете API-ключ, его нужно будет выпустить повторно. Для выпуска ключа в настройках нажмите Ключ Merchant API → Выпустить ещё ключ. Одновременно для магазина можно выпустить не более трех API-ключей.

Используйте для аутентификации запросов.

Merchant ID

Merchant ID — это уникальный идентификатор вашего магазина в системе Яндекс Пэй. Для одного юридического лица создается один магазин с Merchant ID и API-ключом.

Чтобы узнать уникальный Merchant ID магазина, выберите в селекторе нужный магазин и перейдите в раздел Настройки → Merchant ID.

Реализуйте на своей стороне связь Торговая точка ⇔ Касса ⇔ QR-код и при создании заказа передавайте информацию об отдельных торговых точках в поле extensions.billingReport.branchId.

Установка Callback URL

1. Перейдите в раздел Настройки → Добавить Callback URL.
2. В открывшемся окне укажите публично доступный HTTPS URL-адрес бэкенда магазина, для которого вы настраиваете интеграцию, и нажмите кнопку Сохранить.

Указывайте Callback URL без /v1/webhook — этот путь добавится автоматически, например:

URL-адрес для тестового и рабочего окружения может отличаться, например:

Шаг 5. Подключение оплаты в Сплит (опционально)

1. В личном кабинете Яндекс Пэй перейдите в раздел Настройки → Дополнительные сервисы.

2. Включите опцию Оплата частями в Сплит.

3. Ознакомьтесь с тарифом и условиями сервиса Яндекс Пэй для партнеров и нажмите кнопку Отлично, давайте.

   Важно

   Обратите внимание, что тариф вознаграждения за услуги сервиса изменится.

После этого покупатели смогут оплачивать покупки вашем магазине в Сплит.

Отключение оплаты в Сплит

Чтобы отключить оплату в Сплит с помощью QR‑кода от Яндекс Пэй, отключите опцию Оплата частями в Сплит в настройках магазина.

Шаг 6. Настройка интеграции

Изучите как работает Cash Register API, реализуйте и протестируйте все сценарии.

Как это работает?

Схема проведения оплаты

Изучите глоссарий и настройте кассовое ПО так, чтобы поддерживались следующие операции:

• Аутентификация запросов
• Оформление заказа с помощью статического или динамического QR
• Деактивация (прерывание оплаты)
• Возврат
• Получение нотификаций

Глоссарий

При работе с API важно понимать разницу между заказом, корзиной, позициями и товарами:

{
  "orderId": "order-123",              // ← ЗАКАЗ — запрос на оплату
  "cart": {                            // ← КОРЗИНА — контейнер для позиций
    "items": [                         // ← Массив ПОЗИЦИЙ КОРЗИНЫ
      {                                // ← ПОЗИЦИЯ #1
        "productId": "id-1",           // ← Идентификатор ТОВАРА
        "title": "Шариковая ручка",    // ← Название ТОВАРА
        "quantity": {
          "count": "3"                 // ← Количество ТОВАРА
        },
        "unitPrice": "3.33",           // ← Цена за ЕДИНИЦУ ТОВАРА
        "total": "10"                  // ← Сумма ПОЗИЦИИ
      }
    ],
    "total": {
      "amount": "10"                   // ← Сумма КОРЗИНЫ: 10₽
    }
  }
}

• Заказ — запрос на оплату с уникальным orderId.
• Корзина — набор позиций для оплаты — cart.
• Позиция корзины — элемент массива items[] с информацией о товаре.
• Товар — продукт, который описывается в позиции (ручка, мясо, услуга).
• Единица — одна штука, килограмм, литр товара.
• Количество — сколько единиц товара в позиции — quantity.count.
• Цена за единицу — стоимость одной единицы — unitPrice.
• Сумма позиции — итоговая стоимость одной позиции в корзине — items[i].total. Может не быть равна quantity.count * unitPrice.
• Сумма корзины — общая стоимость всех позиций в корзине — cart.total.amount.

Аутентификация запросов

В каждом запросе передавайте в HTTP-заголовки:

Если в запросе отсутствуют или переданы недействительные токены, сервер вернет статус 401 Unauthorized.

Пример запроса:

curl https://pay.yandex.ru/api/merchant/cash-register/v1/accounts \
  --header 'Authorization: Api-Key <YandexPayApiKey>' \
  --header 'Software-Authorization: <SoftwareAuthorization>' \

Оформление заказа

1. Покупатель формирует корзину.

2. Кассир фиксирует корзину в кассовом ПО.

3. Кассир выбирает способ оплаты Яндекс Пэй.

4. Кассовое ПО передает заказ в бэкенд Яндекс Пэй одним из методов:

   • для статического QR: /orders

   • для динамического QR: /orders/dynamic

     с параметрами:

     qrcId	Обязателен только для статического QR. Идентификатор зарегистрированного в СБП QR-кода. Его можно получить с помощью метода /accounts.
     cart	Корзина. Если в корзине есть позиции с нецелыми ценами (3 ручки за 10 рублей) или весовые товары (500 г. говядины), для всех позиций в корзине добавьте цену за единицу товара unitPrice. Это избавит от проблем с округлением, например, при возврате.
     currencyCode	Трехбуквенный код валюты (ISO 4217).
     orderId	ID заказа в системе продавца.
     extensions.billingReport	Информация о торговой точке и кассире. Реализуйте на своей стороне связь Торговая точка ⇔ Касса ⇔ QR-код и передавайте в этом параметре.

5. Бэкенд Яндекс Пэй создает заказ:

   • для статического QR: связывает заказ с полученным в запросе QR-кодом;

   • для динамического QR: генерирует уникальный QR-код для заказа.

6. В обоих случаях бэкенд Яндекс Пэй возвращает поле paymentUrl с уникальной ссылкой на оплату.

   Отобразите эту ссылку в виде QR-кода на экране или распечатайте.

7. Кассир просит покупателя отсканировать:

   • для статического QR: QR-табличку;

   • для динамического QR: QR-код на экране или в чеке.

8. Покупатель сканирует QR-код, открывает страницу оплаты, выбирает способ оплаты и подтверждает платеж.

9. Кассовое ПО отслеживает статус заказа.

   Основной способ получения информации об изменении заказа — нотификации /webhook. Если получение нотификаций невозможно, используйте поллинг.

   Нотификации

   Поллинг

   Если у вас настроены нотификации, то после завершения оплаты Яндекс Пэй отправит событие ORDER_STATUS_UPDATED — обновлен статус заказа.

   Проверьте поле paymentStatus:

   CAPTURED	Оплата прошла успешно. Фискализируйте чек. Терминальный успешный статус.
   FAILED	Оплата не прошла или при проведении оплаты произошла ошибка. Пересоздайте заказ методом /orders или /orders/dynamic. Терминальный неуспешный статус.

   Через 5–10 секунд после создания заказа начните опрашивать статус заказа методом /orders/{orderId}.

   Проверьте поле paymentStatus:

   PENDING	Оплата в процессе. Запросите статус позже или дождитесь нотификации.
   CAPTURED	Оплата прошла успешно. Фискализируйте чек. Терминальный успешный статус.
   FAILED	Оплата не прошла или при проведении оплаты произошла ошибка. Пересоздайте заказ методом /orders или /orders/dynamic. Терминальный неуспешный статус.

   Примечание

   Не забудьте фискализировать оплату на кассе в соответствии с Федеральным законом № 54-ФЗ.

Деактивация (прерывание оплаты)

1. Перед деактивацией кассовое ПО вызывает метод /orders/{orderId} и проверяет поле paymentStatus.

   Деактивация доступна только для заказов в статусе PENDING. Если оплата уже прошла, вернется ошибка ORDER_ALREADY_CAPTURED. В таком случае проведите возврат.

2. Кассовое ПО вызывает метод /orders/{orderId}/deactivate и передает externalOperationId — уникальный идентификатор операции. По нему можно узнать статус операции и он служит токеном идемпотентности.

3. В результате QR-код будет деактивирован, а заказ перейдет в статус FAILED.

   Если у вас настроены нотификации, Яндекс Пэй отправит событие ORDER_STATUS_UPDATED — обновлен статус заказа.

Возврат

1. Перед оформлением возврата кассовое ПО вызывает метод /orders/{orderId} и проверяет поле paymentStatus.

   Возврат доступен только для заказов в статусе CAPTURED или PARTIALLY_REFUNDED.

2. Кассир формирует чек возврата в кассовом ПО.

3. Кассовое ПО вызывает метод /orders/{orderId}/refund с параметрами:

   externalOperationId	Уникальный идентификатор операции на стороне продавца. По нему можно узнать статус операции и он служит токеном идемпотентности.
   refundAmount	Сумма к возврату.
   refundCart	Корзина возвращаемых позиций. Обязательна для частичного возврата. Формат зависит от вида логики возвратов.

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

   Основной способ получения информации об изменении заказа — нотификации /webhook. Если получение нотификаций невозможно, используйте поллинг.

   Нотификации

   Поллинг

   Если у вас настроены нотификации, Яндекс Пэй отправит два события:

   • ORDER_STATUS_UPDATED — обновлен статус заказа;
   • OPERATION_STATUS_UPDATED — обновлен статус операции возврата.

   В нотификации OPERATION_STATUS_UPDATED проверьте статус операции status:

   SUCCESS	Операция возврата запущена успешно. Фискализируйте чек возврата.
   FAIL	Операция возврата не запущена. Повторно инициируйте возврат методом /orders/{orderId}/refund.

   Если возврат прошел успешно, заказ перейдет в статус PARTIALLY_REFUNDED или REFUNDED.

   Начните опрашивать статус заказа методом /orders/{orderId}. Найдите нужную операцию по externalOperationId и проверяйте ее статус status:

   PENDING	Операция возврата не завершена. Запросите статус позже или дождитесь нотификации.
   SUCCESS	Операция возврата запущена успешно. Фискализируйте чек возврата.
   FAIL	Операция возврата не запущена. Повторно инициируйте возврат методом /orders/{orderId}/refund.

   Если возврат прошел успешно, заказ перейдет в статус PARTIALLY_REFUNDED или REFUNDED.

Две логики возвратов

Cash Register API поддерживает две логики работы с возвратами. Логика определяется при создании заказа по наличию в позициях корзины cart цены за единицу товара unitPrice.

Различия проявляются при частичных возвратах — когда в refundCart указываются конкретные позиции для возврата.

{
  "productId": "id-1",
  "title": "Шариковая ручка",
  "total": "50",
  "quantity": {
    "count": "10"
  }
}

{
  "productId": "id-1",
  "title": "Шариковая ручка",
  "total": "10",
  "quantity": {
    "count": "3"
  },
  "unitPrice": "3.33"
}

{
  "refundCart": {
    "items": [
      {
        "productId": "id-1",
        "quantityCount": "2"
      }
    ]
  },
  "refundAmount": "10"
}

{
  "refundCart": {
    "items": [
      {
        "productId": "id-1",
        "quantityCount": "1",
        "total": "3.33"
      }
    ]
  },
  "refundAmount": "3.33"
}

Больше примеров возвратов см. на странице метода Вернуть деньги за заказ.

Получение нотификаций

Основной способ получения информации об изменении заказа — нотификации /webhook.

Бэкенд Яндекс Пэй отправляет нотификации со следующими событиями:

• ORDER_STATUS_UPDATED — обновлен статус заказа;
• OPERATION_STATUS_UPDATED — обновлен статус операции.

Чтобы получать нотификации:

1. В личном кабинете Яндекс Пэй установите Callback URL.

2. Настройте ваш бэкенд для приема POST-запроса /webhook от бэкенда Яндекс Пэй.

Примеры нотификаций см. на странице метода /webhook.

Оформление заказа в кассе самообслуживания

Процесс аналогичен оформлению заказа в кассовом ПО со следующим отличием:

1. После создания заказа методы /orders и /orders/dynamic возвращают поле paymentUrl с уникальной ссылкой на оплату.
2. Отобразите эту ссылку на экране КСО в виде QR-кода.

Тестирование

Получение списка QR-табличек

Вызовите метод /v1/accounts и получите список QR-табличек.

Если в ответе статус 5XX, повторите запрос.

Успешное оформление с оплатой

1. Создайте и оплатите заказ по инструкции Оформление заказа.
2. Проверьте, что оплата прошла успешно — заказ в статусе CAPTURED.

Успешное оформление с оплатой и полным возвратом

1. Создайте и оплатите заказ по инструкции Оформление заказа.
2. Проверьте, что оплата прошла успешно — заказ в статусе CAPTURED.
3. Совершите полный возврат средств по инструкциям:
   • Возврат
   • {#T}
4. Проверьте, что возврат прошел успешно — заказ в статусе REFUNDED.

Успешное оформление с оплатой и частичным возвратом

1. Создайте и оплатите заказ по инструкции Оформление заказа.
2. Проверьте, что оплата прошла успешно — заказ в статусе CAPTURED.
3. Совершите частичный возврат средств по инструкциям:
   • Возврат
   • {#T}
4. Проверьте, что возврат прошел успешно — заказ в статусе PARTIALLY_REFUNDED.

Деактивация заказа

1. Создайте заказ методом /orders, но не оплачивайте его.
2. Деактивируйте заказ по инструкции Деактивация (прерывание оплаты).
3. Отсканируйте QR-код камерой смартфона и убедитесь, что страница оплаты недоступна.
4. Проверьте, что заказ деактивирован — в статусе FAILED.

Закрывающие документы

Ежедневные и ежемесячные отчеты можно получать тремя способами:

• по email — используется по умолчанию, отчеты будут отправляться на указанные адреса почты;
• по SFTP-протоколу — отчеты будут отправляться в папку на SFTP-сервере партнера;
• в S3-хранилище — отчеты будут отправляться в бакет в S3-хранилище партнера.

Подробнее читайте в разделе Отчетность.