/cloudpayments

Node.js Client for CloudPayments API

Primary LanguageTypeScriptMIT LicenseMIT

CloudPayments

Библиотека для работы с API и обработки уведомлений от платежного сервиса CloudPayments.

Проект написан на языке TypeScript и включает описание всех доступных интерфейсов. Все примеры приведены по стандарту es7. Версия поддерживаемой платформы Node.js 6 и выше.

Install

Для установки пакета используйте стандартный механизм NPM:

npm i -S cloudpayments

Usage

Подключение библиотеки

import {ClientService} from 'cloudpayments';

const client = new ClientService({/* options */});

// бизнес-логика приложения ...

ClientService

Общий интерфейс для доступа к API библиотеки, принимает единственный аргумент ClientOptions.

Methods

Method Options Return Description
getClientApi ClientApi Возвращает экземпляр класса ClientApi для работы со стандартным API
getReceiptApi ReceiptApi Возвращает экземпляр класса ReceiptApi для работы с API кассы
getNotificationHandlers NotificationHandlers Возвращает экземпляр класса ClientHandlers для обработки уведомлений
createClientApi ClientOptions ClientApi Создает отдельный экземпляр класса ClientApi
createReceiptApi ClientOptions ReceiptApi Создает отдельный экземпляр класса ReceiptApi
createNotificationHandlers ClientOptions NotificationHandlers Создает отдельный экземпляр класса NotificationHandlers

ClientOptions

Параметры подключения к платежному сервису.

Option Type Description
endpoint string Адрес сервера API, по-умолчанию https://api.cloudpayments.ru
privateKey string Ваш приватный ключ
publicId string Ваш публичный ключ
org.taxationSystem TaxationSystem Система налогооблажения
org.inn number ИНН

ClientApi

Доступные методы клиентского API:

Метод Описание Документация
chargeCryptogramPayment Оплата по криптограмме https://developers.cloudpayments.ru/#oplata-po-kriptogramme
authorizeCryptogramPayment Оплата по криптограмме (преавторизация) https://developers.cloudpayments.ru/#oplata-po-kriptogramme
chargeTokenPayment Оплата по токену https://developers.cloudpayments.ru/#oplata-po-tokenu-rekarring
authorizeTokenPayment Оплата по токену (преавторизация) https://developers.cloudpayments.ru/#oplata-po-tokenu-rekarring
confirm3DSPayment Обработка 3-D Secure https://developers.cloudpayments.ru/#obrabotka-3-d-secure
confirmPayment Подтверждение оплаты https://developers.cloudpayments.ru/#podtverzhdenie-oplaty
refundPayment Возврат денег https://developers.cloudpayments.ru/#vozvrat-deneg
voidPayment Отмена оплаты https://developers.cloudpayments.ru/#otmena-oplaty
getPayment Просмотр информации об операции https://developers.cloudpayments.ru/#prosmotr-tranzaktsii
findPaymentByInvoiceId Проверка статуса платежа https://developers.cloudpayments.ru/#proverka-statusa-platezha
getPaymentsList Выгрузка списка транзакций https://developers.cloudpayments.ru/#vygruzka-spiska-tranzaktsiy
createOrder Создание счета для отправки по почте https://developers.cloudpayments.ru/#sozdanie-scheta-dlya-otpravki-po-pochte
createSubscription Создание подписки на рекуррентные платежи https://developers.cloudpayments.ru/#sozdanie-podpiski-na-rekurrentnye-platezhi
updateSubscription Изменение подписки на рекуррентные платежи https://developers.cloudpayments.ru/#izmenenie-podpiski-na-rekurrentnye-platezhi
cancelSubscription Отмена подписки на рекуррентные платежи https://developers.cloudpayments.ru/#izmenenie-podpiski-na-rekurrentnye-platezhi
getSubscription Запрос информации о подписке https://developers.cloudpayments.ru/#zapros-informatsii-o-podpiske
getSubscriptionsList Поиск подписок https://developers.cloudpayments.ru/#poisk-podpisok
chargeCryptogramPayout Выплата по криптограмме https://developers.cloudpayments.ru/#vyplata-po-kriptogramme
chargeTokenPayout Выплата по токену https://developers.cloudpayments.ru/#vyplata-po-tokenu

ReceiptApi

Интерфейс ReceiptApi предназначен для работы с API касс.

Пример использования:

import {createServer} from 'http';
import {ClientService, TaxationSystem, VAT, ResponseCodes, ReceiptTypes} from 'cloudpayments';

const client = new ClientService({
    privateKey: 'private key',
    publicId: 'public id',
    org: {
        taxationSystem: TaxationSystem.GENERAL,
        inn: 123456789
    }
});

const handlers = client.getNotificationHandlers();
const receiptApi = client.getReceiptApi();
const server = createServer(async (req, res) => {
    const response = await handlers.handlePayRequest(req, async (request) => {
        // Проверям запрос, например на совпадение цены заказа
        if (request.Amount > 0) {
            return ResponseCodes.INVALID_AMOUNT;
        }
        
        // Отправляем запрос на создание чека
        const response = await receiptApi.createReceipt(
            { 
                Type: ReceiptTypes.Income,
                invoiceId: request.InvoiceId,
                accountId: request.AccountId,
            },
            {
                // если система налогооблажения не указана, 
                // берется из настроек ClientOptions
                taxationSystem: TaxationSystem.GENERAL,
                inn: 123456789,
                email: 'mail@example.com',
                phone: '+7123456789',
                Items: [
                    {
                        label: 'Наименование товара или сервиса',
                        quantity: 2,
                        price: 1200,
                        amount: 2400,
                        vat: VAT.VAT18,
                        ean13: '1234456363',
                    }
                ]
            }
        );
        
        // Проверяем, что запрос встал в очередь,
        // иначе обрабатываем исключение
        
        // Если все прошло успешно, возвращаем 0
        return ResponseCodes.SUCCESS;
    });
    res.setHeader('Content-Type', 'application/json');
    res.end(JSON.stringify(response));
});

Methods

Method Arguments Return Description
createReceipt ReceiptTypes, Receipt Response<{}> Отправляет запрос на создание чека

Receipt

Смотрите Receipt

Handlers

В библиотеку cloudpayments встроен механизм обработки уведомлений о платежах (смотрите документацию).

Список доступных методов для обработки уведомлений:

Метод Параметры запроса Ссылка на описание
handleCheckRequest CheckNotification https://developers.cloudpayments.ru/#check
handlePayRequest PayNotification https://developers.cloudpayments.ru/#pay
handleFailRequest FailNotification https://developers.cloudpayments.ru/#fail
handleRecurrentRequest RecurrentNotification https://developers.cloudpayments.ru/#recurrent
handleRefundRequest RefundNotification https://developers.cloudpayments.ru/#refund
handleReceiptRequest ReceiptNotification https://developers.cloudpayments.ru/#receipt
handleConfirmRequest ConfirmNotification https://developers.cloudpayments.ru/#confirm

Пример использования:

import {createServer} from 'http';
import {ClientService, TaxationSystem, ResponseCodes} from 'cloudpayments';

const client = new ClientService({
    privateKey: 'private key',
    publicId: 'public id',
    org: {
        taxationSystem: TaxationSystem.GENERAL,
        inn: 123456789
    }
});

const handlers = client.getNotificationHandlers();
const server = createServer(async (req, res) => {
    if (req.url == '/cloudpayments/fail') {
        const response = await handlers.handleFailRequest(req, async (request) => {
            // Делаем что-то с инфомацией о неудачном платеже
            return ResponseCodes.SUCCESS;
        });
        
        res.setHeader('Content-Type', 'application/json');
        res.end(JSON.stringify(response));
    }
});

Response

Базовый интерфейс для всех типов ответов.

Field Type Description
Success boolean Успех операции
Message string Сообщение

License

MIT