Документація API

Виставляйте рахунки з платіжними QR-кодами НБУ, керуйте бізнес-субʼєктами й банківськими рахунками та читайте аналітику платежів — той самий JSON:API, на якому працює app.pmnt.app.

Початок роботи

  1. Створіть обліковий запис і пройдіть онбординг на app.pmnt.app — додайте свій бізнес-субʼєкт та його банківський рахунок IBAN.
  2. Згенеруйте API-ключ у розділі Налаштування → API-ключі . Повний ключ показується лише один раз, одразу після створення — збережіть його в надійному місці.
  3. Зробіть свій перший запит:
curl https://app.pmnt.app/api/me \
  -H "Authorization: Bearer apa_YOUR_API_KEY" \
  -H "Accept: application/vnd.api+json"

Автентифікація

Кожен запит до захищеного ендпоїнта передає ваш API-ключ у заголовку Authorization. Ключі — це непрозорі рядки з префіксом apa_, а не JWT. 

Authorization: Bearer apa_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  • Ключ привʼязаний до вашого облікового запису й має всі його права — окремих обмежень (scopes) для ключів поки немає.
  • Зберігається лише хеш ключа. Якщо ви втратили ключ, створіть новий і відкличте старий — відкликання діє миттєво.
  • Запити без дійсного ключа отримують 403 Forbidden на захищених ендпоїнтах.

Конвенції JSON:API

API відповідає специфікації JSON:API 1.0. Надсилайте та очікуйте тип вмісту application/vnd.api+json. Ендпоїнти списків підтримують стандартні параметри запиту:

Параметр Опис
filter[attr] Фільтрувати список за значенням атрибута. ?filter[state]=paid
sort Поля сортування через кому; префікс - означає спадний порядок. ?sort=-qr_generated_at
page[limit] Keyset-пагінація: розмір сторінки та курсори page[after] / page[before] з попередньої відповіді. ?page[limit]=25
page[count] Додати загальну кількість записів до обʼєкта meta. ?page[count]=true
include Довантажити повʼязані ресурси в тій самій відповіді. ?include=business_entity,bank_account
fields[type] Часткові набори полів: повернути лише перелічені атрибути. ?fields[invoice]=short_code,state

Помилки

Помилки повертаються в конверті помилок JSON:API з HTTP-статусом, що відповідає зовнішній помилці: 

{
  "errors": [
    {
      "status": "403",
      "title": "Forbidden",
      "detail": "forbidden"
    }
  ]
}

Ендпоїнти

Усі шляхи вказані відносно базової URL-адреси. Ендпоїнти з позначкою «Публічний» не потребують API-ключа; решта — потребують. Згенерована специфікація OpenAPI залишається канонічним і завжди актуальним довідником.

Базова URL-адреса: https://app.pmnt.app/api Інтерактивний Swagger UI Специфікація OpenAPI (JSON)

Профіль

Визначення облікового запису за API-ключем.

GET /me API-ключ
Профіль користувача, якому належить наданий API-ключ.

Рахунки

Виставляйте платіжні рахунки й керуйте ними. Кожен рахунок отримує публічну сторінку платника та платіжний QR-код НБУ.

GET /invoices API-ключ
Список ваших рахунків (з фільтрами та пагінацією).
POST /invoices API-ключ
Створити рахунок. Генерація QR-коду ставиться в чергу автоматично.
GET /invoices/{id} API-ключ
Отримати окремий рахунок.
PATCH /invoices/{id} API-ключ
Оновити примітку покупця або позначку «обране».
DELETE /invoices/{id} API-ключ
Видалити рахунок.
POST /invoices/{id}/disable API-ключ
Деактивувати активний рахунок.
POST /invoices/{id}/enable API-ключ
Повторно увімкнути вимкнений рахунок.
POST /invoices/{id}/confirm-payment API-ключ
Позначити рахунок як оплачений.
GET /invoice/{short_code} Публічний
Публічний пошук рахунку за коротким кодом. Сам короткий код є токеном доступу; поля лише для власника залишаються прихованими.

Наприклад, створіть рахунок і отримайте його сторінку платника та QR-код: 

curl -X POST https://app.pmnt.app/api/invoices \
  -H "Authorization: Bearer apa_YOUR_API_KEY" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "invoice",
      "attributes": {
        "business_entity_id": "YOUR_BUSINESS_ENTITY_ID",
        "bank_account_id": "YOUR_BANK_ACCOUNT_ID",
        "purpose": "Оплата за послуги",
        "amount": 1980
      }
    }
  }'

Відповідь надходить зі станом created; qr_url заповнюється асинхронно за мить. Сторінка платника доступна за адресою https://app.pmnt.app/pay/{short_code}. 

{
  "data": {
    "type": "invoice",
    "id": "6b9f2c1e-4a5d-4e8f-9c3b-2d7a8e1f0b4c",
    "attributes": {
      "short_code": "…",
      "state": "created",
      "qr_url": null
    }
  }
}

Бізнес-субʼєкти

Компанії, ФОП та фізичні особи, від імені яких ви виставляєте рахунки. Податкові номери (ЄДРПОУ/РНОКПП) перевіряються автоматично.

GET /business-entities API-ключ
Список ваших бізнес-субʼєктів.
POST /business-entities API-ключ
Створити бізнес-субʼєкт (назва, податковий номер, тип).
GET /business-entities/{id} API-ключ
Отримати окремий бізнес-субʼєкт.
PATCH /business-entities/{id} API-ключ
Оновити назву або тип.
DELETE /business-entities/{id} API-ключ
Видалити субʼєкт, який не має рахунків.
POST /business-entities/{id}/set-default API-ключ
Зробити цей субʼєкт типовим.

Банківські рахунки

IBAN-рахунки, привʼязані до ваших бізнес-субʼєктів. Реквізити банку визначаються з IBAN автоматично.

GET /bank-accounts API-ключ
Список ваших банківських рахунків.
POST /bank-accounts API-ключ
Додати IBAN до бізнес-субʼєкта.
GET /bank-accounts/{id} API-ключ
Отримати окремий банківський рахунок.
PATCH /bank-accounts/{id} API-ключ
Оновити позначку основного рахунку.
DELETE /bank-accounts/{id} API-ключ
Видалити банківський рахунок.
POST /bank-accounts/{id}/set-primary API-ключ
Зробити цей рахунок основним.

Доставка

Необовʼязковий збір даних доставки для рахунків, що потребують відправлення.

POST /delivery-info Публічний
Надіслати дані доставки для рахунку (використовується сторінкою платника).
GET /delivery-providers Публічний
Список підтримуваних служб доставки.
GET /delivery-providers/{id} Публічний
Отримати службу доставки.

Довідники

Довідкові дані для категоризації рахунків: категорії та призначення платежів НБУ.

GET /categories Публічний
Список категорій платежів.
GET /categories/{id} Публічний
Отримати категорію платежу.
GET /purposes Публічний
Список призначень платежів.
GET /purposes/{id} Публічний
Отримати призначення платежу.

Аналітика

Відстеження відвідувань сторінок платника: хто, коли та звідки їх відкривав.

GET /invoices/{id}/visits API-ключ
Список відвідувань сторінки рахунку (до 100 за запит).
GET /invoices/{id}/visits/stats API-ключ
Агрегована статистика відвідувань з необовʼязковим діапазоном from/to.

Життєвий цикл рахунку

Рахунок проходить через такі стани; переходи відбуваються через сторінку платника та наведені вище ендпоїнти:

  • created — Рахунок виставлено, але сторінку платника ще ніхто не відкривав.
  • pending_delivery — Платник відкрив рахунок, що потребує доставки, але ще не надіслав дані доставки.
  • awaiting_payment — Платник відкрив сторінку оплати.
  • paid — Власник підтвердив оплату через confirm-payment.
  • expired — Термін valid_until минув; прострочення застосовується автоматично щохвилини.
  • disabled — Вимкнений вручну через disable; enable повертає його в created.

Повні схеми атрибутів і решта перелічень (field_lock_preset, transfer_type, …) містяться у специфікації OpenAPI .

Підтримка

Маєте запитання щодо API? Напишіть на admin@pmnt.app або перегляньте Довідковий центр.