mediazona/cloudpayments

Node.js Client for CloudPayments API

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