Документация ЮKassa PRO (Расширенный протокол)

Лицензионный ключ отправляется автоматически на почту аккаунта покупателя, если письма Вы не нашли, проверьте папку спам, если письмо в спаме, то пожалуйста поставьте отметку не спам. При отсутствии ключа в папке спам напишите в поддержку.

Купить модуль можно по ссылке.
Зарегистрируйтесь по ссылке и получите особые условия: комиссия 2,8% за платежи картами, кошельком ЮMoney и через SberPay — независимо от оборота.

Последние версии модулей:
Магазины 1.5 - 4.1 (oc1.5)
Магазины 2.0-2.1 - 4.1 (oc2.0-2.1)
Магазины 2.2 - 4.1 (oc2.0-2.1)
Магазины 2.3 - 4.1 (oc2.3)
Магазины 3.0 - 5.2 (oc3.0)

Содержание:

  I. Установка
     a) Магазины 3, 2.3, 2.2, 2.1, 2.0
     b) Магазины 1.5
 II. Настройка
III. Настройка взаимодействия с онлайн-кассой
     a) Что нужно сделать
     b) Как работает решение
     c) Как отправлять данные для чеков через ЮКассу
     d) Интеграция с orange data
     e) Интеграция с МодульКасса
      f) Интеграция с АтолОнлайн
 IV.  Тестирование платежей
  V.  Перевод приема платежей в рабочий режим
 VI.  Обновление версии модуля
VII.  Переход с модуля от ЮКассы
VIII. FAQ
  IX. Настройка Признака предмета расчета и Признака способа расчета
IIX. Активация отложенной оплаты

I. Установка

Внимание! Архивы подписаны версией магазина, разные архивы для разных версий не совместимы. В названии архива префикс _for_

• oc3 - только для магазинов 3
• oc2.3 - только для магазинов 2.3
• oc2.2 - только для магазинов 2.2
• oc2.0-2.1 - только для магазинов 2.0 и 2.1
• oc1.5 - только для магазинов 1.5.3, 1.5.4, 1.5.5, 1.5.6

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

 

a) Магазины 3, 2.3, 2.2, 2.1, 2.0

Автоматическая установка:

1. Разархивируйте архив, внутри архива 2 файла - readme.txt и yandexur-pro.ocmod.zip
2. В админ панели сайта меню Дополнения - Установка дополнений - Загрузите архив yandexur-pro.ocmod.zip
3. Если возникли ошибки с установщиком - проверьте настройки фтп или установите расширение по ссылке (также возможна установка вручную - см. пункт Установка вручную)
4. Меню Менеджер дополнений (Модификации) - обновите кэш модификаций
5. Установите нужные модули в разделе Дополнения - платежи (Оплата)

Установка вручную:

1. Разархивируйте архив, внутри архива 2 файла - readme.txt и yandexur-pro.ocmod.zip
2. Разархивируйте архив yandexur-pro.ocmod.zip, внутри папка upload и файл install.xml
3. С помощью файлового доступа к сайту (ftp или ssh) загрузите все содержимое папки upload в корень сайта
4. Переименуйте install.xml в yandexur.ocmod.xml
5. В админ панели сайта меню Дополнения - Установка дополнений - Загрузите файл yandexur.ocmod.xml
6. Меню Менеджер дополнений (Модификации) - обновите кэш модификаций
7. Установите нужные модули в разделе Дополнения - платежи (Оплата)

 

b) Магазины 1.5

1. Разархивируйте архив, внутри архива 2 объекта - readme.txt и папка upload
2. С помощью файлового доступа к сайту (ftp или ssh) загрузите все содержимое папки upload в корень сайта
3. Установите нужные модули в разделе Дополнения - платежи (Оплата)

 

II. Настройка

1. Отправьте заявку на подключение к ЮКассе по ссылке
2. У Вас появится личный кабинет - далее ЛК
3. Заполните копии документов в ЛК
4. Подпишите договор
5. Во вкладке Настройки нажмите Заполнить. Выберите способ подключения API протокол и нажмите Продолжить.
6. Укажите адреса для уведомлений и включите все уведомления.

7. Нажмите далее

8. Выберите, как отправлять данные для чеков:

   Через ЮКассу — в этом случае вам нужно будет подключить онлайн-кассу одного из партнеров якассы. - Настройка взаимодействия с онлайн-кассой
   Решить позже — если вы точно не знаете, что делать с фискализацией, можете начать подключение, а эти настройки заполнить позже.
   Самостоятельно — платежи через ЮКассу проходят как обычно, фискальные данные в свою онлайн-кассу отправляете вы (вручную или через другой сервис).

9. Нажмите отправить.

10. В настройках модуля введите лицензионный ключ (как получить ключ?) установите статусы "Статус заказа после неуспешной или ожидаемой оплаты" и "Статус после удачной оплаты". Внимание статусы должны быть указаны разные.

11. Для банковских карт доступен выбор Способа транзакции (ТОЛЬКО API протокол) :
    Одностадийная - деньги списываются с карты без дополнительных подтверждений
    Двухстадийная - деньги блокируются на карте покупателя. У Вас есть 7 дней на подтверждение платежа банковской картой. Если вы не подтвердите платеж в отведенное время, деньги вернутся покупателю. Как только вы уверены в том, что готовы оказать услугу или выдать товар, необходимо подтвердить платеж. Если вы не можете оказать услугу или выдать товар, необходимо отменить платеж. Деньги вернутся пользователю, ЮКасса не будет удерживать комиссию за его проведение.

12. Установите статус модуля "включено" и сохраните настройки

13. ВНИМАНИЕ! Статусы заказов должны быть разные (созданный, оплаченный - либо при схеме отложенная или контроль наличия созданный, ожидание, оплаченный)

14. ВНИМАНИЕ! Если вы используете метод Выбор оплаты на стороне яКассы, то для него необходимо настроить все модули которые будут на стороне якассы (включать их не обязательно)

III. Настройка взаимодействия с онлайн-кассой

Этот шаг необходим только тем, кто собирается настраивать взаимодействие со своей онлайн-кассой через ЮКассу. Его следует пропустить, если вы самостоятельно отправляете в свою онлайн-кассу данные для чека или выбиваете чеки вручную. Данный раздел документации позволяет выбрать способ отправки фискальных данных вашей онлайн-кассе (по закону 54-ФЗ). Вы можете отправлять их с помощью ЮКассы или другим способом.

Для работы без дополнительных модулей зарегистрируйте кассу Атол-онлайн по ссылке (если вы выбрали урезанный тариф без офд, зарегистрируйте ОФД.РУ по ссылке), либо зарегисрируйте кассу FERMA в ОФД.РУ, зарегисрируйте кассу в фнс

a) Что нужно сделать:

1. Купить или арендовать онлайн-кассу (ККТ — контрольно-кассовая техника).
2. Заключить договор с оператором фискальных данных (ОФД).
3. Получить квалифицированную электронную подпись (КЭП, нужна для регистрации онлайн-кассы в налоговой).
4. Зарегистрировать онлайн-кассу в налоговой: в личном кабинете юрлица или ИП на сайте nalog.ru.
5. Отправлять фискальные данные через онлайн-кассу после каждого платежа.

Подробнее на сайте налоговой

b) Как работает решение:

1. Покупатель платит в вашем магазине как обычно. Вместе с запросом на оплату модуль передает ЮКассе данные для чека: названия товаров, количество, цену, ставку НДС, электронный адрес покупателя.
2. ЮКасса отправляет вашей онлайн-кассе данные для чека и ждет ответ.
3. Онлайн-касса формирует чек и отправляет оператору фискальных данных (ОФД).
4. Оператор присваивает чеку фискальный признак и отправляет вашей онлайн-кассе.
5. Онлайн-касса отвечает ЮКассе, что с чеком всё в порядке.
6. ЮКасса понимает, что всё по закону: налоговая получит чек от ОФД в тот же день, и отправляет вам сообщение об успешной оплате.
7. ОФД отправляет данные чека в налоговую — раз в сутки.
8. ОФД отправляет чек покупателю по email или sms(это дополнительная услуга).

 

c) Как отправлять данные для чеков через ЮКассу

1. Купите или арендуйте онлайн-кассу одного из партнеров ЮКассы (АТОЛ Онлайн, МодульКасса и Orange Data, поддержка других сервисов — в разработке), заключите договор с ОФД (например ofd.ru), зарегистрируйте онлайн-кассу в налоговой.
2. Поменяйте настройки в личном кабинете ЮКассы. Меню настройки магазина - кнопка подключить наше решение.
    

3. Пример редактирования настроек онлайн-кассы:

   
   Тип онлайн-кассы — партнер якассы, у которого вы купили или взяли в аренду онлайн-кассы.
   Данные в блоке Интеграция нужны, чтобы сервис партнера пропускал запросы к вашей онлайн-кассе. Их можно скопировать в личном кабинете вашей онлайн-кассы (или запросить у провайдера).
   Адрес в чеке — это место продажи, печатается в электронном чеке. Здесь может быть адрес вашего магазина (на карте) или адрес сайта (URL).
   Почта для ошибок — электронный адрес, на который якасса присылет сообщения о неполадках с отправкой данных для чеков. Если ваша онлайн-касса перестанет отвечать, на этот адрес придет письмо.
   Отправка данных для чека Определяет схему, по которой якасса работает с вашей онлайн-кассой.За 7 дней: сначала проводится оплату, а потом отправляются данные для чека в онлайн-кассу. Если онлайн-касса не ответит, оплата пройдет, но чек может так и не отправиться. В этом случае отправится письмо на Почту для ошибок.
   За 5 минут: сначала данные для чека отправляются в вашу онлайн-кассу. Когда от нее придет ответ, что с данными всё в порядке, якасса отправит вам уведомление об оплате. Если онлайн-касса не ответит в течение 5 минут (например, что-то случится на стороне провайдера), оплата не пройдет: деньги вернутся покупателю. Этот вариант гарантирует, что об оплаченном товаре узнает налоговая.

4. В настройках модуля отметьте пункт "Передача корзины" в положение "Да"
5. Ниже установите НДС - Без НДС - всем товарам в корзине будет присвоен налог без НДС. Принудительно - НДС будет присвоен всем товарам в корзине, выбирите нужный процент. Вариант " Из карточки товара" позволяет установить идивидуальную ставку для каждого товара в корзине - для этого обязательно создайте налоговый класс если первое поле справа пустое (система-локализация-налоги-налоговый класс), налоговые ставки создавать не надо. Укажите нужный налоговый класс в редактировании товара, а в таблице справа установите соответствие вашего налогового класса ставке НДС.

Внимание! В модуле "ЮКасса PRO - Мобильный терминал (Расширенный протокол) - Beta version" данные для чеков при оплате через мобильный терминал ЮКасса отправлять не может. Вам нужно сделать это самостоятельно.

Можно принимать платежи через ЮКассу, а данные для чеков отправлять другим способом (вручную или через другой сервис) - Если на стороне Юкассы вы выбрали вариант "Самостоятельно", то в настройках модуля отметьте пункт "Передача корзины" в положение "Нет"

 

f) Интеграция с АтолОнлайн

Для работы без дополнительных модулей зарегистрируйте кассу Атол-онлайн по ссылке (если вы выбрали урезанный тариф без офд, зарегистрируйте ОФД.РУ по ссылке), либо зарегисрируйте кассу FERMA в ОФД.РУ, зарегисрируйте кассу в фнс (для платных консультаций по регистрации кассы, Вы можете обратиться в поддержку)

В полях "Логин для токена","Пароль для токена" и "Код группы касс" указываются данные, полученные после регистрации в АТОЛ Онлайн их вы можете найти в личном кабинте атол-онлайн. Внимание! "Логин для токена","Пароль для токена" не совпадают с логином и паролем от личного кабинета АТОЛ Онлайн

 

IV. Тестирование платежей (ТОЛЬКО ПРОТОКОЛ HTTP)

Если вы планируете тестировать работу вашего магазина, при выборе способа подключения в личном кабинете поставьте галочку «Я буду проводить тестовые платежи». Когда ваш магазин подключат к тестовой среде, вам придет письмо с тестовыми параметрами. (Письмо отправляется на адрес контактного лица по техническим вопросам, который вы указали в личном кабинете.) Эти параметры появляются также в личном кабинете, в разделе Настройки. Подставьте их в платежную форму на вашем сайте.

1. В настройках модуля Выберите режим работы модуля: "Тестирование "
2. На витрине магазине добавьте товар в корзину и оформите заказ с методом оплаты (Банковскими картами - это наиболее простой и удобный вариант для тестирования)
3. Если вы получили ошибку на стороне якассы после перехода к оплате - включите в настройках модуля режим отладки и убидитесь в корректности передаваемых данных (сумме к оплате, а также если вы включили работу с онлайн кассами на стороне якассы то и в корректности передаваемых товарных позиций а также общей суммы к оплате и суммы товарных позиций)
4. На шлюзе якассы введите тестовые данные
    

   Номер карты: 4444 4444 4444 4448
   Действует до: любой год и месяц в будущем
   Код CVV: 000

5. Если вы получили ошибку на стороне якассы после ввода карты то это говорит о проблеме с checkurl - убедитесь что ваш checkurl отдает код 200 в логах доступа к сервера, это запись должна появлятся не посредственно после отправки данных о карте, убедитесь в отсутствии ошибок в журнале ошибок магазина (см faq по кодам ошибок), убедитесь в работе https, убедитесь в правильности адреса checkurl указанного на стороне юкассы)

6. После возврата в магазин вы должны увидеть страницу успешной оплаты, а также статус заказа должен измениться. (Если смена статуса заказа не произошла то это говорит о проблемах с AvisoUrl - убедитесь что ваш AvisoUrl отдает код 200 в логах доступа к сервера, это запись должна появлятся не посредственно после возврата на сайт, убедитесь в отсутствии ошибок в журнале ошибок магазина (см faq по кодам ошибок), убедитесь в правильности адреса AvisoUrl указанного на стороне юкассы)

 

V. Перевод приема платежей в рабочий режим

Вы можете перевести платежную форму в рабочий режим, если:

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

После этого технические специалисты выполнят настройку магазина на стороне ЮКассы и сообщат вам все необходимые параметры.

1. В настройках модуля введите новые данные если вы их получили
2. На витрине магазине добавьте товар в корзину и оформите заказ с методом оплаты (Банковскими картами - это наиболее простой и удобный вариант для тестирования)
3. Если вы получили ошибку на стороне якассы после перехода к оплате - включите в настройках модуля режим отладки и убидитесь в корректности передаваемых данных (сумме к оплате, а также если вы включили работу с онлайн кассами на стороне якассы то и в корректности передаваемых товарных позиций а также общей суммы к оплате и суммы товарных позиций)
4. На шлюзе якассы введите данные для платежа

5. После возврата в магазин вы должны увидеть страницу успешной оплаты, а также статус заказа должен измениться.

Если вы получили через какоето время ошибку фискализации платежа (При включенным режиме работы с онлайн-кассой)
Вот перечень основных ошибок:

• Ваш бухгалтер "по привычке" закрыл смену в интерфейсе онлайн-кассы (Атол, Модуль.Касса и т.д.). Пока смена закрыта, платежи не будут фискализироваться. Обычно закрытие смены происходит автоматически средствами используемой онлайн-кассы.
• В кассе не произведена первичная фискализация

Свяжитесь с поддержкой якассы а также с поддержкой вашей онлайн кассой для решения данных вопросов

 

VI. Обновление версии модуля

1. Обязательно сделайте бекап файлов сайта и базы
2. Удалите модификатор модуля(меню модификаторы или менеджер дополнений или папка system) если вы используете его (только для версии магазинов 2.х)
3. Установите модуль перезаписав файлы , пройдите все шаги установки.
4. Обновите кеш модификаторов (только для версии магазинов 2.х и 3.х)
5. Обязательно вставте заново api_key. Пересохраните настройки, если нужно внесите изменения в настройки
6. Убедитесь что адрес уведомлений не изменились как в модуле так и на стороне ЮKassa, и также включены все переключатели в уведомлениях юкасса в кабинете
7. Для магазинов 3х обновите кеш twig (главная страница админ панели, шестеренка справа вверху)

VII. Переход с модуля от ЮКассы

1. Удалите или отключите оплату родного модуля ЮКассы
2. Установите модуль
3. Смените адрес уведомлений или  checkUrl и AvisioUrl на стороне яКассы в ЛК
4. Частично повторите пунк II Настройки

 

VIII. FAQ

1.  При переходе на оплату текст No Data
В настройках модуля включите режим отладки, последняя строчка - это ошибка от юкассы

Также ошибки от No Data доступны в журнале магазина без включения режима отладки.

Данная ошибки это ответ от юкассы, читайте текст, самое частое неверная авторизация (shopid или api) или не корректный пароль -пробелы в начале в конце(Password has illegal format), метод недоступен на стороне Юкассы (подключите через менеджера), метод не доступен в модуле (на данный момент для api не доступен альфа-клик, промсвязьбанк, мобильный терминал, Masterpass, купивкредит, Ерип - данные методы только для старого протокола HTTP)

2. Расшифровка ошибок из лога магазина (журнал ошибок)

YandexUr Error: Hash not equal - не сходиться секретная фраза указанная в настройках модуля и написанная в анкете

YandexUr Error: Amount of payment not equal - не сходится сумма, оплата прошла на одну а в заказе другая.

YandexUr Error: This order alredy payed - заказ уже оплачен

Другие ошибки это ответ от Юкассы, читайте текст, самое частое неверная авторизация (shopid или api), метод недоступен на стороне Юкассы (подключите через менеджера), метод не доступен в модуле (на данный момент для api не доступен альфа-клик, промсвязьбанк, мобильный терминал, Masterpass, купивкредит, Ерип - данные методы только для старого протокола HTTP)

     В настройках модуля

     поле название метода оплаты добавить тег img (что такое тэг img и как он работает описано по ссылке)

     <img src="путь к картинке" /> Юmoney

4. Некорректно отображаются страницы успешной, неуспешной оплаты и страница повторной оплаты

Магазины 1.5, 2.0, 2.1, 2.2, 2.3
Необходимо привести tpl модуля в соответвие вашего шаблона (за эталон возьмите common/success.tpl)
скопируйте шаблоны модуля сatalog⁩/view⁩/theme⁩/default⁩/template⁩/account⁩/
yandexur_fail.tpl
yandexur_success.tpl
yandexur.tplв папку вашего шаблона по соответвующему пути, исправте верстку в них под ваш шаблон

Магазины 3.х
Необходимо привести tpl модуля в соответвие вашего шаблона (за эталон возьмите common/success.tpl)
скопируйте шаблоны модуля сatalog⁩/view⁩/theme⁩/default⁩/template⁩/extension/payment/
yandexur_fail.twig
yandexur_success.twig
yandexur_view.twig
в папку вашего шаблона по соответвующему пути, исправте верстку в них под ваш шаблон

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

Исправления под шаблон

Магазины 1.5
Отредактируйте xml файл из папки vqmod
блок catalog/view/theme/*/template/account/order_list.tpl в соответвии с вашим шаблоном

Магазины 1.5, 2.0, 2.1, 2.2, 2.3
Удалите модификатор, откройте архив модуля файл instal.xml
отредактируйте блок catalog/view/theme/*/template/account/order_list.tpl в соответвии с вашим шаблоном
переименуйте файл в yandexur.ocmod.xml  и установите через установщик, обновите кеш модификаторов

Магазины 3.х
отредактируйте сatalog⁩/view⁩/theme⁩/default⁩/template⁩/extension/payment/yandexur_aclink.twig
обновите кеш шаблонов twig

IX. Настройка признака способа и предмета расчета

В настройках модуля укажите Признак способа и предмета расчета - эти данные будут использоваться по умолчанию если вы выберите Признак предмета и/или способа для товара - пункт по умолчанию

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

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

Для значений в карточке товара указываете в нужном поле одно из следующих значений

Признак предмета расчета

Значение	Описание
commodity	Товар
excise	Подакцизный товар
job	Работа
service	Услуга
gambling_bet	Ставка в азартной игре
gambling_prize	Выигрыш в азартной игре
lottery	Лотерейный билет
lottery_prize	Выигрыш в лотерею
intellectual_activity	Результаты интеллектуальной деятельности
payment	Платеж
agent_commission	Агентское вознаграждение
composite	Несколько вариантов
another	Другое

 

Признак способа расчета

Значение	Описание
full_prepayment	Полная предоплата
partial_prepayment	Частичная предоплата
advance	Аванс
full_payment	Полный расчет
partial_payment	Частичный расчет и кредит
credit	Кредит
credit_payment	Выплата по кредиту

 

IIX. Активация отложенной оплаты