API Яндекс касса как сделать?

Новый API Яндекс.Кассы: платежное лего для e-commerce всех мастей

Буквально сегодня свет увидел новый API Яндекс.Кассы, разработанный программистами для программистов. Набор протоколов стал единообразным, логичным и простым в освоении. Но статья не об этом – я хочу рассказать, как и почему в один прекрасный момент API решено было переписать с нуля.

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

Исторически в Яндекс.Деньгах протоколы в API появлялись по мере необходимости и разрабатывались разными подразделениями – не стали исключением и сервисы Яндекс.Кассы.

Как получилось так, что нужен новый API

Яндекс.Касса – универсальное решение для онлайн-платежей – родилась в 2013 году в стенах Яндекс.Денег. С её помощью компании могут принимать оплату всеми популярными способами: из кошельков в Яндекс.Деньгах, с банковских карт, со счетов мобильных номеров или наличными через специальные терминалы.

Тогда Касса преимущественно состояла из протокола приема платежей через платежную форму. Этот протокол позволял через платежную форму на сайте контрагента перенаправить плательщика на сайт Яндекс.Денег и провести платеж.

Когда контрагентам потребовалось осуществлять возвраты, получать списки возвратов и платежей, для всего этого появился еще один новый протокол. Он работал на базе PKCS#7 криптопакетов и XML, а порог технического вхождения для него оказался достаточно высок. В общем, с реализацией справлялись только те, кто по-настоящему в этом нуждался.

Кроме того, в 2014 году появились протокол выплат и протокол эквайринга банковских карт для крупных контрагентов, которые прошли PCI DSS аудит и могут хранить данные банковских карт на своей стороне.

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

Именно поэтому мы поставили перед собой задачу значительно снизить технический порог входа в Яндекс.Кассу и сократить время интеграции с интернет-магазинами. Кроме того, новый API должен был не только учитывать лучшие мировые практики в отрасли, но и быть максимально удобным для разработчиков наших контрагентов.

Так появился новый API Яндекс.Кассы, который строился на трех основных принципах: единая модель данных для всего взаимодействия, однозначность признаков и статусов платежей, асинхронность при взаимодействии магазина с Яндекс.Кассой. Сейчас новый API покрывает все протоколы прошлой версии, кроме выплат – они появятся чуть позже.

Единая модель данных

При проектировании API мы использовали объектно-ориентированный подход на основные ценности REST-like протоколов. При этом старались использовать знакомые контрагентам и разработчикам сущности, которые уже существуют в их системах и процессах: платежи, возвраты, сохраненные способы оплаты (они же – привязки) и другие. Эту концепцию принято называть проблемно-ориентированным проектированием.

Структура объекта платежа неизменна от запроса к запросу и позволяет получать необходимую информацию в любой момент без необходимости хранить все это на своих серверах. Что особенно важно, это позволяет одинаково интерпретировать данные объекта в любое время. Создаете ли вы объект платежа (Payment) через POST, получаете его состояние через GET, подтверждаете или отменяете его – во всех ситуациях вы работаете с одним и тем же объектом Payment.

Пример объекта платежа (Payment).

Из соображений единообразия все объекты платежа, возврата, а также платежные методы живут по одним законам и обладают похожими признаками и структурой.

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

Однозначность признаков и статусов платежей

У платежных систем есть одна особенность, которая серьезно затрудняет реализацию протоколов по REST-like принципу: все сущности в рамках API обладают своим жизненным циклом. Он отличается от метода к методу и влияет на значения и структуру полей.

Мы стремились сделать количество статусов платежей и возвратов минимальным, чтобы клиенты Кассы могли реализовывать необходимую бизнес-логику только тогда, когда это действительно нужно. Для общего понимания разберем подробнее жизненный цикл платежа. Он состоит из трех состояний, как показано на рисунке:

Состояния платежа по новому жизненному циклу: waiting_for_capture присутствует не всегда – есть режим проведения платежа с автоматическим capture.

На стадии pending и waiting_for_capture платеж может быть отменен магазином или нами и тогда перейдет в статус canceled.

Ответ сервера при прохождении стадии waiting_for_capture.

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

Также мы даем контрагентам набор признаков, по которым можно получить дополнительную информацию: например, о необходимости подтверждения платежа пользователем, о внесении им денег или регистрации чека в облачной кассе для выполнения требований 54-ФЗ.

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

1. Создание платежа.
2. Получение подтверждения пользователя.
3. Регистрация чека в онлайн-кассе.
4. Подтверждение готовности принять платеж.
5. Получение денег на расчетный счет уже на следующий рабочий день.

Шаги 2-4 опциональны, но последовательность этих действий всегда неизменна.

Чтобы ознакомиться с реальными примерами, посмотрите в инструкциях раздел по проведению платежа «Быстрый старт».

Асинхронность при взаимодействии с Кассой

Начну издалека. API Яндекс.Кассы связывает магазин, покупателя, партнеров и эмитентов банковских карт (банк, который выпустил вашу карту), то есть в каждом платеже задействовано множество участников. Иногда ответ всех участников процесса занимает достаточно продолжительное время.

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

Чтобы поддерживать асинхронность и защититься от задвоения платежей, мы предлагаем использовать ключ идемпотентности. Если Касса по какой-то причине не успеет провести платеж за отведенное время, клиент API получит в ответе HTTP-код 202 (Request Accepted) с просьбой повторить запрос с тем же ключом чуть позже. Даже при множественных запросах с одним и тем же ключом и одинаковым телом запроса операция всегда будет совершена только один раз.

Пример запроса с ключом идемпотентности.

При этом достаточно выбрать генератор случайных чисел с минимально возможной коллизией (рекомендуем использовать v4 UUID). Мы запоминаем каждый из идентификаторов на 24 часа, после чего можно воспользоваться им повторно. При этом вам не нужно хранить ключ идемпотентности вечно – достаточно получить постоянный идентификатор объекта Платежа или Возврата, сгенерированного Кассой. Впоследствии вся работа с объектом осуществляется через этот идентификатор.

Некоторые процессы оплаты в Яндекс.Кассе асинхронны по своей природе. Например, при подтверждении оплаты через SMS в Сбербанке Онлайн контрагент должен передать нам номер телефона своего покупателя, а затем ожидать подтверждения платежа пользователем, на которое может уйти от нескольких минут до часа.

Поэтому Касса передает контрагенту информацию о факте отправки SMS-сообщения и ожидает подтверждения пользователем. В это время клиент Кассы может периодически повторять запросы о статусе платежа либо подписаться на уведомления от сервера, которые направляются на указанный в личном кабинете Кассы URL при смене статуса платежа. В обоих случаях контрагент получает полный объект Платежа.

Все эти решения позволяют компаниям не подстраивать свои бизнес-процессы под Яндекс.Кассу, а гибко встраивать наш API в любые платежные сценарии.

Как мы расширяем API, или Сначала попробуем сами

При создании предыдущих протоколов мы столкнулись с проблемой расхождения документации и реализации, потому что исходники документации существовали отдельно. В новом API с этим тоже нужно было покончить, поэтому для сборки документов решили использовать Swagger. Сейчас на рынке есть множество решений all-in-one, которые позволяют импортировать Swagger-спецификации, но идеальных с точки зрения кастомизации и информационного дизайна не нашлось.

Поэтому документы конвертировали с использованием формата Markdown, а в качестве инструмента для отображения выбрали Slate. Для прототипа каждой новой функции теперь используется спецификация в формате Swagger и сценарии, которые описывают последовательности действий и возможные исходы.

Классический сценарий добавления новых функций в API выглядит следующим образом: менеджер продукта создает Pull Request в репозиторий с документацией, сопровождая его ссылкой на измененный пользовательский сценарий. Pull Request проходит ревью как аналитиков, так и команды разработчиков API.

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

Как только новая функция реализована разработчиком, она тестируется по этой спецификации и далее отправляется на продакшен.

Dogfooding и мониторинг в перерывах

Перед тем как отдавать новую функцию пользователям, мы обязательно устраиваем «dogfooding», то есть сами пробуем наш продукт. Для этого используется специально разработанный демо-магазин, где можно купить виртуальную Капибару и реализовать другие сценарии клиентов Кассы. Вспомогательная цель его использования – снизить порог вхождения для сотрудников-новичков и показать платежные сценарии любому желающему внутри компании.

Как только мы вычитаем документацию, протестируем новые функции и убедимся в их простоте и понятности – выполняется Merge Pull Request Swagger-спецификации в master-ветку, чтобы она автоматически собралась в публичную документацию и попала на сайт.

После выпуска новой функции в мир наступает бесконечно увлекательный момент поддержки и мониторинга. Как и другие подразделения Яндекс.Денег, мы используем Grafana. Наблюдения проводятся с помощью множества метрик, поэтому приведу тут только основные: запросы к API, отправленные уведомления, успешность прохождения платежей и их подтверждение (capture), частота возникновения определенных ошибок.

Вместе с запуском нового API появился обновленный портал документации и SDK на PHP. Начался и постепенный переход наших CMS-модулей на новый протокол – сейчас регистрация на новый протокол доступна для OpenCart 1.5 и WooComerce. К ноябрю 2017 к ним присоединятся Y.CMS для Opencart 2, Prestashop, Webasyst Shop-Script, Drupal (модуль для Commerce и Ubercart), JoomShopping и SimplaCMS.

Мы также запускаем библиотеку YandexCheckout.js, которая позволяет создавать формы для приема карточных платежей любых форм и размеров. Первыми такую библиотеку 6 лет назад предложил Stripe. С тех пор нечто похожее сделали другие платежные агрегаторы для решения проблемы оплаты картами прямо на сайте интенет-магазина. Мы учли лучшие наработки наших западных коллег и выпустили YandexCheckout.js. Теперь компаниям не придется проходить полный и дорогой аудит PCI DSS, чтобы принимать платеж на своей стороне — достаточно заполнить опросник SAQ D и пройти ASV сканирование (с чем мы тоже можем помочь). Сейчас эта опция доступна в индивидуальном порядке, но открытие ее для всех как раз в планах на будущее.

И на десерт: вместе с новым API мы запускаем полноценную песочницу. Прямо в вашем личном кабинете теперь можно обкатывать основные платежные сценарии с использованием тестовых карт и кошельков.

Нет, мы не предлагаем все сломать и сделать заново

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

Если же вы сами разрабатываете новую площадку или давно ждали возможностей нового API – при регистрации будет использован уже обновленный API Яндекс.Кассы. В начале 2018 года также планируется публичный запуск возможности перевода старых магазинов на новый протокол.

Напоследок две самые важные ссылки:

Если у вас остались вопросы или опасения относительно нового API – приглашаю в комментарии к статье.

habr.com

WordPress.org

Поддержка → WooCommerce → передача API в модуль Яндекс.Кассы

передача API в модуль Яндекс.Кассы

Согласно новому 54-ФЗ (ФФД 1.05) в чеке необходимо выбивать новые поля:
1) предмета расчёта
и
2) способ расчёта.
Вопрос: что можно сделать, чтобы плагин Woocomerce передавал в чек информацию о ДОСТАВКЕ с признаком «предмет расчет» — «услуга».

Должно быть следующее:
Объект — receipt
Параметр — payment_subject
Значение — service

Или куда можно обратиться что бы это сделали за оплату?

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

Юрий, я использую шлюз Яндекс.Касса. Он уже принимает эти параметры. Но я не могу откорректировать информацию передаваемую в этот шлюз.
Связка следующая:
WordPress
Плагин Woocomerce
Плагин Яндекс.Касса

Доставка через API должна передаваться со следующими параметрами:
Объект — receipt
Параметр — payment_subject
Значение у параметра — service

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

я бы конечно посоветовала спросить в форуме поддержки плагина
https://wordpress.org/support/plugin/yandexkassa

но там похоже не отвечают совсем

Вы считаете, что будет правильно если кто-нибудь:

• Изменит WooCommerce
• Изменит Яндекс.Касса

без ведома их разработчиков, и по своему усмотрению, в надежде, что эти изменения будут приняты в новых версиях этих плагинов?

Вы понимаете какой срок жизни таких апдейтов?

У меня Яндекс.Касса 2. Все инструкции какие параметры надо передавать у них на сайте есть, но как сделать чтобы передавались эти параметры мне не понятно вообще.

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

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

надо что-то менять, а что, не понятно.

Как говорил кремлевский сантехник из анекдота застойных времен, тут надо менять всю систему.
[/offtop]

Я правильно понял, из всей связки wordpress, woocomerce и яндекс.касса это вопрос плагина яндекс.касса?

Да. WC, а тем более WP сами по себе вообще ничего не знают о существовании Яндекса.

Спасибо за ответ, теперь я хоть понимаю куда копать. Попробую обратиться в службу поддержки Яндекс.Касса.

А с Webmoney он работает?

Ура! Совместно с поддержкой Яндекс.Кассы удалось настроить. В моем случае это было не тривиально. У нас нет НДС и работаем на УСН. Фактически поля признак и предмет расчета появились в атрибутах к каждому товару и их можно задать, но для доставки это невозможно!
Решение следующее, в модуле Яндекс.Касса можно создать значения по умолчанию, кроме позиций у которых будет это указано, соответственно по умолчанию указываем признак — «Услуга», а для все товаров прописываем правильные признаки в карточке товара — закладка атрибуты.
Но! Поле — «значение атрибутов по умолчанию» появляется только если у Вас создана хотя бы одна налоговая ставка в Woocomerce. Но у меня НДС нет, пришлось создать произвольную налоговую ставку в Woocomerce, но к каждой карточке товара прописать что налога нет, и на доставку налога нет тоже. И вуаля, все работает. Товар у меня с признаком «товар», а доставка с признаком «услуга» и нет никаких проблем с налоговой.
Предостережение! Если вы не настроите правильно новый формат ФФН 1.05 с 1 января 2018 г., то при проверке налоговой могут быть санкции вплоть до отстранение генерального директора от работы на 3 месяца.

Браво! Я вас поздравляю.
Не так просто вырвать победу из лап Яндекса.

Но уверен, что передышка не надолго. Они, те «о ком мы не смеем говорить (с)», наверняка придумают пачку новых ФФН, ФЗ, УПЗ, ЗБС, ППЦ, ДЛБ, ЧВС, ПДР, ОХЕ, БЛТ и т.д.

Не расслабляетесь. Особенно некоторые мышцы организма, хоть и маленькие.

ru.wordpress.org

Подключение Яндекс Кассы к 1С Битрикс по API. Светлые дни

Йо-йо! Ранее я уже рассказывал о том как настроить кассу через платёжный модуль. Скажу вам честно, это был просто какой-то ад. И хоть на тот момент уже существовал способ подключения кассы по API, я не смог запустить её и с 5-го раза.

Но всё меняется и вот мне пришлось снова настраивать кассу причём на все настройки ушло 5 минут. По-этому я решил снова рассказать как подключить Яндекс Кассу к 1С Битрикс.

Я пропущу этап регистрации т.к. там из необходимого только выбрать тип подключения «API»

Шаг первый (Тестовая среда)

После регистрации вам выдаются секретных ключа и два shopId. Один для тестовой среды, второй для боевой соответственно.

Переходим в админ-панель битрикса и переходим по адресу:

Магазин > Настройки > Платёжные системы

И добавляем новую платёжную систему. Выбираем обработчик «Яндекс.Касса (yandexcheckout)». Тип оплаты «Эквайринговая операция», кодировка utf-8.

Опускаемся ниже и во вкладке «По умолчанию» нажимаем кнопку «Показать все». Там вводим наш ShopID и секретный ключ от тестового магазина.

Шаг два (Тестовый платёж)

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

Шаг 3 (Боевые настройки)

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

Переходим в Настройки и в пункте «HTTP-уведомления» > URL для уведомлений вписываем путь:
https://ваш_сайт/bitrix/tools/sale_ps_result.php.

«ваш_сайт», конечно же, меняем на адрес вашего сайта. Далее переходим на страницу настройки модуля «интернет-магазин»

Настройки > Настройки продукта > Настройки модулей > Интернет магазин

Там переходим во вкладку «Автоматизация процессов» и проверяем, чтобы в пункте «При получении полной оплаты переводить заказ в статус» была выбрано «Получен формируется к отправке». Это нужно, чтобы в заказа статус оплаты автоматически менялся.

Переходим опять в настройки платёжных систем и выбираем нашу

Магазин > Настройки > Платёжные системы

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

Настройка онлайн кассы

Из-за того, что в интернет-магазинах как правило работает несколько платёжных систем нужно иметь отдельную ( от платёжной системы ) кассу.

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

Заказать настройку

Если вы затрудняетесь в самостоятельном подключении то можете обратиться ко мне, ссылки на меня в подвале сайта. Так же вы можете обратиться в компанию Briney по телефону 8-4212-799-300 или зайти на их сайт https://briney.ru/

Поддержи Xakplant

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

xakplant.ru

Оплата через Яндекс.Касса. Старая версия API

Обратите внимание, этот способ подключения используется только для старых дизайнов на старой системе управления. Если вы сомневаетесь в выборе способа настройки Яндекс.Кассы — по старой или новой версии API, отправьте заявку в Личном кабинете в разделе Поддержка. Мы подскажем, какой способ актуален для вашего сайта.

ВАЖНО: Вы можете подключить данную систему для принятия платежей, только если вы являетесь индивидуальным предпринимателем или юридическим лицом. Если вы являетесь физическим лицом, то вы можете воспользоваться другими вариантами оплаты: варианты оплаты для физических лиц.

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

1. Оставьте заявку на подключение по ссылке money.yandex.ru/joinups, заполнив следующие поля:

• Тип организации – Выберите из выпадающего списка подходящую для вашей организации форму собственности, Юридическое лицо или Индивидуальный предприниматель
• Адрес сайта – Укажите URL-адрес вашего сайта, например, http://www.yandex.ru/ или http://www.amazon.com/
• Сайт должен функционировать и быть полностью в рабочем состоянии с опубликованной информацией о реализуемых вами товарах или услугах, информацией о вашей организации и контактными данными.
• Страна, где вы зарегистрированы – Выберите из выпадающего списка страну в которой зарегистрирована ваша организация
• Контактное лицо – Укажите ФИО контактного лица, с которым будут общаться сотрудники компании Яндекс
• ИНН — Укажите идентификационный номер плательщика
• Номер телефона – Укажите контактный телефон по которому с вами смогут связаться сотрудники компании Яндексв случае возникновения дополнительных вопросов

2. Перейдите на страницу Личного кабинета https://money.yandex.ru/my/questionnaire и заполните Анкету для подключения.

После заполнения разделов « Общие сведения » , « Контактная информация » , « Банковский счет » , « Данные руководителя » , « Загрузка скан-копий » нажмите кнопку Отправить анкету.

3. Перейдите на вкладку Способ подключения, выберите HTTP-протокол и заполните следующие поля:

• checkURL — https://secure.vigbo.com/yandex-kassa/checkorder.php
• avisoURL — https://secure.vigbo.com/yandex-kassa/paymentaviso.php
• Выберите «Использовать страницы успеха и ошибки с динамическими адресами» и «Я буду проводить тестовые платежи».
• checkURL (демо) — https://secure.vigbo.com/yandex-kassa/checkorder.php
• avisoURL (демо) — https://secure.vigbo.com/yandex-kassa/paymentaviso.php
• Email для отправки реестров — ваш контактный e-mail.
• ShopPassword — придумайте свой пароль.
• Если вам необходимо указывать successURL и failURL:
  successURL — http://sitename.com/shop/checkout/gateway/yandex_kassa/success
  failURL — http://sitename.com/shop/checkout/gateway/yandex_kassa/fail, где sitename.com/shop/ — доменное имя вашего сайта+адрес магазина

После заполнения формы нажмите кнопку Сохранить.

4. После того, как вы отправили все необходимые данные, вам должно поступить сообщение с данными по настройке. В этом сообщении должны быть номера shopID и scid

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

Выберите Вид оплаты: Через Яндекс.Касса.

Заполните поля следующими данными из присланного вам письма от Яндекс:

Идентификатор Контрагента = shop >Нажмите кнопку Сохранить.

6. Перейдите на страницу Магазин > Продажи > Методы оплаты.

Здесь вам нужно выбрать какие именно варианты оплаты будут отображаться на вашем сайте. Для этого вам нужно поставить отметку в колонке Отображение.

support.vigbo.com