dimskiy Feb 1 2018 at 12:49

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

5 min

11K

ЮMoney corporate blogPayment systems*Programming*API*Development for e-commerce*

Спустя несколько месяцев после релиза обновленного 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-модуля. Возможно, что-то упустил — спрашивайте в комментариях.

Tags:

Hubs: