FreeKassa SDK

Описание

FreeKassa SDK - это библиотека для работы с платежной системой FreeKassa, которая позволяет интегрировать платежи в ваше приложение. SDK поддерживает как фронтенд, так и бэкенд части приложения. Если для вас не хватает каких то методов, которые есть в документации отпишите мне, я постараюсь их добавить!

Обёртка для NestJS

Документация freekassa

Установка

npm install @exact-team/freekassa-sdk

Структура проекта

src/
├── api/          # API-клиенты и методы
├── commands/     # Команды для работы с платежами
├── interfaces/   # Интерфейсы и типы
├── index.ts      # Точка входа
└── freekassa.sdk.ts # Основной класс SDK

Основные возможности

• Создание платежей и выплат
• Получение списка заказов и выплат
• Проверка статуса платежей
• Работа с уведомлениями
• Управление балансом
• Получение информации о валютах
• Валидация данных
• Поддержка TypeScript

Конфигурация

Обязательные параметры

• key - API ключ для подписи запросов
• secretWord1 - Первое секретное слово для подписи платежных форм
• secretWord2 - Второе секретное слово для проверки уведомлений
• shopId - ID вашего магазина
• lang - Язык интерфейса (ru или en)
• currency - Валюта платежей (RUB, USD, EUR, UAH, KZT)
• payUrl - URL платежной формы (по умолчанию: https://pay.fk.money/)
• apiUrl - URL API (по умолчанию: https://api.fk.life/v1/)

Использование

Инициализация

import { Freekassa } from '@exact-team/freekassa-sdk';

const sdk = new Freekassa({
  key: 'YOUR_API_KEY',
  secretWord1: 'YOUR_SECRET_WORD_1',
  secretWord2: 'YOUR_SECRET_WORD_2',
  shopId: 12345,
  lang: 'ru',
  currency: 'RUB',
  payUrl: 'https://pay.fk.money/',
  apiUrl: 'https://api.fk.life/v1/',
});

Платежи

Создание ссылки для оплаты

const paymentLink = sdk.createPaymentLink({
  amount: 1000,
  paymentId: 'unique-payment-id',
  methodId: 1, // опционально
  email: '[email protected]', // опционально
  phone: '+79001234567', // опционально
  successUrl: 'https://your-site.com/success', // опционально
  failUrl: 'https://your-site.com/fail', // опционально
  notifyUrl: 'https://your-site.com/notify', // опционально
});

Создание заказа

const order = await sdk.createOrder({
  methodId: 1,
  email: '[email protected]',
  ip: '127.0.0.1',
  amount: 1000,
  paymentId: 'unique-payment-id',
  phone: '+79001234567', // опционально
  successUrl: 'https://your-site.com/success', // опционально
  failUrl: 'https://your-site.com/fail', // опционально
  notifyUrl: 'https://your-site.com/notify', // опционально
});

Проверка уведомления

const notification = {
  MERCHANT_ID: 'yourID',
  AMOUNT: '10',
  MERCHANT_ORDER_ID: '1746001556454',
  SIGN: 'a242444ec9b2cf63e5fa1ea1ef1bb999',
};

const isValid = sdk.verifyNotification(notification);
console.log(isValid); // true или false

Получение списка заказов

const orders = await sdk.listOrders({
  paymentId: 'payment-id', // опционально
  orderId: 'order-id', // опционально
  status: 1, // опционально
  dateFrom: '2024-01-01', // опционально
  dateTo: '2024-12-31', // опционально
  page: 1, // опционально
});

Выплаты

Создание выплаты

const withdrawal = await sdk.createWithdrawal({
  methodId: 1,
  account: 'account-number',
  amount: 1000,
  paymentId: 'unique-payment-id', // опционально
});

Получение списка выплат

const withdrawals = await sdk.listWithdrawals({
  orderId: 'order-id', // опционально
  paymentId: 'payment-id', // опционально
  status: 1, // опционально
  dateFrom: '2024-01-01', // опционально
  dateTo: '2024-12-31', // опционально
  page: 1, // опционально
});

Информация

Получение баланса

const balance = await sdk.getBalance();

Получение списка валют

const currencies = await sdk.getCurrencies();

Получение статуса валюты

const currencyStatus = await sdk.getCurrencyStatus(1);

Получение валют для выплат

const withdrawalCurrencies = await sdk.getWithdrawalCurrencies();

Получение списка магазинов

const shops = await sdk.getShops();

Требования

• Node.js 20+
• TypeScript 5.0+

Разработка

Сборка

# Сборка проекта
npm run build

# Запуск линтера
npm run lint

Линтинг

Проект использует ESLint и Prettier для поддержания качества кода.

Структура проекта

src/
├── api/          # API-клиенты и методы
├── commands/     # Команды для работы с платежами
├── interfaces/   # Интерфейсы и типы
├── index.ts      # Точка входа
└── freekassa.sdk.ts # Основной класс SDK

Поддерживаемые версии Node.js

SDK поддерживает следующие версии Node.js:

• Node.js 20.x
• Node.js 21.x
• Node.js 22.x

Безопасность

SDK использует следующие механизмы безопасности:

• HMAC-SHA256 для подписи API-запросов
• MD5 для подписи платежных форм
• Валидация всех входящих данных через Zod
• Типизация TypeScript для предотвращения ошибок

Обработка ошибок

Все методы SDK могут выбросить следующие типы ошибок:

• Error - общие ошибки API
• ZodError - ошибки валидации входных данных
• TypeError - ошибки типизации

Пример обработки ошибок:

try {
  const order = await sdk.createOrder({
    methodId: 1,
    email: '[email protected]',
    ip: '127.0.0.1',
    amount: 1000,
    paymentId: 'unique-payment-id',
  });
} catch (error) {
  if (error instanceof Error) {
    console.error('API Error:', error.message);
  } else if (error instanceof ZodError) {
    console.error('Validation Error:', error.errors);
  }
}

Тестирование

Для тестирования SDK рекомендуется:

1. Использовать тестовые API-ключи
2. Проверять все сценарии обработки ошибок
3. Верифицировать подписи платежных форм
4. Тестировать обработку уведомлений

Вклад в проект

Приветствуются:

• Исправление ошибок
• Улучшение документации
• Добавление новых методов
• Улучшение тестового покрытия

Лицензия

ISC

Автор

exact01

Поддержка

Для получения поддержки или сообщения об ошибках, пожалуйста, создайте issue в репозитории проекта.