Monobank API client for Node.JS

Monobank API client wrapper build on promises.

Installation

yarn:

yarn add monobank-api-client

npm:

npm i monobank-api-client

Usage

Personal API

Read docs here - https://api.monobank.ua/docs/

Visit https://api.monobank.ua - read QR code retrieve your personal TOKEN here.

Create personal client instance

const { ClientFactory } = require('monobank-api-client');

const api = ClientFactory.createPersonal(TOKEN);

Get currency list

const currencyInfo = await api.getCurrencyInfo();

currencyInfo is list of CurrencyInfo DTO.

CurrencyInfo {
    _currencyCodeA:
     { code: 'USD',
       number: '840',
       digits: 2,
       currency: 'US Dollar',
       countries: [Array] },
    _currencyCodeB:
     { code: 'UAH',
       number: '980',
       digits: 2,
       currency: 'Hryvnia',
       countries: [Array] },
    _date: 2019-07-11T07:10:05.000Z,
    _rateSell: 26.0988,
    _rateBuy: 25.761,
    _rateCross: undefined }

Get statement by account ID

const statement = await api.getStatement({
  account: 'ACCOUNT_ID',
  from: new Date('2019-07-04'),
  to: new Date('2019-07-11'),
});

statement is list of Transaction DTO.

Transaction {
    _id: 'xxxxxxxx',
    _time: 2019-07-10T17:04:51.000Z,
    _description: 'Uber',
    _mcc: 4111,
    _hold: true,
    _amount: -800,
    _operationAmount: -800,
    _currencyCode:
     { code: 'UAH',
       number: '980',
       digits: 2,
       currency: 'Hryvnia',
       countries: [Array] },
    _commissionRate: 0,
    _cashbackAmount: 0,
    _balance: 81129811 }

Get statement by currency code

const statement = await api.getStatementByCurrencyCode({
  currencyCode: 'UAH',
  from: new Date('2019-07-04'),
  to: new Date('2019-07-11'),
});

Response will be the same as for previous example.

Corporate API

Read docs here - https://api.monobank.ua/docs/corporate.html

Get access

Generate private key

openssl ecparam -genkey -name secp256k1 -rand /dev/urandom -out priv.key

Out file is priv.key

Be careful! don't share it with anyone

Generate public key

openssl ec -in priv.key -pubout -out pub.key

Out file is pub.key

Request API access

Send an email to [email protected] with next info:

1. app name
2. short description of your app or service
3. attach app logo (.jpg, .png) file
4. attach pub.key file (not private!)

If everything is OK, then you will get approve and KEY_ID.

Now you can start using corporate API.

Create corporate client instance

const { ClientFactory } = require('monobank-api-client');

const api = ClientFactory.createCorporate(KEY_ID, '/path/to/priv.key');

Create access request

const accessInfo = await api.getAccessRequest({ permissions: [Permission.GET_PERSONAL_INFO] });

accessInfo is instance of AccessInfo DTO:

AccessInfo {
  _tokenRequestId: 'aL67772mA7PlJygFjzQP111',
  _acceptUrl: 'https://mbnk.app/auth/aL67772mA7PlJygFjzQP111' }

Store tokenRequestId to DB and give user acceptUrl link.

Check access is granted

const isGranted = await api.checkAccessRequest({ requestid: 'aL67772mA7PlJygFjzQP111' });

Other use cases of corporate API same to personal with same interface.

Error handling

Most of bad cases mapped to custom error classes. All NOT-OK responses from API also mapped to errors, so you could handle them by their classes too.

Actual list below.

• InvalidPrivateKeyError;
• TooManyRequestsError;
• InvalidPermissionValueError;
• AccessForbiddenError;
• InvalidRequestParamsError;
• NotFoundError;
• UnauthorizedRequestError;
• UndefinedApiError;

Examples

Check examples directory for more use cases.

Run personal API example

TOKEN='your-personal-token-here' node examples/personal-app.js

Run corporate API example

KEY_ID='key-id-given-by-monobank' PRIVATE_KEY='path/to/priv.key' node examples/personal-app.js

FYI: Corporate API example has 5s access granted check.

jangolle@imac:/monobank-api-client$ KEY_ID=xxxxxxx PRIVATE_KEY=/xxxx/xxxx/priv.key node examples/corporate-app.js
Go to 'https://mbnk.app/auth/xxxxxxxxxxxxxxxxx' from your mobile device with Monobank client and grant access.
Access for requestId "xxxxxxxxxxxxxxxxx" not granted yet. Auto-check in 5s..
Access for requestId "xxxxxxxxxxxxxxxxx" not granted yet. Auto-check in 5s..
Access for requestId "xxxxxxxxxxxxxxxxx" not granted yet. Auto-check in 5s..
Access granted successfully!

FAQ

Q: Why I receive list of transactions and operation amounts and balances so big (x100) of real amount by my card?

A: Everything is OK. Operation amounts and account balances represented as int64 amount of currency with minor units.

If you need normalized value just do next calculation:

const normalizedAmount = transaction.amount / Math.pow(10, transaction.currencyCode.digits);

monobank-api-client use currency-codes module as dictionary for ISO 4217 to detect minor units and country of usage for currency.

Roadmap

• Tests