nestjs-monobank 1.2.8

package/src/modules/invoice/interfaces/responses/charge.response.ts

@@ -0,0 +1,43 @@
+import type { ChargeStatusEnum } from "../../enums";
+
+export interface ChargeResponse {
+    /**
+     * Ідентифікатор інвойсу, за яким здійснювалась оплата
+     */
+    invoiceId: string;
+  
+    /**
+     * Посилання на проходження 3DS підтвердження платежу (якщо потрібне)
+     */
+    tdsUrl?: string;
+    
+    /**
+     * Статус оплати
+     */
+    status: ChargeStatusEnum;
+  
+    /**
+     * Причина відмови в оплаті
+     */
+    failureReason?: string;
+  
+    /**
+     * Сума у мінімальних одиницях валюти (наприклад, копійки)
+     */
+    amount: number;
+  
+    /**
+     * ISO 4217 код валюти
+     */
+    ccy: number;
+  
+    /**
+     * Дата і час створення заяви на оплату
+     */
+    createdDate: string;
+  
+    /**
+     * Дата і час останньої модифікації операції оплати
+     */
+    modifiedDate: string;
+}

package/src/modules/invoice/interfaces/responses/create-cancel.response.ts

@@ -0,0 +1,7 @@
+import type { Cancel } from "./cancel.response";
+
+/**
+ * Відповідь API при створенні запиту на скасування інвойсу.
+ * Наслідує базову структуру Cancel.
+ */
+export interface CreateCancelResponse extends Cancel {}

package/src/modules/invoice/interfaces/responses/create-charge.response.ts

@@ -0,0 +1,7 @@
+import type { ChargeResponse } from "./charge.response";
+
+/**
+ * Відповідь API при створенні заяви на оплату.
+ * Наслідує базову структуру Charge.
+ */
+export interface CreateChargeResponse extends ChargeResponse {}

package/src/modules/invoice/interfaces/responses/create-finalize.response.ts

@@ -0,0 +1,7 @@
+import type { FinalizeResponse } from "./finalize.response";
+
+/**
+ * Відповідь API при підтвердженні холду.
+ * Наслідує базову структуру CaptureHold.
+ */
+export interface CreateFinalizeResponse extends FinalizeResponse {}

package/src/modules/invoice/interfaces/responses/create-invoice.response.ts

@@ -0,0 +1,7 @@
+import type { Invoice } from "./invoice.response";
+
+/**
+ * Відповідь API при створенні рахунку (invoice).
+ * Наслідує базову структуру Invoice.
+ */
+export interface CreateInvoiceResponse extends Invoice {}

package/src/modules/invoice/interfaces/responses/finalize.response.ts

@@ -0,0 +1,9 @@
+/**
+ * Результат підтвердження холду.
+ */
+export interface FinalizeResponse {
+    /**
+     * Статус операції: наприклад, "success", "failure" або null, якщо статус невідомий.
+     */
+    status: string | null;
+}

package/src/modules/invoice/interfaces/responses/fiscal-checks.response.ts

@@ -0,0 +1,49 @@
+/**
+ * Інформація про чек.
+ */
+export interface FiscalCheckItem {
+    /**
+     * Унікальний ідентифікатор чеку.
+     */
+    id: string;
+
+    /**
+     * Тип транзакції (наприклад, sale — продаж).
+     */
+    type: string;
+
+    /**
+     * Поточний статус чеку.
+     */
+    status: string;
+
+    /**
+     * Опис статусу чеку, якщо є.
+     */
+    statusDescription: string;
+
+    /**
+     * URL для перегляду або перевірки чеку.
+     */
+    taxUrl: string;
+
+    /**
+     * Посилання на файл, пов'язаний з чеком.
+     */
+    file: string;
+
+    /**
+     * Джерело фіскалізації (наприклад, monopay).
+     */
+    fiscalizationSource: string;
+}
+
+/**
+ * Список чеків.
+ */
+export interface FiscalChecksResponse {
+    /**
+     * Масив об'єктів типу `CheckItem`.
+     */
+    checks: FiscalCheckItem[];
+}

package/src/modules/invoice/interfaces/responses/index.ts

@@ -0,0 +1,10 @@
+export * from './create-invoice.response'
+export * from './create-finalize.response'
+export * from './create-cancel.response'
+
+export * from './cancel.response'
+export * from './finalize.response'
+export * from './invoice-status.response'
+export * from './invoice.response'
+export * from './fiscal-checks.response'
+export * from './receipt.response'

package/src/modules/invoice/interfaces/responses/invoice-status.response.ts

@@ -0,0 +1,142 @@
+import type { InvoiceCancelItem, TipsInfo, WalletData } from "../../../../common/interfaces";
+import type { InvoiceStatusEnum } from "../../enums";
+
+/**
+ * Інформація про здійснений платіж за рахунком.
+ */
+export interface InvoiceStatusPaymentInfo {
+    /**
+     * Маскований номер картки, з якої здійснено платіж.
+     */
+    maskedPan: string;
+
+    /**
+     * Код авторизації транзакції.
+     */
+    approvalCode: string;
+
+    /**
+     * RRN (Retrieval Reference Number) — унікальний ідентифікатор транзакції.
+     */
+    rrn: string;
+
+    /**
+     * Унікальний ідентифікатор транзакції в системі банку.
+     */
+    tranId: string;
+
+    /**
+     * Ідентифікатор терміналу, через який проведено оплату.
+     */
+    terminal: string;
+
+    /**
+     * Назва банку, що обробив платіж.
+     */
+    bank: string;
+
+    /**
+     * Платіжна система (наприклад, Visa, Mastercard).
+     */
+    paymentSystem: string;
+
+    /**
+     * Метод оплати (наприклад, картка, Google Pay, Apple Pay).
+     */
+    paymentMethod: string;
+
+    /**
+     * Комісія, стягнена банком, у мінімальних одиницях валюти.
+     */
+    fee: number;
+
+    /**
+     * Код країни у форматі ISO 3166-1 numeric (наприклад, 804 — Україна).
+     */
+    country: 804;
+
+    /**
+     * Комісія агента, якщо застосовується (у мінімальних одиницях).
+     */
+    agentFee: number;
+}
+
+/**
+ * Інформація про статус рахунку.
+ */
+export interface InvoiceStatus {
+    /**
+     * Ідентифікатор інвойсу.
+     */
+    invoiceId: string;
+
+    /**
+     * Поточний статус інвойсу.
+     */
+    status: InvoiceStatusEnum;
+
+    /**
+     * Причина відмови, якщо оплата неуспішна.
+     */
+    failureReason?: string;
+
+    /**
+     * Код помилки, яка виникла під час обробки платежу.
+     */
+    errCode?: string;
+
+    /**
+     * Сума у мінімальних одиницях валюти.
+     */
+    amount: number;
+
+    /**
+     * Валюта операції.
+     */
+    ccy: number;
+
+    /**
+     * Підсумкова сума після оплати та повернень.
+     */
+    finalAmount: number;
+
+    /**
+     * Дата і час фінансової операції.
+     */
+    createdDate: string;
+
+    /**
+     * Дата і час останньої модифікації операції.
+     */
+    modifiedDate: string;
+
+    /**
+     * Референс платежу, який визначається продавцем.
+     */
+    reference: string;
+
+    /**
+     * Призначення платежу, визначається продавцем.
+     */
+    destination: string;
+
+    /**
+     * Список прийнятих заявок на скасування.
+     */
+    cancelList: InvoiceCancelItem[];
+
+    /**
+     * Інформація про платіж, що включає деталі транзакції.
+     */
+    paymentInfo: InvoiceStatusPaymentInfo;
+
+    /**
+     * Дані про гаманця користувача, що зберігає токенізовану картку.
+     */
+    walletData: WalletData;
+
+    /**
+     * Інформація про чайові, якщо вони були сплачені.
+     */
+    tipsInfo: TipsInfo;
+}

package/src/modules/invoice/interfaces/responses/invoice.response.ts

@@ -0,0 +1,14 @@
+/**
+ * Відповідь після створення інвойсу.
+ */
+export interface Invoice {
+    /**
+     * Ідентифікатор інвойсу.
+     */
+    invoiceId: string;
+
+    /**
+     * Посилання на сторінку оплати.
+     */
+    pageUrl: string;
+}

package/src/modules/invoice/interfaces/responses/receipt.response.ts

@@ -0,0 +1,6 @@
+export interface ReceiptResponse {
+    /**
+     * Base64-закодований PDF-файл квитанції
+     */
+    file: string;
+  }

package/src/modules/invoice/invoice.module.ts

@@ -0,0 +1,8 @@
+import { Module } from "@nestjs/common";
+import { InvoiceService } from "./invoice.service";
+
+@Module({
+     providers: [InvoiceService],
+     exports: [InvoiceService]
+})
+export class InvoiceModule {}

package/src/modules/invoice/invoice.service.ts

@@ -0,0 +1,191 @@
+import { Injectable } from "@nestjs/common";
+import type { 
+	CreateChargeRequest,
+	CreateCancelRequest,
+	CreateFinalizeRequest, 
+	CreateFinalizeResponse, 
+	CreateInvoiceRequest, 
+	CreateInvoiceResponse, 
+	CreateCancelResponse,
+	FiscalChecksResponse,
+	InvoiceStatus, 
+	ReceiptResponse
+} from './interfaces'
+import { MonobankHttpClient } from "../../core/http/monobank.http-client";
+import { CreateChargeResponse } from "./interfaces/responses/create-charge.response";
+
+@Injectable()
+export class InvoiceService {
+	public constructor(private readonly http: MonobankHttpClient) {}
+
+	/**
+	 * Створює рахунок для оплати через Monobank.
+	 * @param {CreateInvoiceRequest} data - Дані для створення рахунку.
+	 * @returns {Promise<CreateInvoiceResponse>} Відповідь від API з деталями рахунку.
+	 *
+	 * @example
+	 * const invoiceData: CreateInvoiceRequest = {
+	 *   amount: 1000,
+	 *   ccy: 980, // UAH
+	 *   merchantPaymInfo: {
+	 *     reference: "my_shop_order_28142",
+	 *     destination: "Оплата за замовлення #28142",
+	 *     basketOrder: [
+	 *       {
+	 *         name: "Товар1",
+	 *         qty: 2,
+	 *         sum: 500,
+	 *         icon: "https://example.com/images/product1.jpg",
+	 *         unit: "уп."
+	 *       }
+	 *     ]
+	 *   },
+	 *   redirectUrl: "https://example.com/order-result",
+	 *   webHookUrl: "https://example.com/mono-webhook",
+	 *   validity: 3600 * 24 * 7,
+	 *   paymentType: "debit"
+	 * };
+	 *
+	 * const invoice = await this.monobankService.invoice.create(data);
+	 * console.log(invoice.pageUrl);
+	 */
+	public async create(data: CreateInvoiceRequest): Promise<CreateInvoiceResponse> {
+		return this.http.post('/merchant/invoice/create', data)
+	}
+
+	/**
+	 * Проводить прямий платеж через Monobank.
+	 * @param {CreateChargeRequest} data - Дані для проведення прямого платежу.
+	 * @returns {Promise<CreateChargeResponse>} Відповідь від API з деталями платежу.
+	 * @example
+	 * const data: CreateChargeRequest = {
+	 *   amount: 1000,
+	 *   ccy: 980,
+	 *   cardData: {
+	 *     pan: "1234567890123456",
+	 *     exp: "1226",
+	 *     cvv: 123
+	 *   },
+	 *   merchantPaymInfo: {
+	 *     reference: "my_shop_order_28142",
+	 *     destination: "Оплата за замовлення #28142",
+	 *     basketOrder: [
+	 *       {
+	 *         name: "Товар1",
+	 *         qty: 2,
+	 *         sum: 500,
+	 *         icon: "https://example.com/images/product1.jpg",
+	 *         unit: "уп."
+	 *       }
+	 *     ]
+	 *   },
+	 *   webhookUrl: "https://example.com/mono-webhook",
+	 *   redirectUrl: "https://example.com/order-result",
+	 *   paymentType: "debit",
+	 *   initiationKind: "merchant"
+	 * };
+	 * const charge = await this.monobankService.invoice.charge(data);
+	 * console.log(charge.invoiceId);
+	 */
+	public async charge(data: CreateChargeRequest): Promise<CreateChargeResponse> {
+		return this.http.post('/merchant/invoice/payment-direct', data)
+	}
+
+	/**
+	 * Отримує статус рахунку за його ID.
+	 * @param {string} invoiceId - Унікальний ідентифікатор рахунку.
+	 * @returns {Promise<InvoiceStatus>} Поточний статус рахунку.
+	 * @example
+	 * const invoiceId = "khsf8723hsdf8923hf";
+	 * const status = await this.monobankService.invoice.getStatus(invoiceId);
+	 * console.log(status);
+	 */
+	public async getStatus(invoiceId: string): Promise<InvoiceStatus> {
+		return this.http.get(`/merchant/invoice/status?invoiceId=${invoiceId}`)
+	}
+
+	/**
+	 * Отримує фіскальні чеки по рахунку.
+	 * @param {string} invoiceId - Унікальний ідентифікатор рахунку.
+	 * @returns {Promise<FiscalChecksResponse>} Список фіскальних чеків.
+	 * @example
+	 * const checks = await this.monobankService.invoice.getFiscalReceipts(invoiceId);
+	 * console.log(checks);
+	 */
+	public async getFiscalReceipts(invoiceId: string): Promise<FiscalChecksResponse> {
+		return this.http.get(`/merchant/invoice/fiscal-checks?invoiceId=${invoiceId}`)
+	}
+
+	/**
+	 * Отримує квитанцію по рахунку.
+	 * @param {string} invoiceId - Унікальний ідентифікатор рахунку.
+	 * @returns {Promise<ReceiptResponse>} Квитанція по рахунку.
+	 * @example
+	 * const receipt = await this.monobankService.invoice.getReceipt(invoiceId);
+	 * console.log(receipt);
+	 */
+	public async getReceipt(invoiceId: string): Promise<ReceiptResponse> {
+		return this.http.get(`/merchant/invoice/receipt?invoiceId=${invoiceId}`)
+	}
+
+    /**
+     * Завершує утримання коштів за рахунком.
+     * @param {CreateFinalizeRequest} data - Дані для завершення утримання коштів.
+     * @returns {Promise<CreateFinalizeResponse>} Статус завершення утримання.
+     * @example
+     * const data: CreateFinalizeRequest = {
+     *    invoiceId: "2210012MPLYwJjVUzchj",
+     *    amount: 4200
+     * };
+     * const finalize = await this.monobankService.invoice.finalize(data);
+     * console.log(finalize.status);
+     */
+    public async finalize(data: CreateFinalizeRequest): Promise<CreateFinalizeResponse> {
+        return this.http.post('/merchant/invoice/finalize', data)
+    }
+
+	/**
+	 * Скасовує (повертає) платіж за рахунком Monobank.
+	 *
+	 * Метод створює заявку на скасування оплати (cancel).
+	 * Статус скасування може бути:
+	 * - `processing` — заявка в обробці
+	 * - `success` — скасування виконано успішно
+	 * - `failure` — помилка під час скасування
+	 *
+	 * @param {CreateCancelRequest} data - Дані для створення запиту на скасування.
+	 * @returns {Promise<CreateCancelResponse>} Результат операції скасування.
+	 *
+	 * @example
+	 * const data: CreateCancelRequest = {
+	 *   invoiceId: "2210012MPLYwJjVUzchj",
+	 *   amount: 1500
+	 * };
+	 *
+	 * const cancel = await this.monobankService.invoice.cancel(data);
+	 * console.log(cancel.status);
+	*/
+	public async cancel(data: CreateCancelRequest): Promise<CreateCancelResponse> {
+		return this.http.post("/merchant/invoice/cancel", data)
+	}
+
+	/**
+	 * Видаляє (анулює) інвойсу Monobank за його ідентифікатором.
+	 *
+	 * Метод використовується для:
+	 * - повного видалення інвойсу
+	 * - припинення можливості оплати за інвойсом
+	 *
+	 * ⚠️ Зазвичай застосовується лише для інвойсів,
+	 * які ще не були успішно оплачені.
+	 *
+	 * @param {string} invoiceId - Унікальний ідентифікатор інвойсу.
+	 * @returns {Promise<void>} Результат операції (без тіла відповіді).
+	 *
+	 * @example
+	 * await this.monobankService.invoice.remove("2210012MPLYwJjVUzchj");	
+	*/
+	public async remove(invoiceId: string): Promise<void> {
+		return this.http.post("/merchant/invoice/remove", invoiceId)
+	}
+}

package/src/modules/merchant/interfaces/index.ts

@@ -0,0 +1 @@
+export * from './responses'

package/src/modules/merchant/interfaces/responses/index.ts

@@ -0,0 +1,2 @@
+export * from './merchant.response'
+export * from './pubkey.response'

package/src/modules/merchant/interfaces/responses/merchant.response.ts

@@ -0,0 +1,19 @@
+/**
+ * Інформація про мерчанта, зареєстрованого в Monobank.
+ */
+export interface MerchantResponse {
+    /**
+     * Унікальний ідентифікатор мерчанта.
+     */
+    merchantId: string;
+
+    /**
+     * Назва компанії або організації.
+     */
+    merchantName: string;
+
+    /**
+     * ЄДРПОУ (ідентифікаційний код юридичної особи в Україні).
+     */
+    edrpou: string;
+}

package/src/modules/merchant/interfaces/responses/pubkey.response.ts

@@ -0,0 +1,10 @@
+/**
+ * Відповідь API з відкритим RSA-ключем мерчанта.
+ */
+export interface PubkeyResponse {
+	/**
+	 * Відкритий RSA-ключ у PEM-форматі.
+	 * Використовується для верифікації підписів Monobank.
+	 */
+	key: string;
+}

package/src/modules/merchant/merchant.module.ts

@@ -0,0 +1,8 @@
+import { Module } from "@nestjs/common";
+import { MerchantService } from "./merchant.service";
+
+@Module({
+  providers: [MerchantService],
+  exports: [MerchantService]
+})
+export class MerchantModule {}

package/src/modules/merchant/merchant.service.ts

@@ -0,0 +1,46 @@
+import { Injectable } from "@nestjs/common";
+import type { MerchantResponse, PubkeyResponse } from './interfaces'
+import { MonobankHttpClient } from "../../core/http/monobank.http-client";
+
+@Injectable()
+export class MerchantService {
+     public constructor(
+          private readonly http: MonobankHttpClient
+     ) {}
+
+	 /**
+	 * Отримує публічний ключ мерчанта Monobank.
+	 *
+	 * Публічний ключ використовується для:
+	 * - верифікації підписів webhook-повідомлень
+	 * - перевірки автентичності даних від Monobank
+	 *
+	 * @returns {Promise<PubkeyResponse>} Публічний RSA-ключ мерчанта.
+	 *
+	 * @example
+	 * const pubkey = await this.monobankService.merchant.getMerchantPubkey();
+	 * console.log(pubkey.key);
+	 */
+	public async getMerchantPubkey(): Promise<PubkeyResponse> {
+		 return this.http.get("/merchant/pubkey")
+	}
+
+	 /**
+	 * Отримує детальну інформацію про мерчанта Monobank.
+	 *
+	 * Метод повертає основні дані облікового запису мерчанта:
+	 * - ідентифікатор мерчанта
+	 * - назву
+	 * - доступні налаштування
+	 * - інформацію для інтеграції
+	 *
+	 * @returns {Promise<MerchantResponse>} Дані мерчанта.
+	 *
+	 * @example
+	 * const merchant = await this.monobankService.merchant.getMerchant();
+	 * console.log(merchant.name);
+	 */
+     public async getMerchant(): Promise<MerchantResponse> {
+          return this.http.get('/merchant/details')
+     }
+}

package/src/modules/qr/enums/amount-type.enum.ts

@@ -0,0 +1,13 @@
+/**
+ * Тип суми одноразової QR-каси
+ */
+export enum AmountTypeEnum {
+    /** Суму встановлює мерчант */
+    MERCHANT = 'merchant',
+  
+    /** Суму встановлює клієнт */
+    CLIENT = 'client',
+  
+    /** Сума фіксована */
+    FIX = 'fix',
+}

package/src/modules/qr/enums/index.ts

@@ -0,0 +1 @@
+export * from './amount-type.enum'

package/src/modules/qr/interfaces/responses/index.ts

@@ -0,0 +1,2 @@
+export * from './list.response'
+export * from './qr.response'

package/src/modules/qr/interfaces/responses/list.response.ts

@@ -0,0 +1,11 @@
+import type { AmountTypeEnum } from "../../enums";
+import type { QrResponse } from "./qr.response";
+  
+/**
+ * Відповідь API при отриманні списку QR-кас
+ */
+export interface ListResponse {
+    /** Список QR-кас */
+    list: QrResponse[];
+}
+  

package/src/modules/qr/interfaces/responses/qr.response.ts

@@ -0,0 +1,18 @@
+import { AmountTypeEnum } from "../../enums";
+
+/**
+ * Дані однієї QR-каси
+ */
+export interface QrResponse {
+    /** Короткий ідентифікатор QR-каси */
+    shortQrId: string;
+  
+    /** Ідентифікатор QR-каси для встановлення суми оплати на існуючих QR-касах */
+    qrId: string;
+  
+    /** Тип суми одноразової каси */
+    amountType: AmountTypeEnum
+  
+    /** Посилання на оплату QR-каси */
+    pageUrl: string;
+}

package/src/modules/qr/qr.module.ts

@@ -0,0 +1,8 @@
+import { Module } from "@nestjs/common";
+import { QrService } from "./qr.service";
+
+@Module({
+     providers: [QrService],
+     exports: [QrService],
+})
+export class QrModule {}