Создание NPM-модуля Яндекс.Кассы под Node.js — опыт Lodoss Team


    Спустя несколько месяцев после релиза обновленного API Яндекс.Кассы начали появляться первые интеграционные решения на новых технологиях. Одним из пионеров интеграции стала компания Lodoss Team, разработавшая SDK-библиотеку для работы с Кассой под Node.js.


    Никто не расскажет о проекте лучше, чем его автор. Поэтому передаю слово Антону, техническому идеологу Lodoss Team, который и расскажет о том, почему выбор пал на Кассу и как теперь у них всё это работает.


    Меня зовут Антон, я технический директор Lodoss Team. Мы занимаемся веб-разработкой с 2008 года. Стек технологий — Javascript: Node.js, Angular, React. Основные клиенты — из Америки и Европы.

    На сегодняшний день моя команда выполнила более 400 коммерческих проектов. Среди них есть и связанные с платёжными системами.


    В этой статье хочу поделиться опытом интеграции платёжной системы в приложения для российского рынка и рассказать, почему мы выбрали Яндекс.Кассу, написали SDK-библиотеку для Node.js, как она упрощает внедрение платёжной системы и помогает в разработке.


    Особенности работы с российским e-commerce


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


    Выбирали по параметрам, которые подходили и нам, и клиенту:


    • работа с рублями и на российском рынке;
    • популярный сервис;
    • реализация нужной функциональности;
    • отсутствие абонентской платы;
    • небольшая комиссия с платежей — от 2,8% до 6%;
    • скорость интеграции — ±3 дня;
    • возможность подключения Apple Pay;
    • возможность работы по 54-ФЗ.

    С последним пунктом кто-то может быть не знаком. 54-ФЗ — федеральный закон о применении кассовой техники. В 2017 году он пережил реформу: отныне все кассы на территории России должны подключаться к интернету и отправлять электронные чеки в налоговую. Онлайн-кассы должны установить все, у кого есть интернет-магазин, кто владеет бизнесом и продаёт товары или оказывает платные услуги.


    Яндекс.Касса занимается эквайрингом и предлагает удобное решение для работы по 54-ФЗ онлайн-сервисам и интернет-магазинам. Клиент подключает онлайн-кассу, а сервис помогает наладить с ней работу: отправляет данные чека, проверяет отправку в налоговую, проводит транзакцию. Если не использовать Яндекс.Кассу, а, например, заключить договор по эквайрингу с банком, все операции с электронными чеками магазину придётся выполнять самостоятельно.


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


    …и за неделю до релиза выходит новый API Яндекс.Кассы


    В документации к обновлённой версии мы увидели, что информация стала «ближе» к разработчику. Ребята из Яндекс.Кассы объединили платёжные протоколы общей логикой и описанием, сделали удобнее интерфейс для разработчиков. Теперь процесс интеграции платёжных систем почти не отличался от известных зарубежных аналогов, с которыми я сталкивался в работе, — таких, как Stripe и Braintree.


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


    В новом API Яндекс.Кассы разработчики оптимизировали такие специфические вещи, как асинхронность и идемпотентность. Ещё стало удобнее работать с данными. Об этом рассказала команда Яндекс.Кассы.


    Команде понравился новый подход Яндекс.Кассы: они действительно заботятся о разработчиках. Но для новой версии API Яндекс.Касса не предоставляла из коробки библиотеку для работы с Node.js — а именно на нём мы писали проект. И вот что скажу: таких библиотек на рынке нет вообще. Но наши ребята подумали и собрали свою OpenSource-библиотеку для работы с API Яндекс.Кассы.


    В итоге библиотека упрощает и оптимизирует разработку, интегрировать её можно для кастомных и e-commerce решений. NPM-модуль помогает в создании модулей оплаты e-commerce и внедрении в приложение возможности платежей за товары и услуги. Например, можно использовать SDK, если надо добавить на сайт оплату бронирования или покупки билета.


    Подключение NPM-модуля


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


    Первым делом нужно установить саму библиотеку через пакетный менеджер NPM: в ближайшее время выложим ещё и на Yarn.


    npm install yandex-checkout

    Импортируем библиотеку, указав shopId и secretKey:


    const yandexCheckout = require('yandex-checkout')('shopId', 'secretKey');

    Для аутентификации запросов используется обычная Basic auth:


    • shopId — идентификатор магазина в Яндекс.Кассе.
    • secretKey — ваш секретный ключ.

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


    При подключении библиотеки можно передавать не только текстовые параметры, но и конфигурационный объект:


    const yandexCheckout = require('yandex-checkout')({
      shopId: 'Ваш индентификатор магазина',
      secretKey: 'Ваш cекретный ключ',
      timeout: 20000, //значение по умолчанию 120000
      debug: false, //значение по умолчанию FALSE
      host: '', //значение по умолчанию https://payment.yandex.net
      path: '', //значение по умолчанию ‘/api/v3/’
    });

    На этом процесс интеграции закончился. Теперь вы можете использовать библиотеку.


    Пример работы — создание платежа


    Для создания платежа нужно указать ключ идемпотентности. В документации к API Яндекс рекомендует использовать UUID V4. Если в функции не передавать ключ идемпотентности, библиотека будет генерировать каждый раз новый ключ с использованием рекомендованного алгоритма.


    Для удобства использования мы обернули все методы в Promise, поэтому результатом функций будет обещание, и мы можем использовать then, catch:


    const yandexCheckout = require('yandex-checkout')('shopId', 'secretKey');
    const idempotenceKey = '02347fc4-a1f0-49db-807e-f0d67c2ed5a5';
    yandexCheckout.createPayment({
      'amount':{
        'value': '2.00',
        'currency': 'RUB',
      },
      'payment_method_data':{
        'type': 'bank_card',
      },
      'confirmation':{
        'type': 'redirect',
        'return_url': 'https://www.merchant-website.com/return_url',
      }
    }, idempotenceKey)
        .then((result) => {
         console.log({payment: result});
        })
        .catch( err => console.log(err));

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


    Чтобы получить информацию о платеже, нужно воспользоваться функцией getPaymentInfo и передать ей параметры идентификатора платежа:


    const yandexCheckout = require('yandex-checkout')('shopId', 'secretKey');
    const paymentId = '21966b95-000f-50bf-b000-0d78983bb5bc';
    yandexCheckout.getPaymentInfo(paymentId)
        .then((result) => {
         console.log({payment: result});
        })
        .catch( err => console.log(err));
    });

    Библиотека поддерживает все доступные методы, описанные в документации.


    Что в итоге


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


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


    Я описал основные моменты, с которыми моя команда столкнулась при интеграции платёжной системы и создании NPM-модуля. Возможно, что-то упустил — спрашивайте в комментариях.

    ЮMoney (Яндекс.Деньги)
    Всё о разработке сервисов онлайн-платежей

    Comments 5

      0
      А в новом api кассы имеется реализация рекурентных платежей?
        0
        Да, рекуррентные платежи есть. Нужно по инструкции создать платеж, взять из ответного объекта payment_method поле id — и использовать его в рекуррентном платеже. Просто вместо payment_method_data используйте payment_method_id"
          –1

          Благодарю, жаль плюс в карму дать не могу.

        0
        кинули бы что ли пример оплаты токеном, а так гадай как его там прикрутить
          0
          собственно — не поддерживает оно платежи токеном, а жаль… придется делать свой велосипед

        Only users with full accounts can post comments. Log in, please.