openapi: 3.0.3
info:
  description: |-
    API для отримання інформації про виписки та стан особистого рахунку та рахунків ФОП. Для надання доступу потрібно пройти авторизацію у особистому кабінеті https://api.monobank.ua/ та отримати токен для персонального використання.

    Якщо у вас є запитання щодо роботи API, запрошуємо до ком'юніті у [Telegram-групі](https://t.me/joinchat/FiAEWhDf-QzTqM4wzEtffw).
    API недоступне для клієнтів до 16 років, дані за дитячими рахунками доступні з батьківського акаунту.
    Якщо у вас є сервіс і ви хочете централізовано приєднатися до API для надання послуг клієнтам, потрібно підключитися до [API для провайдерів послуг](/docs/corporate.html), що має більше можливостей. Якщо дані клієнтів не будуть надходити на ваші сервери або ви робите сервіс для своєї родини, використання корпоративного API необов'язкове. Розробка бібліотек або програм, які будуть використовувати клієнти особисто (дані клієнта не будуть проходити черeз вузли розробника), також не потребують використання корпоративного API.

    Це надасть змогу клієнтам monobank авторизуватись у вашому сервісі (наприклад, у фінансовому менеджері) для надання інформації про стан рахунку або виписки.

    У разі виявлення експлуатації цього API в якості корпоративного, банк залишає за собою право накласти санкції на компанію.
  title: Monobank open API
  version: v2303
  x-logo:
    url: logo.png
    altText: logo
servers:
- url: https://api.monobank.ua
tags:
- description: Загальна інформація що надається без авторизації.
  name: Публічні дані
- description: "Інформація, що надається тільки за наявстю token-а доступу, який к\
    лієнт може отримати в особистому кабінеті https://api.monobank.ua/"
  name: Клієнтські персональні дані
paths:
  /bank/currency:
    get:
      description: Отримати базовий перелік курсів валют monobank. Інформація кешується
        та оновлюється не частіше 1 разу на 5 хвилин.
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrencyInfo'
          description: Інформація про курс валют
      summary: Отримання курсів валют
      tags:
      - Публічні дані
  /personal/client-info:
    get:
      description: Отримання інформації про клієнта та переліку його рахунків і банок.
        Обмеження на використання функції не частіше ніж 1 раз у 60 секунд.
      parameters:
      - description: Token для особистого доступу до API
        example: u3AulkpZFI1lIuGsik6vuPsVWqN7GoWs6o_MO2sdf301
        explode: false
        in: header
        name: X-Token
        required: true
        schema:
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
          description: Statement list
      summary: Інформація про клієнта
      tags:
      - Клієнтські персональні дані
  /personal/webhook:
    post:
      description: |-
        Встановлення URL користувача:
        - Для підтвердження коректності наданої адреси, на неї надсилається GET-запит. Сервер має відповісти строго HTTP статус-кодом 200, і ніяким іншим. Якщо валідацію пройдено, на задану адресу починають надсилатися POST запити з подіями.
        - Події надсилаються у наступному вигляді: POST запит на задану адресу у форматі `{type:"StatementItem", data:{account:"...", statementItem:{#StatementItem}}}`. Якщо сервіс користувача не відповість протягом 5с на команду, сервіс повторить спробу ще через 60 та 600 секунд. Якщо на третю спробу відповідь отримана не буде, функція буде вимкнута. Відповідь сервера має строго містити HTTP статус-код 200.
      parameters:
      - description: Token для особистого доступу до API
        explode: false
        in: header
        name: X-Token
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetWebHook'
        required: true
      responses:
        "200":
          description: ok
      summary: Встановлення WebHook
      tags:
      - Клієнтські персональні дані
  /personal/statement/{account}/{from}/{to}:
    get:
      description: |-
        Отримання виписки за час від {from} до {to} часу в секундах в форматі Unix time. Максимальний час, за який можливо отримати виписку — 31 доба + 1 година (2682000 секунд).

        Обмеження на використання функції — не частіше ніж 1 раз на 60 секунд.

        Повертає 500 транзакцій з кінця, тобто від часу to до from. Якщо кількість транзакцій = 500, потрібно зробити ще один запит, зменшивши час to до часу останнього платежу, з відповіді. Якщо знову кількість транзакцій = 500, то виконуєте запити до того часу, поки кількість транзакцій не буде < 500. Відповідно, якщо кількість транзакцій < 500, то вже отримано всі платежі за вказаний період.
      parameters:
      - description: Token для особистого доступу до API
        explode: false
        in: header
        name: X-Token
        required: true
        schema:
          type: string
        style: simple
      - description: Ідентифікатор рахунку або банки з переліків Statement list або
          0 - дефолтний рахунок.
        explode: false
        in: path
        name: account
        required: true
        schema:
          type: string
        style: simple
      - description: Початок часу виписки.
        example: "1546304461"
        explode: false
        in: path
        name: from
        required: true
        schema:
          type: string
        style: simple
      - description: "Останній час виписки (якщо відсутній, буде використовуватись\
          \ поточний час)."
        example: "1546306461"
        explode: false
        in: path
        name: to
        required: false
        schema:
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatementItems'
          description: Statement list
      summary: Виписка
      tags:
      - Клієнтські персональні дані
components:
  schemas:
    SetWebHook:
      description: "URL для надсиляння подій по зміні балансу рахунків фізичних ос\
        іб, ФОП та банок"
      example:
        webHookUrl: https://example.com/some_random_data_for_security
      properties:
        webHookUrl:
          example: https://example.com/some_random_data_for_security
          type: string
      type: object
    UserInfo:
      description: Опис клієнта та його рахунків і банок.
      example:
        clientId: 3MSaMMtczs
        permissions: psfj
        webHookUrl: https://example.com/some_random_data_for_security
        name: Мазепа Іван
        jars:
        - sendId: uHWzqVoZuH
          goal: 10000000
          balance: 1000000
          description: На тепловізор
          id: kKGVoZuHWzqVoZuH
          title: На тепловізор
          currencyCode: 980
        - sendId: uHWzqVoZuH
          goal: 10000000
          balance: 1000000
          description: На тепловізор
          id: kKGVoZuHWzqVoZuH
          title: На тепловізор
          currencyCode: 980
        accounts:
        - sendId: uHWzqVoZuH
          balance: 10000000
          cashbackType: UAH
          maskedPan:
          - 537541******1234
          iban: UA733220010000026201234567890
          creditLimit: 10000000
          id: kKGVoZuHWzqVoZuH
          type: black
          currencyCode: 980
        - sendId: uHWzqVoZuH
          balance: 10000000
          cashbackType: UAH
          maskedPan:
          - 537541******1234
          iban: UA733220010000026201234567890
          creditLimit: 10000000
          id: kKGVoZuHWzqVoZuH
          type: black
          currencyCode: 980
      properties:
        clientId:
          description: Ідентифікатор клієнта (збігається з id для send.monobank.ua)
          example: 3MSaMMtczs
          type: string
        name:
          description: Ім'я клієнта
          example: Мазепа Іван
          type: string
        webHookUrl:
          description: URL для надсиляння подій по зміні балансу рахунку
          example: https://example.com/some_random_data_for_security
          type: string
        permissions:
          description: "Перелік прав, які які надає сервіс (1 літера на 1 permission)."
          example: psfj
          type: string
        accounts:
          description: Перелік доступних рахунків
          items:
            $ref: '#/components/schemas/UserInfo_accounts_inner'
          type: array
        jars:
          description: Перелік банок
          items:
            $ref: '#/components/schemas/UserInfo_jars_inner'
          type: array
      type: object
    StatementItems:
      description: Перелік транзакцій за вказанний час
      items:
        $ref: '#/components/schemas/StatementItems_inner'
      type: array
    CurrencyInfo:
      description: "Перелік курсів. Кожна валютна пара може мати одне і більше пол\
        ів з  rateSell, rateBuy, rateCross."
      items:
        $ref: '#/components/schemas/CurrencyInfo_inner'
      type: array
    Error:
      properties:
        errorDescription:
          description: "Текст помилки для кінцевого користувача, для автоматичного\
            \ оброблення потрібно аналізувати HTTP код відповіді (200, 404, 429 та\
            \ інші)"
          type: string
      type: object
    UserInfo_accounts_inner:
      example:
        sendId: uHWzqVoZuH
        balance: 10000000
        cashbackType: UAH
        maskedPan:
        - 537541******1234
        iban: UA733220010000026201234567890
        creditLimit: 10000000
        id: kKGVoZuHWzqVoZuH
        type: black
        currencyCode: 980
      properties:
        id:
          description: Ідентифікатор рахунку
          example: kKGVoZuHWzqVoZuH
          type: string
        sendId:
          description: "Ідентифікатор для сервісу https://send.monobank.ua/{sendId}"
          example: uHWzqVoZuH
          type: string
        balance:
          description: "Баланс рахунку в мінімальних одиницях валюти (копійках, це\
            нтах)"
          example: 10000000
          format: int64
          type: number
        creditLimit:
          description: Кредитний ліміт
          example: 10000000
          format: int64
          type: number
        type:
          description: Тип рахунку
          enum:
          - black
          - white
          - platinum
          - iron
          - fop
          - yellow
          - eAid
          example: black
          type: string
        currencyCode:
          description: Код валюти рахунку відповідно ISO 4217
          example: 980
          format: int32
          type: number
        cashbackType:
          description: Тип кешбеку який нараховується на рахунок
          enum:
          - None
          - UAH
          - Miles
          example: UAH
          type: string
        maskedPan:
          description: Перелік замаскованних номерів карт (більше одного може бути
            у преміальних карт)
          example:
          - 537541******1234
          type: array
        iban:
          description: IBAN рахунку
          example: UA733220010000026201234567890
          type: string
      type: object
    UserInfo_jars_inner:
      example:
        sendId: uHWzqVoZuH
        goal: 10000000
        balance: 1000000
        description: На тепловізор
        id: kKGVoZuHWzqVoZuH
        title: На тепловізор
        currencyCode: 980
      properties:
        id:
          description: Ідентифікатор банки
          example: kKGVoZuHWzqVoZuH
          type: string
        sendId:
          description: "Ідентифікатор для сервісу https://send.monobank.ua/{sendId}"
          example: uHWzqVoZuH
          type: string
        title:
          description: Назва банки
          example: На тепловізор
          type: string
        description:
          description: Опис банки
          example: На тепловізор
          type: string
        currencyCode:
          description: Код валюти банки відповідно ISO 4217
          example: 980
          format: int32
          type: number
        balance:
          description: "Баланс банки в мінімальних одиницях валюти (копійках, цент\
            ах)"
          example: 1000000
          format: int64
          type: number
        goal:
          description: "Цільова сума для накопичення в банці в мінімальних одиниця\
            х валюти (копійках, центах)"
          example: 10000000
          format: int64
          type: number
      type: object
    StatementItems_inner:
      example:
        amount: -95000
        commissionRate: 0
        counterIban: UA898999980000355639201001404
        counterEdrpou: "3096889974"
        cashbackAmount: 19000
        description: Покупка щастя
        originalMcc: 7997
        mcc: 7997
        hold: false
        counterName: ТОВАРИСТВО З ОБМЕЖЕНОЮ ВІДПОВІДАЛЬНІСТЮ «ВОРОНА»
        balance: 10050000
        operationAmount: -95000
        comment: За каву
        invoiceId: 2103.в.27
        id: ZuHWzqkKGVo=
        time: 1554466347
        currencyCode: 980
        receiptId: XXXX-XXXX-XXXX-XXXX
      properties:
        id:
          description: Унікальний id транзакції
          example: ZuHWzqkKGVo=
          type: string
        time:
          description: Час транзакції в секундах в форматі Unix time
          example: 1554466347
          format: int64
          type: number
        description:
          description: Опис транзакцій
          example: Покупка щастя
          type: string
        mcc:
          description: "Код типу транзакції (Merchant Category Code), відповідно ISO\
            \ 18245"
          example: 7997
          format: int32
          type: number
        originalMcc:
          description: "Оригінальний код типу транзакції (Merchant Category Code),\
            \ відповідно ISO 18245"
          example: 7997
          format: int32
          type: number
        hold:
          description: "Статус блокування суми (детальніше у [wiki](https://en.wikipedia.org/wiki/Authorization_hold))"
          example: false
          type: boolean
        amount:
          description: "Сума у валюті рахунку в мінімальних одиницях валюти (копій\
            ках, центах)"
          example: -95000
          format: int64
          type: number
        operationAmount:
          description: "Сума у валюті транзакції в мінімальних одиницях валюти (ко\
            пійках, центах)"
          example: -95000
          format: int64
          type: number
        currencyCode:
          description: Код валюти рахунку відповідно ISO 4217
          example: 980
          format: int32
          type: number
        commissionRate:
          description: "Розмір комісії в мінімальних одиницях валюти (копійках, це\
            нтах)"
          example: 0
          format: int64
          type: number
        cashbackAmount:
          description: "Розмір кешбеку в мінімальних одиницях валюти (копійках, це\
            нтах)"
          example: 19000
          format: int64
          type: number
        balance:
          description: "Баланс рахунку в мінімальних одиницях валюти (копійках, це\
            нтах)"
          example: 10050000
          format: int64
          type: number
        comment:
          description: "Коментар до переказу, уведений користувачем. Якщо не вказа\
            ний, поле буде відсутнім"
          example: За каву
          type: string
        receiptId:
          description: Номер квитанції для check.gov.ua. Поле може бути відсутнім
          example: XXXX-XXXX-XXXX-XXXX
          type: string
        invoiceId:
          description: "Номер квитанції ФОПа, приходить у випадку якщо це операція\
            \ із зарахуванням коштів"
          example: 2103.в.27
          type: string
        counterEdrpou:
          description: "ЄДРПОУ контрагента, присутній лише для елементів виписки р\
            ахунків ФОП"
          example: "3096889974"
          type: string
        counterIban:
          description: "IBAN контрагента, присутній лише для елементів виписки рах\
            унків ФОП"
          example: UA898999980000355639201001404
          type: string
        counterName:
          description: Найменування контрагента
          example: ТОВАРИСТВО З ОБМЕЖЕНОЮ ВІДПОВІДАЛЬНІСТЮ «ВОРОНА»
          type: string
      type: object
    CurrencyInfo_inner:
      example:
        date: 1552392228
        currencyCodeA: 840
        currencyCodeB: 980
        rateBuy: 27.2
        rateSell: 27
        rateCross: 27.1
      properties:
        currencyCodeA:
          description: Код валюти рахунку відповідно ISO 4217
          example: 840
          format: int32
          type: number
        currencyCodeB:
          description: Код валюти рахунку відповідно ISO 4217
          example: 980
          format: int32
          type: number
        date:
          description: Час курсу в секундах в форматі Unix time
          example: 1552392228
          format: int64
          type: number
        rateSell:
          example: 27
          format: float
          type: number
        rateBuy:
          example: 27.2
          format: float
          type: number
        rateCross:
          example: 27.1
          format: float
          type: number
      type: object