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

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

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