nestjs-monobank 1.2.8

package/src/modules/qr/qr.service.ts

@@ -0,0 +1,43 @@
+import { Injectable } from "@nestjs/common";
+import { MonobankHttpClient } from "../../core/http/monobank.http-client";
+import type { ListResponse, QrResponse } from "./interfaces/responses";
+
+@Injectable()
+export class QrService {
+    public constructor(public readonly http: MonobankHttpClient) {}
+
+    /**
+     * Отримує список усіх QR-кас мерчанта.
+     * @returns {Promise<ListResponse>} Список QR-кас.
+     * @example
+     * const qrList = await this.monobankService.qr.getList();
+     * console.log(qrList.list);
+     */
+    public async getList(): Promise<ListResponse> {
+        return this.http.get("/merchant/qr/list");
+    }
+
+    /**
+     * Отримує деталі конкретної QR-каси.
+     * @param {string} qrId - Ідентифікатор QR-каси, яку потрібно отримати.
+     * @returns {Promise<QrResponse>} Деталі QR-каси.
+     * @example
+     * const qrDetails = await this.monobankService.qr.getDetails('123456');
+     * console.log(qrDetails.pageUrl);
+     */
+    public async getDetails(qrId: string): Promise<QrResponse> {
+        return this.http.get(`/merchant/qr/details?qrId=${qrId}`);
+    }
+
+    /**
+     * Видаляє суму оплати конкретної QR-каси.
+     * @param {string} qrId - Ідентифікатор QR-каси, для якої потрібно скинути суму.
+     * @returns {Promise<void>} Порожня відповідь при успішному видаленні суми.
+     * @example
+     * await this.monobankService.qr.resetAmount('XJ_DiM4rTd5V');
+     * console.log('Суму було видалено');
+     */
+    public async resetAmount(qrId: string): Promise<void> {
+        return this.http.post(`/merchant/qr/reset-amount`, { qrId });
+    }
+}

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

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

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

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

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

@@ -0,0 +1,119 @@
+/**
+ * Інформація про скасований платіж у виписці.
+ */
+export interface StatmentCancelItem {
+    /**
+     * Сума скасованої транзакції в мінімальних одиницях.
+     */
+    amount: number;
+
+    /**
+     * ISO 4217 код валюти.
+     */
+    ccy: number;
+
+    /**
+     * Дата скасування транзакції або null, якщо відсутня.
+     */
+    date: string | null;
+
+    /**
+     * Код авторизації транзакції.
+     */
+    approvalCode: string;
+
+    /**
+     * RRN (Retrieval Reference Number) транзакції.
+     */
+    rrn: string;
+
+    /**
+     * Маскований номер картки.
+     */
+    maskedPan: string;
+}
+
+/**
+ * Запис про транзакцію у виписці.
+ */
+export interface StatementItem {
+    /**
+     * Ідентифікатор рахунку (invoice).
+     */
+    invoiceId: string;
+
+    /**
+     * Поточний статус транзакції.
+     */
+    status: string;
+
+    /**
+     * Маскований номер картки.
+     */
+    maskedPan: string;
+
+    /**
+     * Дата транзакції або null, якщо відсутня.
+     */
+    date: string | null;
+
+    /**
+     * Платіжна система (Visa, Mastercard тощо) або null.
+     */
+    paymentScheme: string | null;
+
+    /**
+     * Сума транзакції в мінімальних одиницях.
+     */
+    amount: number;
+
+    /**
+     * Сума доходу (прибутку) від транзакції.
+     */
+    profitAmount: number;
+
+    /**
+     * ISO 4217 код валюти.
+     */
+    ccy: number;
+
+    /**
+     * Код авторизації транзакції.
+     */
+    approvalCode: string;
+
+    /**
+     * RRN (Retrieval Reference Number) транзакції.
+     */
+    rrn: string;
+
+    /**
+     * Референс мерчанта або внутрішній ідентифікатор.
+     */
+    reference: string;
+
+    /**
+     * Короткий ідентифікатор QR-коду, пов’язаний з транзакцією.
+     */
+    shortQrId: string;
+
+    /**
+     * Призначення платежу або опис транзакції.
+     */
+    destination: string;
+
+    /**
+     * Список скасувань, пов’язаних з цією транзакцією.
+     */
+    cancelList: StatmentCancelItem[];
+}
+
+/**
+ * Виписка з рахунку, що містить список транзакцій.
+ */
+export interface StatementResponse {
+    /**
+     * Список транзакцій у виписці.
+     */
+    list: StatementItem[];
+}

package/src/modules/statement/statement.module.ts

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

package/src/modules/statement/statement.service.ts

@@ -0,0 +1,25 @@
+import { Injectable } from "@nestjs/common";
+import { MonobankHttpClient } from "../../core/http/monobank.http-client";
+import type { StatementResponse } from "./interfaces";
+
+@Injectable()
+export class StatementService {
+     public constructor(
+          private readonly http: MonobankHttpClient
+     ) {}
+
+     /**
+     * Отримує виписки по рахунках за заданий період.
+     * @param {string} account - Ідентифікатор рахунку (наприклад, номер картки). 0 — основний рахунок в UAH.
+     * @param {string} from - Початковий час періоду в форматі Unix time (секунди).
+     * @param {string} [to] - Кінцевий час періоду в форматі Unix time (секунди). Якщо не вказано, використовується поточний час.
+     * @returns {Promise<StatementResponse>} Список операцій за період.
+     * @example
+     * const statement = await this.monobankService.statement.getStatementByPeriod('0', '1680000000', '1681000000');
+     * console.log(statement.items);
+     */
+     public async getStatementByPeriod(account: string, from: string, to?: string): Promise<StatementResponse> {
+          const url = to ? `/merchant/statement/${account}/${from}/${to}` : `/merchant/statement/${account}/${from}`;
+          return this.http.get("get", url);
+     }
+}

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

@@ -0,0 +1,2 @@
+export * from './wallet-status.enum'
+export * from './subscription-status.enum'

package/src/modules/subscription/enums/subscription-status.enum.ts

@@ -0,0 +1,14 @@
+/**
+ * Статуси підписки.
+ */
+export enum SubscriptionStatusEnum {
+    /**
+     * Підписка активна.
+     */
+    ACTIVE = 'active',
+
+    /**
+     * Підписка скасована.
+     */
+    CANCELLED = 'cancelled',
+}

package/src/modules/subscription/enums/wallet-status.enum.ts

@@ -0,0 +1,19 @@
+/**
+ * Статуси кошика.
+ */
+export enum WalletStatusEnum {
+    /**
+     * Кошик новостворений.
+     */
+    NEW = 'new',
+
+    /**
+     * Кошик успішно створений.
+     */
+    SUCCESS = 'success',
+
+    /**
+     * Кошик не успішно створений.
+     */
+    FAILED = 'failed',
+}

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

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

package/src/modules/subscription/interfaces/requests/client-subscriptions.request.ts

@@ -0,0 +1,31 @@
+import type { SubscriptionStatusEnum } from "../../enums";
+
+/**
+ * Запит на отримання списку підписок клієнта.
+ */
+export interface ClientSubscriptionsRequest {
+    /**
+     * Статус підписки.
+     */
+    status?: SubscriptionStatusEnum;
+
+    /**
+     * Кількість підписок на сторінку.
+     */
+    limit?: number;
+
+    /**
+     * Номер сторінки.
+     */
+    page?: number;
+
+    /**
+     * Дата початку періоду.
+     */
+    dateFrom: string;
+
+    /**
+     * Дата кінця періоду.
+     */
+    dateTo?: string;
+}

package/src/modules/subscription/interfaces/requests/create-subscription.request.ts

@@ -0,0 +1,38 @@
+/**
+ * Запит на створення підписки (регулярного платежу).
+ */
+export interface CreateSubscriptionRequest {
+    /**
+     * Сума регулярного платежу у мінімальних одиницях валюти
+     */
+    amount: number;
+  
+    /**
+     * ISO 4217 код валюти (за замовчуванням 980 — гривня)
+     */
+    ccy?: number;
+  
+    /**
+     * Періодичність списання: 1d, 2w, 1m, 1y
+     */
+    interval: string;
+  
+    /**
+     * Строк дії інвойса у секундах (макс. 30 днів)
+     */
+    validity?: number;
+  
+    /**
+     * URL для повернення користувача після оплати
+     */
+    redirectUrl?: string;
+  
+    /**
+     * Webhook-и для подій підписки
+     */
+    webhookUrls?: {
+      chargeUrl?: string;
+      statusUrl?: string;
+    };
+  }
+  

package/src/modules/subscription/interfaces/requests/edit-subscription.request.ts

@@ -0,0 +1,20 @@
+/**
+ * Запит на зміну (скасування) підписки
+ */
+export interface EditSubscriptionRequest {
+    /**
+     * Ідентифікатор підписки
+     */
+    subscriptionId: string;
+  
+    /**
+     * Дія над підпискою
+     */
+    action: 'cancel';
+  
+    /**
+     * Сума для повернення у мінімальних одиницях валюти
+     * Якщо не передано, повернення коштів не виконується
+     */
+    refundAmount?: number;
+}

package/src/modules/subscription/interfaces/requests/history.request.ts

@@ -0,0 +1,20 @@
+/**
+ * Запит на отримання історії платежів за підпискою
+ */
+export interface HistoryRequest {
+    /** Ідентифікатор підписки */
+    subscriptionId: string;
+  
+    /** Кількість отриманих платежів (дефолт 20) */
+    limit?: number;
+  
+    /** Номер сторінки / зміщення (дефолт 1) */
+    page?: number;
+  
+    /** Дата від (RFC3339) */
+    dateFrom: string;
+  
+    /** Дата до (RFC3339) */
+    dateTo?: string;
+  }
+  

package/src/modules/subscription/interfaces/requests/index.ts

@@ -0,0 +1,4 @@
+export * from './create-subscription.request'
+export * from './edit-subscription.request'
+export * from './history.request'
+export * from './client-subscriptions.request'

package/src/modules/subscription/interfaces/responses/client-subscriptions.response.ts

@@ -0,0 +1,36 @@
+import type { PaginatedResponse } from "../../../../common/interfaces";
+import type { SubscriptionStatusEnum } from "../../enums";
+
+/**
+ * Інформація про підписку клієнта
+ */
+export interface ClientSubscription {
+    /** Ідентифікатор підписки */
+    subscriptionId: string;
+
+    /** Сума списання у мінімальних одиницях валюти */
+    amount: number;
+
+    /** Періодичність списання (наприклад, "1m", "2w") */
+    interval: string;
+
+    /** Дата початку підписки (RFC3339 / ISO8601) */
+    startDate: string;
+
+    /** Дата створення підписки */
+    created: string;
+
+    /** Дата наступного списання (якщо відома) */
+    nextChargeDate?: string;
+
+    /** Дата завершення підписки (якщо задана) */
+    endDate?: string;
+
+    /** Статус підписки */
+    status: SubscriptionStatusEnum;
+}
+
+/**
+ * Відповідь API з історією або списком підписок клієнта
+ */
+export type ClientSubscriptionResponse = PaginatedResponse<ClientSubscription[]>

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

@@ -0,0 +1,6 @@
+import { SubscriptionResponse } from "./subscription.response";
+
+/**
+ * Відповідь на створення підписки
+ */
+export type CreateSubscriptionResponse = SubscriptionResponse;

package/src/modules/subscription/interfaces/responses/history.response.ts

@@ -0,0 +1,12 @@
+import type { PaginatedResponse } from "../../../../common/interfaces";
+import type { WalletStatusEnum } from "../../enums";
+
+export interface PaymentResponse {
+    amount: number
+    status: WalletStatusEnum
+    chargedAt: string
+    ccy: string
+}
+
+export type HistoryResponse = PaginatedResponse<PaymentResponse>;
+  

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

@@ -0,0 +1,5 @@
+export * from './subscription.response'
+export * from './subscription-status.response'
+export * from './client-subscriptions.response'
+export * from './history.response'
+export * from './create-subscription.response'

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

@@ -0,0 +1,40 @@
+import type { SubscriptionSummary, WalletData } from "../../../../common/interfaces";
+import type { SubscriptionStatusEnum } from "../../enums";
+
+/**
+ * Статус підписки клієнта
+ */
+export interface SubscriptionStatusResponse {
+  /** Ідентифікатор підписки */
+  subscriptionId: string;
+
+  /** Статус підписки */
+  status: SubscriptionStatusEnum;
+
+  /** Дата початку підписки (ISO 8601) */
+  startDate: string;
+
+  /** Дата завершення підписки (ISO 8601), якщо підписка закінчена або запланована */
+  endDate?: string;
+
+  /** Сума списання у мінімальних одиницях валюти */
+  amount: number;
+
+  /** Числовий код валюти ISO 4217 */
+  ccy: number;
+
+  /** Періодичність списання (наприклад, "1m", "2w") */
+  interval: string;
+
+  /** Дата наступного списання (ISO 8601), якщо відома */
+  nextChargeDate?: string;
+
+  /** Причина скасування, якщо підписка була скасована */
+  cancellationDesc?: string;
+
+  /** Статистика платежів по підписці */
+  summary: SubscriptionSummary;
+
+  /** Дані гаманця, через який проходять списання */
+  walletData: WalletData;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Відповідь API при створенні або отриманні підписки
+ */
+export interface SubscriptionResponse {
+    /** Ідентифікатор підписки */
+    subscriptionId: string;
+  
+    /** URL сторінки підписки для користувача */
+    pageUrl: string;
+  }
+  

package/src/modules/subscription/subscription.module.ts

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

package/src/modules/subscription/subscription.service.ts

@@ -0,0 +1,121 @@
+import { Injectable } from '@nestjs/common';
+import type {
+       ClientSubscriptionResponse,
+       ClientSubscriptionsRequest,
+       CreateSubscriptionRequest,
+       CreateSubscriptionResponse,
+       EditSubscriptionRequest,
+       HistoryRequest,
+       HistoryResponse,
+       SubscriptionStatusResponse
+} from "./interfaces";
+import { MonobankHttpClient } from "../../core/http/monobank.http-client";
+
+@Injectable()
+export class SubscriptionService {
+       public constructor(private readonly http: MonobankHttpClient) {}
+
+       /**
+        * Створює нову підписку (регулярний платіж).
+        * Після створення клієнта необхідно перенаправити на `pageUrl`
+        * для підтвердження підписки.
+        *
+        * @param {CreateSubscriptionRequest} data Дані для створення підписки
+        * @returns {Promise<CreateSubscriptionResponse>} Обʼєкт із посиланням на сторінку оплати
+        *
+        * @example
+        * const subscription = await this.monobankService.subscription.create({
+        *   amount: 19900,
+        *   redirectUrl: 'https://example.com/payment/success',
+        *   webHookUrls: {
+        *       chargeUrl: "https://example.com/api/v1/webhooks/monobank/charge"
+        *       statusUrl: "https://example.com/api/v1/webhooks/monobank/status"
+        *   }
+        *   interval: '1m',
+        *   validity: 2592000
+        * });
+        *
+        * console.log(subscription.pageUrl);
+        */
+       public async create(data: CreateSubscriptionRequest): Promise<CreateSubscriptionResponse> {
+              return this.http.post('/merchant/subscription/create', data)
+       }
+
+       /**
+        * Отримує поточний статус підписки.
+        *
+        * @param {string} subscriptionId Унікальний ідентифікатор підписки
+        * @returns {Promise<SubscriptionStatusResponse>} Інформація про статус підписки
+        *
+        * @example
+        * const status = await this.monobankService.subscription.getStatus('sub_123456');
+        * console.log(status.status);
+        */
+       public async getStatus(subscriptionId: string): Promise<SubscriptionStatusResponse> {
+              return this.http.get(`/merchant/subscription/status?subscriptionId=${subscriptionId}`);
+       }
+
+       /**
+        * Отримує історію платежів по підписці.
+        *
+        * @param {HistoryRequest} query Параметри фільтрації (subscriptionId, дати, ліміти)
+        * @returns {Promise<HistoryResponse>} Список платежів
+        *
+        * @example
+        * const history = await this.monobankService.subscription.getHistory({
+        *   subscriptionId: 'sub_123456',
+        *   dateFrom: '2025-01-01T00:00:00Z',
+        *   limit: 20
+        * });
+        */
+       public async getHistory(query: HistoryRequest): Promise<HistoryResponse> {
+              return this.http.get('/merchant/subscription/payments', { params: query })
+       }
+
+
+       /**
+        * Отримує список підписок мерчанта або клієнта.
+        *
+        * @param {ClientSubscriptionsRequest} query Параметри пошуку (статус, дати, сторінка)
+        * @returns {Promise<ClientSubscriptionsResponse>} Масив підписок
+        *
+        * @example
+        * const subscriptions = await this.monobankService.subscription.getClientSubscriptions({
+        *   status: 'active',
+        *   limit: 10
+        * });
+        */
+       public async getClientSubscriptions(query: ClientSubscriptionsRequest): Promise<ClientSubscriptionResponse> {
+              return this.http.get(`/merchant/subscription/list`, { params: query });
+       }
+
+       /**
+        * Редагує або скасовує підписку.
+        * На даний момент підтримується дія `cancel`.
+        *
+        * @param {EditSubscriptionRequest} data Дані для редагування підписки
+        * @returns {Promise<void>}
+        *
+        * @example
+        * await this.monobankService.subscription.editSubscription({
+        *   subscriptionId: 'sub_123456',
+        *   action: 'cancel'
+        * });
+        */
+       public async editSubscription(data: EditSubscriptionRequest): Promise<void> {
+              return this.http.post(`/merchant/subscription/edit`, data);
+       }
+
+       /**
+        * Видаляє (деактивує) підписку.
+        *
+        * @param {string} subscriptionId Ідентифікатор підписки
+        * @returns {Promise<void>}
+        *
+        * @example
+        * await this.monobankService.subscription.removeSubscription('sub_123456');
+        */
+       public async removeSubscription(subscriptionId: string): Promise<void> {
+              return this.http.post(`/merchant/subscription/remove?subscriptionId=${subscriptionId}`);
+       }
+}

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

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

package/src/modules/wallet/interfaces/requests/create-card-token.request.ts

@@ -0,0 +1,50 @@
+import type { MerchantPaymInfoItem } from "../../../../common/interfaces";
+
+/**
+ * Запит на створення платежу за токеном картки.
+ */
+export interface CreateCardTokenRequest {
+    /**
+     * Токен картки, отриманий з особистого кабінету або тестовий токен
+     */
+    cardToken: string;
+
+    /**
+     * Сума платежу в мінімальних одиницях (наприклад, копійки для гривні)
+     */
+    amount: number;
+
+    /**
+     * ISO 4217 код валюти
+     */
+    ccy: number;
+
+    /**
+     * (Не обов'язковий) URL для переадресації користувача після 3DS підтвердження
+     */
+    redirectUrl?: string;
+
+    /**
+     * (Не обов'язковий) URL для вебхука, на який надсилаються оновлення статусу платежу
+     */
+    webHookUrl?: string;
+
+    /**
+     * Тип ініціації платежу:
+     * "merchant" - ініціатива мерчанту (наприклад, регулярний платіж)
+     * "client" - ініціатива клієнта (клієнт підтверджує платіж)
+     */
+    initiationKind: "merchant" | "client";
+
+    /**
+     * (Не обов'язковий) Тип платежу:
+     * "debit" - списання коштів
+     * "hold" - блокування коштів
+     */
+    paymentType?: "debit" | "hold";
+
+    /**
+     * (Не обов'язковий) Інформація про платіж, для зв'язку з ПРРО через веб-кабінет
+     */
+    merchantPaymInfo?: MerchantPaymInfoItem;
+}