NestJS Monobank

У цьому розділі ми розглянемо, як отримати поточний статус рахунку за його унікальним ідентифікатором.

Виклик методу для отримання статусу рахунку

Щоб дізнатися статус рахунку, потрібно скористатися методом getInvoiceStatus, передавши в нього ідентифікатор рахунку.

import { Injectable } from '@nestjs/common';
import { MonobankService } from 'nestjs-monobank';

@Injectable()
export className InvoiceService {
  	constructor(private readonly monobankService: MonobankService) {}

  	async checkInvoiceStatus() {
    		const invoiceId = 'khsf8723hsdf8923hf'; // унікальний ID рахунку

    		const status = await this.monobankService.getInvoiceStatus(invoiceId);
    		return status;
  	}
}

Обробка відповіді від API

Метод getInvoiceStatus повертає об’єкт з інформацією про рахунок, включаючи його поточний статус. Приклад відповіді:

{
    "invoiceId": "p2_9ZgpZVsl3", // ідентифікатор рахунку
    "status": null, // статус рахунку (created, processing, hold, success, failure, reversed, expired)
    "failureReason": "Неправильний CVV код", // причина відмови у проведенні платежу (заповнюється при статусі failure)
    "errCode": "59", // код помилки, що виникла під час обробки платежу
    "amount": 4200, // сума рахунку в копійках (наприклад, 4200 = 42.00 грн)
    "ccy": 980, // валюта рахунку (код ISO 4217, 980 = гривня)
    "finalAmount": 4200, // фінальна сума після врахування комісій або часткових повернень
    "createdDate": null, // дата створення рахунку
    "modifiedDate": null, // дата останньої модифікації рахунку
    "reference": "84d0070ee4e44667b31371d8f8813947", // унікальний референс, який встановлюється продавцем
    "destination": "Покупка щастя", // призначення платежу, яке бачить користувач
    "cancelList": [
        {
            "status": null, // статус заявки на скасування (processing, success, failure)
            "amount": 4200, // сума скасованої транзакції в копійках
            "ccy": 980, // валюта транзакції (код ISO 4217)
            "createdDate": null, // дата створення заявки на скасування
            "modifiedDate": null, // дата останнього оновлення заявки
            "approvalCode": "662476", // код авторизації транзакції
            "rrn": "060189181768", // унікальний ідентифікатор транзакції в платіжній системі
            "extRef": "635ace02599849e981b2cd7a65f417fe" // зовнішній референс, який встановлюється продавцем
        }
    ],
    "paymentInfo": {
        "maskedPan": "444403******1902", // маскований номер картки
        "approvalCode": "662476", // код авторизації платежу
        "rrn": "060189181768", // ідентифікатор транзакції в платіжній системі
        "tranId": "13194036", // ідентифікатор транзакції в системі банку
        "terminal": "MI001088", // ідентифікатор терміналу, через який проведено платіж
        "bank": "Універсал Банк", // назва банку, що випустив картку
        "paymentSystem": "visa", // платіжна система (visa, mastercard)
        "paymentMethod": null, // спосіб оплати (pan, apple, google, monobank, wallet, direct)
        "fee": null, // еквайрингова комісія в копійках
        "country": "804", // країна банку (код ISO 3166-1 numeric)
        "agentFee": null // комісія агента в копійках
    },
    "walletData": {
        "cardToken": "67XZtXdR4NpKU3", // токен картки
        "walletId": "c1376a611e17b059aeaf96b73258da9c", // ідентифікатор гаманця
        "status": null // статус токенізації картки (new, created, failed)
    },
    "tipsInfo": {
        "employeeId": null, // ідентифікатор співробітника, якому нараховуються чайові
        "amount": 4200 // сума успішно сплачених чайових у копійках
    }
}

Можливі статуси рахунку

created — рахунок створено, очікує на оплату.
processing — платіж в обробці.
hold — Сума була заблокована на картці платника.
success — рахунок успішно оплачено.
failure — оплата не вдалася.
reversed — Платіж був повернений після успішного списання.
expired — Термін дії рахунку завершився.

Важливо знати:

Вебхуки можуть приходити не по порядку. Щоб отримати актуальний статус — орієнтуйтесь на поле modifiedDate.

Приклад обробки статусів рахунку

1. Очікування оплати (created)

Цей статус означає, що рахунок створено, але ще не оплачений. Користувач ще не перейшов за посиланням або не ввів дані платіжної картки.

{
    "invoiceId": "inv_1abc23",
    "status": "created",
    "amount": 4200,
    "ccy": 980,
    "destination": "Оплата консультації",
    "modifiedDate": 1713954000000
}

2. Обробка платежу (processing)

Означає, що платіж обробляється. Це проміжний стан, коли система ще не завершила перевірку чи зарахування коштів.

{
    "invoiceId": "inv_1abc23",
    "status": "processing",
    "amount": 4200,
    "modifiedDate": 1713954020000
}

3. Блокування суми (hold)

Сума була зарезервована на рахунку платника, але ще не списана. Найчастіше використовується при попередньому погодженні оплати.

{
    "invoiceId": "inv_1abc23",
    "status": "hold",
    "amount": 4200,
    "modifiedDate": 1713954050000
}

4. Успішна оплата (success)

Платіж пройшов успішно, кошти списані та зараховані.

{
    "invoiceId": "inv_1abc23",
    "status": "success",
    "finalAmount": 4200,
    "paymentInfo": {
        "maskedPan": "444403******1902",
        "bank": "Універсал Банк"
    },
    "modifiedDate": 1713954070000
}

5. Помилка при оплаті (failure)

Платіж не вдалось провести. Можлива причина вказана у полі failureReason.

{
    "invoiceId": "inv_1abc23",
    "status": "failure",
    "failureReason": "Недостатньо коштів",
    "errCode": "51",
    "modifiedDate": 1713954100000
}

6. Оплата повернена (reversed)

Кошти були повернуті після успішної оплати. Наприклад, клієнт оформив повернення.

{
    "invoiceId": "inv_1abc23",
    "status": "reversed",
    "cancelList": [
        {
            "amount": 4200,
            "rrn": "060189181768"
        }
    ],
    "modifiedDate": 1713954150000
}

7. Рахунок протерміновано (expired)

Клієнт не здійснив оплату вчасно, тому рахунок більше неактивний.

{
    "invoiceId": "inv_1abc23",
    "status": "expired",
    "modifiedDate": 1713954200000
}

Статус рахунку