Хабрахабр

Создание 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, как она упрощает внедрение платёжной системы и помогает в разработке.

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

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

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

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

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

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

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

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

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

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

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

При разработке 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 host: '', //значение по умолчанию ‘/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-модуля. Возможно, что-то упустил — спрашивайте в комментариях.

Теги
Показать больше

Похожие статьи

Кнопка «Наверх»
Закрыть