monobank

README

monobank-sdk

🇺🇦 Українська · 🇬🇧 English

Повноцінний Go SDK для всіх публічних API monobank: personal, corporate (з monoКЕП), business (corp-api для юр. осіб), acquiring (еквайринг із subscriptions / monopay-keys / split-receivers / T2P), installment (Покупка частинами) та jar (публічні банки). Поза самими клієнтами SDK містить серверні helper-и, без яких безпечно приймати webhook-и доводилось би писати самотужки — верифікація ECDSA-підпису, готовий http.Handler, дедуплікація ретраїв, HMAC-SHA256 для ПЧ-callback, типізовані enum-и MCC та валют, утиліти для тестування.

Стартував як форк vtopc/go-monobank; розрісся, бо upstream свідомо лишається тонкою обгорткою лише над Open API. Тут ви знайдете все, чого там нема.

Встановлення

go get github.com/OlexiyOdarchuk/go-monobank-sdk

Потрібен Go 1.25+ (пагінатори використовують iter.Seq2; весь воркспейс пінить 1.25 через залежність otelmonobank від OpenTelemetry).

Покриття API

Покрито всі п'ять публічних API monobank плюс два community-документовані ендпоінти банок (jars). Внутрішній mobile-API публічної специфікації не має — поза скоупом.

API	Специфікація	Підпакет	Endpoints
Open API — personal (X-Token)	api.monobank.ua/docs	personal	4
Open API — corporate (ECDSA) + monoКЕП	api-docs/providers	corporate	11
corp-api для юр. осіб	corp-api.monobank.ua	business	23
Acquiring (/api/merchant/*)	api-docs/acquiring	acquiring	31
Покупка частинами (HMAC-SHA256)	api-docs/chast	installment	14
JAR / банки (community)	community docs	jar	2

Структура пакетів

monobank-sdk/
├── (root)          базовий HTTP-транспорт: Client, Option, retry, hooks
├── auth/           Authorizer + Personal/Corporate/Public + monoКЕП хелпери
├── bank/           публічні endpoint-и (Rates, ServerKey) + спільні типи
│                   (ClientInfo, Account, Jar, Transaction) + Rates.Convert
├── personal/       Personal Open API (X-Token)
├── corporate/      Corporate Open API (ECDSA) + monoКЕП
├── business/       corp-api.monobank.ua — 23 endpoint-и
├── acquiring/      /api/merchant/* — 31 endpoint (інвойси, QR, wallet,
│                   subscriptions, monopay-keys, split, T2P) +
│                   ECDSA-верифікація webhook
├── installment/    «Покупка частинами» (u2.monobank.com.ua) — 14 endpoint-ів,
│                   HMAC-SHA256 підпис тіла, VerifyCallback
├── jar/            публічні банки: /bank/jar/{id} + send.monobank.ua/api/handler
├── webhook/        Verify, Parse, http.Handler, Deduper для personal webhook
├── monobanktest/   фейковий monobank-сервер + білдери для тестування
├── money/          типізована грошова сума з валютою + арифметика
├── currency/       ISO 4217 числовий код + alpha-3 ім'я
├── mcc/            ISO 18245 enum + Category (Groceries, Fuel, Restaurants…)
└── otelmonobank/   (окремий sub-module) OpenTelemetry-інтеграція

Кожен підпакет імпортується незалежно — беріть рівно те, що потрібно.

Швидкий старт: Personal API

package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "time"

    "github.com/OlexiyOdarchuk/go-monobank-sdk/personal"
)

func main() {
    cli := personal.New(os.Getenv("MONO_TOKEN"))
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    info, err := cli.ClientInfo(ctx)
    if err != nil {
        log.Fatal(err)
    }
    for _, a := range info.Accounts {
        fmt.Println(a.IBAN, a.Balance)
    }

    // Виписка за період > 31 дня автоматично розбивається на сторінки.
    to := time.Now()
    from := to.Add(-90 * 24 * time.Hour)
    for tx, err := range cli.TransactionsRangeIter(ctx, info.Accounts[0].AccountID, from, to) {
        if err != nil {
            log.Fatal(err)
        }
        fmt.Println(tx.Time, tx.Description, tx.Amount, tx.MCCCode().Category())
    }
}

Токен — на https://api.monobank.ua/.

Швидкий старт: Webhook (приймати події)

package main

import (
    "context"
    "log"
    "net/http"

    "github.com/OlexiyOdarchuk/go-monobank-sdk/bank"
    "github.com/OlexiyOdarchuk/go-monobank-sdk/webhook"
)

func main() {
    keys := bank.New() // KeyProvider — тягне публічний ключ /bank/sync і кешує

    h, err := webhook.NewHandler(context.Background(), webhook.Options{
        Keys:  keys,
        Dedup: webhook.NewMemoryDeduper(1024),
        OnEvent: func(_ context.Context, e *webhook.Response) error {
            t := e.Data.Transaction
            log.Printf("%s · %s · %s",
                e.Data.AccountID, t.Amount, t.MCCCode().Category())
            return nil
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    http.Handle("/webhook", h)
    log.Fatal(http.ListenAndServe(":8080", nil))
}

Підписатись на URL — один раз: personal.New(token).SetWebHook(ctx, "https://you/webhook").

webhook.Handler сам:

• завантажує ключ через Keys.ServerKey на старті й автоматично рефрешить при ротації (X-Key-Id у заголовку перестав збігатися),
• перевіряє ECDSA-підпис у X-Sign,
• парсить payload у типізований Response,
• консультується з Deduper, щоб Mono-ретраї не виконали ваш callback двічі,
• повертає 200/400/500 відповідно до результату.

Швидкий старт: Corporate API (ECDSA)

package main

import (
    "context"
    "os"

    "github.com/OlexiyOdarchuk/go-monobank-sdk/auth"
    "github.com/OlexiyOdarchuk/go-monobank-sdk/corporate"
)

func main() {
    privPEM, _ := os.ReadFile("mono-corp.key")
    maker, _ := auth.NewCorpAuthMaker(privPEM)
    cli, _ := corporate.New(maker)

    ctx := context.Background()
    tok, _ := cli.Auth(ctx, "https://yourapp/cb", auth.PermSt, auth.PermPI)
    // → редіректнути користувача на tok.AcceptURL,
    //    потім поллити cli.CheckAuth(ctx, tok.RequestID).
}

Підпакет corporate також покриває monoКЕП — електронні підписи документів у мобільному додатку: cli.SignatureCreate / SignatureStatus / SignatureCancel.

Швидкий старт: Business API (юр. особи)

import "github.com/OlexiyOdarchuk/go-monobank-sdk/business"

cli := business.New(os.Getenv("MONO_BUSINESS_TOKEN"))
accs, _ := cli.Accounts(ctx)

key, err := business.NewIdempotencyKey() // UUID v4
if err != nil { return err }
out, _ := cli.PreparePayment(ctx, key, &business.PaymentRequest{...})

Усі мутаційні endpoint-и приймають Idempotency-Key — генеруйте його через business.NewIdempotencyKey() на кожну логічну спробу. Повтор із тим самим ключем гарантовано безпечний — банк віддасть ту саму відповідь, не дублюючи операцію. Порожній ключ відхиляється локально (ErrIdempotencyKeyRequired), бо банк потрактує відсутність ключа як «дедуп не треба» і створить дубль.

Швидкий старт: Acquiring (еквайринг)

import "github.com/OlexiyOdarchuk/go-monobank-sdk/acquiring"

cli := acquiring.New(os.Getenv("MONO_ACQUIRING_TOKEN"))

inv, _ := cli.CreateInvoice(ctx, &acquiring.CreateInvoiceRequest{
    Amount:   10000,           // копійки → 100.00 грн
    Currency: currency.UAH,    // або просто 980
    MerchantPaymInfo: &acquiring.MerchantPaymInfo{
        Reference:   "order-42",
        Destination: "Замовлення №42",
    },
    Validity:    600,
    PaymentType: acquiring.PaymentDebit,
})
// → клієнту віддаєте inv.PageURL; статус — через webhook або InvoiceStatus.

// Верифікація acquiring webhook (ECDSA-SHA256, ASN.1 DER).
// Поле `key` із /api/merchant/pubkey — це base64(PEM(SPKI)).
keyResp, _ := cli.PubKey(ctx)
pub, _ := keyResp.Public() // або acquiring.ParsePubKey([]byte(keyResp.Key))
if err := acquiring.VerifyWebhook(pub, body, r.Header.Get("X-Sign")); err != nil {
    http.Error(w, "bad signature", 400)
    return
}

// Опційно: захист від replay'а — відхилити webhook-и, modifiedDate яких
// старший за 5 хвилин. Це поверх dedup-у за (invoiceId, modifiedDate),
// який ви ОБОВ'ЯЗКОВО мусите тримати persistent (Mono ретраїть на 60s/600s).
if err := acquiring.VerifyWebhookFresh(pub, body, sig, 5*time.Minute); err != nil {
    // ErrWebhookStale / ErrWebhookNoTimestamp / ErrBadSignature
}

Покриті сценарії: одношагова оплата (debit), auth-then-capture (hold + finalize), рекурент через токенізовані картки, регулярні платежі (SubscriptionCreate/Edit/Remove/Status/List/Payments), QR-каси, повернення, фіскальні чеки, період-виписка для звірки, прямі PAN-потоки (для мерчантів з PCI DSS scope), monopay-кнопка (MonoPayKeyImport/Delete/List), розщеплення платежів (SplitReceivers), T2P-термінали (Terminals).

Швидкий старт: Installment («Покупка частинами»)

import "github.com/OlexiyOdarchuk/go-monobank-sdk/installment"

cli, err := installment.New(
    os.Getenv("CHAST_STORE_ID"),
    os.Getenv("CHAST_SECRET"),
    installment.WithBaseURL(installment.BaseURLSandbox),
)
if err != nil { return err } // ErrEmptyStoreID / ErrEmptySecret / ErrInsecureBaseURL

order, _ := cli.CreateOrder(ctx, &installment.CreateOrderRequest{
    StoreOrderID: "ORD-001",
    ClientPhone:  "+380501234561",                // ...1 = sandbox-успіх
    TotalSum:     installment.NewMoney(2499, 99), // 2499.99 UAH (типована Money)
    Invoice: installment.CreateOrderInvoice{
        Number: "INV-001", Date: "2026-05-13",
        Source: installment.SourceInternet,
    },
    AvailablePrograms: []installment.Program{{AvailablePartsCount: []int{3, 6}}},
    Products: []installment.Product{
        {Name: "Кит-набір", Count: 1, Sum: installment.NewMoney(2499, 99)},
    },
    ResultCallback: "https://shop/api/chast/cb",
})
// → poll cli.OrderState(ctx, order.OrderID) до WAITING_FOR_STORE_CONFIRM
// → видали товар → cli.ConfirmOrder(ctx, order.OrderID)

Підпис тіла рахується автоматично (HMAC-SHA256 з вашим store-secret). Для вхідного callback від банку — cli.VerifyCallback(body, signatureHeader). Невалідна довжина підпису → ErrCallbackBadLength; невалідний MAC → ErrCallbackSignatureMismatch — окремі sentinel-и для security-телеметрії.

Усі money-поля installment (TotalSum, Sum, Reverse.Sum, Commission, CreditAmount тощо) — це installment.Money із exact-decimal JSON serializer (int64 копійок всередині, MarshalJSON через рядкову арифметику). float64 на парсингу/серіалізації не з'являється — 0.10/0.20/0.30 round-trip точно.

Швидкий старт: Jar (банки)

import "github.com/OlexiyOdarchuk/go-monobank-sdk/jar"

cli, err := jar.New()
if err != nil { return err }

// 1) Якщо знаєш longJarId (з URL віджета) — одразу /bank/jar/{id}:
info, _ := cli.ByLongID(ctx, "2zQL6sqnKgTYi7e69271YYWKTXTfMK8g")
fmt.Println(info.Title, info.Amount, "/", info.Goal)

// 2) Якщо є тільки коротке share-посилання send.monobank.ua/<id>:
short, _ := cli.ByShortID(ctx, "clientIdFromShareLink")
// → short.LongJarID можна закешувати й далі ходити в ByLongID

Обидва ендпоінти без авторизації, read-only. Ліміти на send.monobank.ua суворіші — кешуй LongJarID і ходи лише в ByLongID для регулярних оновлень.

Можливості

Базовий клієнт ([root])

• monobank.New(opts...) — *http.Client, HTTPDoer, base URL, retry, auth, slog-логер, request/response hooks, клієнтський rate limiter.
• WithRetry(attempts, base, max) — експонентний бекоф з full jitter, повага до Retry-After, ретраїться лише на 5xx/429.
• WithRateLimiter(RateLimiter) — клієнтський throttle (див. розділ «Rate limits» нижче).
• WithUnsafeRetries(bool) — за замовчуванням POST/PATCH ретраяться ЛИШЕ за наявності заголовка Idempotency-Key (інакше 502 від балансера може створити дублікат операції). Вмикайте, якщо точно знаєте, що ваш endpoint ідемпотентний і дублі прийнятні.
• APIError — типізована помилка з методом, URL, отриманим/очікуваним статусом, розпарсеним ErrorDescription і сирим body. Реалізує errors.Is проти sentinel-помилок (див. нижче).
• WithRequestHook / WithResponseHook — підключіть власні метрики чи трейсинг без замін транспорту. Перезаписують один одного — щоб ДОДАТИ hook поверх існуючого (наприклад, application hook + OpenTelemetry): Client.ChainRequestHook(fn) / ChainResponseHook(fn). Для повноцінного middleware-chain — WithRoundTripper(http.RoundTripper): чистий слот під OpenTelemetry / Datadog / circuit-breaker, що зберігає таймаут і Cookie-jar вбудованого *http.Client.
• WithUserAgent(string) — перевизначає дефолтний User-Agent (go-monobank-sdk/vX.Y.Z (linux; goX.Y.Z)). Mono використовує його у support-кейсах для розрізнення твого сервісу серед інших юзерів SDK. Експортовано monobank.UserAgent() — якщо хочеш зберегти SDK-частину і додати свій префікс.
• Client.Close() error — реалізує io.Closer; зупиняє sweeper фоновим KeyedLimiter. Безпечно викликати на клієнті без лімітера.

Insecure base URL

За замовчуванням WithBaseURL("http://...") для не-loopback-хоста повертає monobank.ErrInsecureBaseURL із першого Do — щоб конфігураційна помилка не призвела до відправлення X-Token у відкритому вигляді. Loopback дозволений завжди — і localhost, і вся 127.0.0.0/8, і ::1 (через net.IP.IsLoopback, не лише дослівні localhost/127.0.0.1). Свідомо обійти для MITM-проксі чи staging-у за VPN-ом:

cli := personal.New(token,
    monobank.WithInsecureBaseURL(true),
    monobank.WithBaseURL("http://staging.example.com"),
)
// Порядок опцій не важить — New робить two-pass apply.

Та сама гарда у installment.New, jar.New, corporate.Client.Auth (для X-Callback URL). Кожен з пакетів має власну WithInsecureBaseURL / AllowInsecureCallback для opt-out.

Token redaction у логах

auth.Personal, business.TokenAuth, acquiring.TokenAuth, auth.CorpAuthMaker, installment.Client реалізують slog.LogValuer і рендеряться як *** у slog-виводі:

slog.Info("auth", "creds", auth.NewPersonal(token))
// → ... creds=auth.Personal{token:***}

Захист від випадкового потрапляння токену/секрету в DEBUG-логи через slog.Info("token", token). Якщо ти логуєш токен явно через slog.String("token", token) — це твоя відповідальність.

SDK також маскує PII у logs: bank.ClientInfo (Name → перша літера+***, WebHookURL шлях → ***), bank.Account (IBAN → country+last4, card masks → ****+last4), а також installment.ClientInfo (ПІБ/ІНН). Усе через LogValue — raw структура поведена нормально, але slog.Info("info", info) не розкриє ПІБ клієнта в log-аґрегаторі.

Rate limits

Mono обмежує більшість endpoint-ів — наприклад, /personal/client-info і /personal/statement/{account}/… дозволяють лише 1 виклик на 60 секунд (на токен/акаунт відповідно). Поза лімітом сервер повертає 429 з Retry-After, який WithRetry поважає автоматично.

При систематичному перевищенні лімітів edge Mono (AWS) може віддати 403 з HTML-тілом (а не JSON errorDescription) і заблокувати IP приблизно на добу — це не те саме, що 403 про права токена. Sentinel ErrForbidden все одно зматчиться за статусом, але APIError.ErrorDescription буде порожнім, а Body міститиме HTML. Не ретрайте такий 403 агресивно. (Поведінка недокументована офіційно, описана community-докою.)

Щоб не вистрілити в 429 з самого початку, додайте WithRateLimiter:

import (
    "time"

    monobank "github.com/OlexiyOdarchuk/go-monobank-sdk"
    "github.com/OlexiyOdarchuk/go-monobank-sdk/personal"
)

lim := monobank.NewLimiter(time.Minute, 1) // 1 запит / 60 с
cli := personal.New(token,
    monobank.WithRateLimiter(lim),
    monobank.WithRetry(3, 0, 0), // на випадок, якщо все одно прилетить 429
)

Wait викликається один раз на логічний Do (а не на кожен retry), тож токен не витрачається повторно. Сигнатура RateLimiter.Wait(ctx) сумісна з *golang.org/x/time/rate.Limiter — підставляйте, якщо вам потрібні дрібніші налаштування.

Для per-account обмежень (виписка по кожному рахунку — окремий ліміт) використовуйте KeyedLimiter:

// idleTTL=10*time.Minute — корзини, до яких не зверталися >10 хв,
// видаляються фоновим sweeper-ом, щоб мапа не росла безкінечно.
klim := monobank.NewKeyedLimiter(time.Minute, 1, 10*time.Minute)
defer klim.Stop()

cli := personal.New(token, monobank.WithRateLimiter(klim))

for _, acc := range info.Accounts {
    ctx := monobank.WithLimiterKey(ctx, acc.AccountID)
    txs, _ := cli.Transactions(ctx, acc.AccountID, from, to)
    // …
}

idleTTL <= 0 вимикає eviction — годиться для коротких CLI-утиліт, але у long-running сервісах задавайте розумне значення (~10× за every).

Структуровані помилки

Усі personal/corporate/business/acquiring API повертають помилки у форматі {"errorDescription": "..."}. SDK розпарсює їх у поле APIError.ErrorDescription:

_, err := cli.ClientInfo(ctx)

// Sentinel-помилки за статусом — для типового control-flow:
switch {
case errors.Is(err, monobank.ErrUnauthorized):    // 401
    log.Println("токен невалідний")
case errors.Is(err, monobank.ErrForbidden):       // 403
    log.Println("токен не має прав на endpoint")
case errors.Is(err, monobank.ErrNotFound):        // 404
    log.Println("сутність не існує")
case errors.Is(err, monobank.ErrTooManyRequests): // 429
    log.Println("rate-limit перевищено")
}

// Повний APIError — коли треба ErrorDescription, raw body тощо:
var apiErr *monobank.APIError
if errors.As(err, &apiErr) {
    log.Printf("HTTP %d: %s", apiErr.StatusCode, apiErr.ErrorDescription)
    // apiErr.Body — оригінальні байти, якщо потрібен власний парсинг.
}

installment має власний формат і власний installment.APIError з полями Message, TraceID. Підпис callback порівнюється або з installment.ErrCallbackBadLength (для wrong-length header), або з installment.ErrCallbackSignatureMismatch (для wrong MAC) — окремі sentinels дозволяють security-телеметрії розрізняти "malformed request" і "forgery attempt".

Інші локальні sentinel-помилки, які варто знати:

• monobank.{ErrEmptyRequest, ErrInvalidURL, ErrInsecureBaseURL}
• auth.ErrEmptyToken — порожній X-Token відхиляється з першого Do.
• business.{ErrIdempotencyKeyRequired, ErrInvalidTimeRange, ErrNilRequest}
• installment.{ErrEmptyOrderID, ErrEmptyDate, ErrEmptyPhone, ErrInvalidPhone, ErrEmptyStoreID, ErrEmptySecret, ErrInsecureBaseURL}
• acquiring.{ErrEmptyID, ErrBadSignature, ErrWebhookStale, ErrWebhookNoTimestamp}
• corporate.{ErrInsecureCallback, ErrInvalidCallback, ErrLogoTooLarge, ErrEmptyAuthMaker, ErrNilRequest}
• jar.{ErrNotFound, ErrEmptyJarID, ErrEmptyClientID, ErrInsecureBaseURL}
• money.ErrOverflow — int64 overflow на Add/Sub/Mul.

bank — публічні endpoint-и

• Rates(ctx) — поточні курси банку.
• Rates.Convert(amount Money, to Code) — конвертує суму через курс банку (через UAH-крос, якщо потрібно).
• ServerKey(ctx) — публічний ECDSA-ключ для верифікації webhook; кешується, рефрешиться автоматично у webhook.Handler.

webhook — серверна сторона

• Verify(pub, body, signatureB64) — приймає і raw r||s, і ASN.1 DER.
• Parse(body) → *Response з типізованими полями (transaction, mcc, amount, balance, opAmount, currencyCode, hold тощо).
• NewHandler(ctx, Options) — готовий http.Handler: верифікація, парсинг, дедуп, авторефреш ключа.
• NewMemoryDeduper(n) — LRU-set на Data.Transaction.ID (id транзакції з payload-у); підставте власну реалізацію Deduper для Redis/SQL — in-memory deduper втрачає стан при рестарті, що дозволяє replay валідно підписаного webhook-у.
• Options.MaxBodyBytes — стеля на розмір тіла запиту (за дефолтом 1 MiB через DefaultMaxBodyBytes). Захист від OOM на публічно доступному webhook-URL.
• Refresh серверного ключа дроссельований до раз на 30 с і об'єднаний через singleflight — атакуючий, що шле POST з випадковим X-Key-Id, не амплифікує DoS на /bank/sync.

acquiring — серверні helper-и та звірка

Поверх самих ендпоінтів еквайринг має батарейки для типових production-задач:

// 1. Готовий http.Handler для acquiring-webhook-ів (аналог webhook.NewHandler,
//    але для еквайрингу): верифікація → freshness → парсинг → dedup → колбек.
//    Dedup за (invoiceId, modifiedDate); ключ авторефрешиться при поганому підписі.
h, _ := acquiring.NewWebhookHandler(ctx, acquiring.WebhookHandlerOptions{
    Keys:   cli,                              // *acquiring.Client (PubKeyProvider)
    Dedup:  acquiring.NewMemoryDeduper(4096), // у проді — persistent (Redis/SQL)
    MaxAge: 15 * time.Minute,                 // anti-replay поверх dedup-у
    OnEvent: func(ctx context.Context, inv *acquiring.InvoiceStatusResponse) error {
        return fulfil(ctx, inv) // помилка → 500 → Mono ретраїть; nil → 200
    },
})
mux.Handle("/mono/webhook", h)

// 2. Reconciliation: добити статус, якщо webhook загубився (єдиний спосіб
//    побачити "expired", по якому webhook не приходить) + diff виписки.
inv, err := cli.PollInvoice(ctx, invoiceID, acquiring.PollOptions{
    Interval: time.Second, Timeout: 2 * time.Minute,
}) // → термінальний стан або acquiring.ErrPollTimeout
stmt, _ := cli.Statement(ctx, from, time.Time{}, "")
rec := acquiring.ReconcileStatement(stmt, local) // local: map[invoiceID]LocalPayment
if !rec.Clean() { /* rec.OnlyRemote / OnlyLocal / Mismatches */ }

// 3. Basket-білдер із валідацією (найчастіша помилка — відсутній code або
//    total != qty*sum). Build звіряє суму кошика з amount інвойсу.
items, err := acquiring.NewBasket().
    AddItem("Кава", "SKU-1", 2, money.UAH(45).Minor, acquiring.WithUnit("шт.")).
    AddItem("Чай", "SKU-2", 1, money.UAH(30).Minor).
    Build(money.UAH(120).Minor)

// 4. Типізовані помилки API ({errCode, errText}) з предикатами.
if _, err := cli.InvoiceStatus(ctx, id); err != nil {
    switch {
    case acquiring.IsNotFound(err):        // невідомий invoiceId
    case acquiring.IsTooManyRequests(err): // back off
    }
    if e, ok := acquiring.AsAPIError(err); ok { log.Println(e.Code, e.Text) }
}

// 5. Subscription lifecycle: класифікатор, що драйвить grace-логіку.
switch acquiring.ClassifyCharge(payment.Status, sub.WalletData.Status) {
case acquiring.HealthChargeFailed: // тимчасово — тримати доступ у grace-вікні
case acquiring.HealthWalletDead:   // токен мертвий — попросити перепривʼязку картки
case acquiring.HealthActive:       // ок
}

• NewWebhookHandler дзеркалить webhook.NewHandler: singleflight + throttle на рефреш ключа, MaxBodyBytes (дефолт 1 MiB), OnError-хук, ack-200 для GET-пінгу підписки.
• Deduper / NewMemoryDeduper(n) — LRU за DedupKey(inv) = invoiceId|modifiedDate.
• InvoiceStatus.IsTerminal() і PollOptions.TreatHoldAsTerminal — для auth-then-capture, де цільовий стан саме hold.
• AsAPIError / Code / Is{BadRequest,Forbidden,NotFound,TooManyRequests,InternalError} — падають на HTTP-статус, якщо тіло без errCode; зберігають monobank-sentinel-и через Unwrap.
• SubscriptionHealth: GraceEligible(), Terminal(), RetainAccess().

money — типізовані суми

m := money.New(12550, currency.UAH)        // 125.50 грн
k := money.UAH(125.50)                      // 12550 копійок — без плутанини *100
p, _ := money.ParseMajor("0.10", currency.UAH) // 10 копійок, ціломатематично (без float-похибки)
fmt.Println(money.UAH(125.50).Major())     // 125.5 — назад у гривні
trip, err := m.Mul(3)                      // → ErrOverflow при MaxInt64*N
if err != nil { return err }
sum, err := m.Add(other)                   // різні валюти → error
                                           // переповнення → ErrOverflow
fmt.Println(trip)                          // "376.50 UAH"
fmt.Println(money.New(1250, currency.JPY)) // "1250 JPY" — 0 знаків після коми

Money серіалізується в JSON як ціле число мінорних одиниць — wire-сумісно з форматом Mono. Money.Major / String поважають currency.Code.Decimals() — JPY/KRW (0 знаків), BHD/JOD/KWD/OMR/TND (3 знаки), UAH/USD/EUR/... (2 знаки) форматуються коректно без жорстко зашитого ділення на 100. Helper currency.Code.MinorPerMajor() повертає 10^Decimals для конвертації decimal-float ↔ int64 minor.

Add/Sub/Mul повертають ErrOverflow при перетині межі int64 — silent wrap на сумах рівня квартальної виписки виключений.

installment.Money — UAH з exact-decimal wire-форматом

installment API унікальна тим, що шле гроші як "total_sum": 2499.99 (decimal-float), а не як int64 minor units. Щоб уникнути float64 precision loss, у пакеті є окремий тип:

amt := installment.NewMoney(2499, 99)     // 2499.99 грн
amt = installment.MoneyFromKopecks(249999)
amt = installment.MoneyFromMajor(2499.99) // round half away from zero

// MarshalJSON емітить `2499.99` (без лапок); UnmarshalJSON парсить через
// рядок, без float64. 0.10, 0.20, 0.30 round-trip точно.

currency, mcc — enum-и

• currency.Code(980).String() → "UAH"; currency.FromAlpha3("USD") → 840.
• currency.UAH.Decimals() → 2; currency.JPY.Decimals() → 0; currency.BHD.Decimals() → 3.
• mcc.Code(5411).Category() → mcc.CategoryGroceries.
• mcc.Code(3500).Category() → mcc.CategoryHotels (3000-3299 авіакомпанії, 3300-3499 оренда авто, 3500-3999 готелі).
• mcc.Code(5912).Category() → mcc.CategoryHealth (аптека-override).

Пагінатори

Усі ендпоінти, де є природний курсор, мають iter.Seq2-обгортки:

• personal.Client.TransactionsRangeIter — виписка за довільний період, ліниво по 31-денних вікнах. Вікна, де більше за ліміт у 500 транзакцій на відповідь, добираються прозоро (Mono віддає максимум 500 рядків і не має offset-курсора — SDK переанкорує to на найстарішу секунду й дедупить за id, як business.StatementAll).
• corporate.Client.TransactionsRangeIter — те саме для corp-API.
• business.Client.ContactsAll / SearchContactsAll — зарплатні контакти.
• business.Client.StatementAll — виписка через DOWN-курсор по часу.
• acquiring.Client.SubscriptionListAll / SubscriptionPaymentsAll — списки підписок та їх платежів.

Усі поважають break (зупиняють подальші HTTP-виклики) і ctx.Done().

monobanktest — фейковий monobank для тестів

srv := monobanktest.NewServer(t)
srv.WithClientInfo(&bank.ClientInfo{ID: "c1", Name: "Тест"})
cli := personal.New("token", srv.Option())

info, _ := cli.ClientInfo(ctx) // повертає те, що зашили вище

Білдери покривають типові сценарії: клієнт-інфо, виписки за період, курси, webhook-події. Конкурентно-безпечні.

Для інтеграційних тестів верифікації acquiring-webhook-ів є генератор підписаного тіла — не треба руками піднімати ECDSA-ключі:

signer := monobanktest.NewAcquiringWebhookSigner(t)        // P-256 keypair
srv := monobanktest.NewServer(t).WithAcquiringPubKey(signer) // віддає /api/merchant/pubkey
cli := acquiring.New("tok", srv.Option())
h, _ := acquiring.NewWebhookHandler(ctx, acquiring.WebhookHandlerOptions{
    Keys: cli, OnEvent: onEvent,
})

body := signer.MarshalBody(t, &acquiring.InvoiceStatusResponse{
    InvoiceID: "p2_x", Status: acquiring.InvoiceSuccess,
})
req := signer.Request(t, "POST", "/webhook", body) // X-Sign проставлено
h.ServeHTTP(rec, req)                              // підпис верифікується справжнім ключем

otelmonobank — OpenTelemetry

import (
    "go.opentelemetry.io/otel"
    "github.com/OlexiyOdarchuk/go-monobank-sdk/otelmonobank"
    "github.com/OlexiyOdarchuk/go-monobank-sdk/personal"
)

cli := personal.New(token, otelmonobank.WithTracer(otel.Tracer("my-app")))

Кожен HTTP-виклик (включно з ретраями) стає окремим span-ом із атрибутами http.method, http.url, http.status_code. Винесено в окремий sub-module, щоб OTel не тягнувся у проєкти, які його не використовують.

Приклади

Робочі програми в examples/:

Каталог	Що показує
examples/personal	ClientInfo, виписка за 7 днів, MCC-категорії
examples/corporate	ECDSA-авторизація, очікування підтвердження клієнта
examples/business	Список рахунків + виписка з пагінацією
examples/acquiring	Створення інвойсу, поллінг до фінального стану
examples/installment	Sandbox-флоу ПЧ: create → state → confirm
examples/jar	Lookup банки за longJarId та коротким clientId
examples/webhook	HTTP-сервер з ECDSA-верифікацією і дедупом

Кожен — go run ./examples/<name> з відповідною env-змінною (MONO_TOKEN, MONO_ACQUIRING_TOKEN, CHAST_STORE_ID+CHAST_SECRET, LONG_JAR_ID тощо).

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

Повна godoc-документація на кожен пакет, тип, функцію: https://pkg.go.dev/github.com/OlexiyOdarchuk/go-monobank-sdk.

Wire-ідентифікатори (HTTP-заголовки, JSON-ключі) лишаються англійською — як це бачить власне API.

• CHANGELOG.md — історія релізів (Keep a Changelog).
• SECURITY.md — як приватно повідомити про вразливість.
• CONTRIBUTING.md — як долучитися PR-ом.

Сумісність

• Go: 1.25+ (iter.Seq2-пагінатори; otelmonobank пінить 1.25 через OpenTelemetry).
• Перевірено на 1.25.x – 1.26.x у CI.
• Race-clean — go test -race ./... проходить.

Зв'язок з vtopc/go-monobank

Upstream свідомо мінімалістичний: тонкі обгортки лише для Personal та Corporate Open API, без серверних helper-ів, без enum-ів, без corp-api чи еквайрингу. Цей SDK залишає кожен endpoint upstream-у і додає решту. Хочете «батерейки в комплекті» — беріть це; хочете мінімум — беріть upstream.

MIT-ліцензія несе авторські права upstream-у далі (див. LICENSE).

Ліцензія

MIT — див. LICENSE.

Documentation

Overview

Package monobank is the base HTTP transport for every monobank API surface. It exposes the Client type, the Option type, and a set of constructors and options (New, WithHTTPClient, WithHTTPDoer, WithBaseURL, WithRetry, WithAuth, WithRateLimiter, WithUnsafeRetries, WithLogger, WithRequestHook, WithResponseHook), plus the shared error type APIError and sentinel errors keyed by HTTP status (ErrUnauthorized, ErrForbidden, ErrNotFound, ErrTooManyRequests).

Throttling: NewLimiter is a simple token bucket; NewKeyedLimiter gives per-key buckets (for example, per accountID) with optional TTL eviction; WithLimiterKey propagates the key through context.Context.

Application code usually does not pull in this package directly, but rather the topical sub-packages built on top of it:

• github.com/OlexiyOdarchuk/go-monobank-sdk/auth — the Authorizer interface plus implementations for the personal token and the corporate ECDSA signature.
• github.com/OlexiyOdarchuk/go-monobank-sdk/bank — the bank's public endpoints (currency rates, server key) and the shared data model (ClientInfo, Account, Jar, Transaction).
• github.com/OlexiyOdarchuk/go-monobank-sdk/personal — Personal Open API (authorization via X-Token).
• github.com/OlexiyOdarchuk/go-monobank-sdk/corporate — Corporate Open API (ECDSA signatures), including monoKEP.
• github.com/OlexiyOdarchuk/go-monobank-sdk/business — corp-api (legal entities): payroll contacts and rosters, payments, payslips.
• github.com/OlexiyOdarchuk/go-monobank-sdk/acquiring — acquiring (/api/merchant/*): invoices, holds, QR cash desks, tokenized cards.
• github.com/OlexiyOdarchuk/go-monobank-sdk/webhook — the server side: signature verification, payload parser, a ready http.Handler, and an in-memory deduper.
• github.com/OlexiyOdarchuk/go-monobank-sdk/mcc — a typed ISO 18245 MCC enum with grouping into categories ([mcc.Code.Category]).
• github.com/OlexiyOdarchuk/go-monobank-sdk/currency — a typed ISO 4217 numeric currency code with its alpha-3 name.

The base client (Client) is already embedded in each sub-package: you don't construct it separately for routine code.

Index

• Variables
• func UserAgent() string
• func WithLimiterKey(ctx context.Context, key string) context.Context
• type APIError
  • func (e *APIError) Error() string
  • func (e *APIError) Is(target error) bool
• type Client
  • func New(opts ...Option) Client
  • func (c *Client) ChainRequestHook(fn func(*http.Request))
  • func (c *Client) ChainResponseHook(fn func(*http.Response, error))
  • func (c *Client) Close() error
  • func (c Client) Do(req *http.Request, v any, expectedStatusCodes ...int) error
  • func (c *Client) SetBaseURL(uri string)
• type HTTPDoer
• type KeyedLimiter
  • func NewKeyedLimiter(every time.Duration, burst int, idleTTL time.Duration) *KeyedLimiter
  • func (k *KeyedLimiter) Stop()
  • func (k *KeyedLimiter) Wait(ctx context.Context) error
  • func (k *KeyedLimiter) WaitKey(ctx context.Context, key string) error
• type Limiter
  • func NewLimiter(every time.Duration, burst int) *Limiter
  • func (l *Limiter) Wait(ctx context.Context) error
• type Option
  • func WithAuth(a auth.Authorizer) Option
  • func WithBaseURL(uri string) Option
  • func WithHTTPClient(httpClient *http.Client) Option
  • func WithHTTPDoer(d HTTPDoer) Option
  • func WithInsecureBaseURL(allow bool) Option
  • func WithLogger(l *slog.Logger) Option
  • func WithRateLimiter(l RateLimiter) Option
  • func WithRequestHook(fn func(*http.Request)) Option
  • func WithResponseHook(fn func(*http.Response, error)) Option
  • func WithRetry(attempts int, baseDelay, maxDelay time.Duration) Option
  • func WithRoundTripper(rt http.RoundTripper) Option
  • func WithUnsafeRetries(enabled bool) Option
  • func WithUserAgent(ua string) Option
• type RateLimiter

Examples

• APIError
• NewKeyedLimiter
• NewLimiter
• WithUnsafeRetries

Variables

var (
	// ErrEmptyRequest indicates that [Client.Do] received a nil request.
	ErrEmptyRequest = errors.New("empty request")
	// ErrInvalidURL indicates that the client's baseURL is not valid
	// (usually never happens because [New] always sets a default; it
	// can occur after [Client.SetBaseURL] with an invalid string).
	ErrInvalidURL = errors.New("invalid URL")
	// ErrInsecureBaseURL indicates that [WithBaseURL] received a
	// non-https URL for a non-loopback host. This guards against
	// accidentally sending tokens in cleartext. For tests via httptest
	// or a custom localhost proxy, use a loopback host or opt in via
	// [WithInsecureBaseURL].
	ErrInsecureBaseURL = errors.New("base URL must be https for non-loopback hosts")
)

Client-level errors.

var (
	// ErrUnauthorized is HTTP 401: the token is invalid or expired.
	ErrUnauthorized = errors.New("monobank: unauthorized (401)")
	// ErrForbidden is HTTP 403: the token lacks rights for the endpoint.
	ErrForbidden = errors.New("monobank: forbidden (403)")
	// ErrNotFound is HTTP 404: endpoint or entity does not exist.
	ErrNotFound = errors.New("monobank: not found (404)")
	// ErrTooManyRequests is HTTP 429: rate limit exceeded.
	ErrTooManyRequests = errors.New("monobank: too many requests (429)")
)

Sentinel errors for the common HTTP statuses. APIError.Is implements errors.Is against them, giving convenient detection:

if errors.Is(err, monobank.ErrUnauthorized) { /* token expired */ }
if errors.Is(err, monobank.ErrTooManyRequests) { /* back off */ }

On top of the sentinels, the full APIError is still reachable via errors.As (status code, ErrorDescription, raw body).

Functions

func UserAgent

func UserAgent() string

UserAgent returns the User-Agent the SDK uses by default. Exported so you can compose your own value for WithUserAgent without losing the SDK portion:

cli := personal.New(token,
    monobank.WithUserAgent("myapp/1.2.3 "+monobank.UserAgent()),
)

func WithLimiterKey

func WithLimiterKey(ctx context.Context, key string) context.Context

WithLimiterKey returns a copy of ctx carrying key, which KeyedLimiter uses to pick the matching per-key bucket. If the key is absent from the context, KeyedLimiter treats the request as "" (the shared default bucket).

ctx = monobank.WithLimiterKey(ctx, accountID)
cli.Transactions(ctx, accountID, from, to)

Types

type APIError

type APIError struct {
	Method              string
	URL                 string
	StatusCode          int
	ExpectedStatusCodes []int
	// ErrorDescription is the value of the errorDescription field from
	// the JSON body of the Mono response, when the body could be
	// parsed; otherwise empty.
	ErrorDescription string
	Body             []byte
}

APIError is returned when a monobank HTTP response does not match any of the statuses the caller expected. It captures the method, full URL, received and expected status codes, plus the first 256 characters of the body for diagnostics.

If the response body is JSON of the shape {"errorDescription": "..."} (the standard Mono error format for the personal/corporate/business/ acquiring APIs), the APIError.ErrorDescription field holds the parsed message; otherwise it is empty and the original bytes remain in APIError.Body.

Example

Розпізнавання конкретного типу помилки і доступ до errorDescription.

package main

import (
	"context"
	"errors"
	"fmt"
	"net/http"
	"os"

	monobank "github.com/OlexiyOdarchuk/go-monobank-sdk"
	"github.com/OlexiyOdarchuk/go-monobank-sdk/personal"
)

func main() {
	cli := personal.New(os.Getenv("MONO_TOKEN"))

	_, err := cli.ClientInfo(context.Background())
	var apiErr *monobank.APIError
	if errors.As(err, &apiErr) {
		switch apiErr.StatusCode {
		case http.StatusForbidden:
			fmt.Printf("token rejected: %s\n", apiErr.ErrorDescription)
		case http.StatusTooManyRequests:
			fmt.Println("rate limited — wait and retry")
		default:
			fmt.Printf("HTTP %d: %s\n", apiErr.StatusCode, apiErr.ErrorDescription)
		}
	}
}

func (*APIError) Error

func (e *APIError) Error() string

func (*APIError) Is

func (e *APIError) Is(target error) bool

Is enables errors.Is(apiErr, monobank.ErrUnauthorized) and similar checks for the common HTTP statuses. Other status codes map only to APIError itself — use errors.As for full access.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the base HTTP transport for every monobank surface. Each sub-package (bank, personal, corporate, business, acquiring) composes Client with an auth.Authorizer from the auth package and the base URL tailored to its API. Routine code does not usually construct this type directly — use the sub-package factories ([personal.New], [bank.New] etc.).

func New

func New(opts ...Option) Client

New returns the base Client assembled from the supplied options. Without WithAuth the client uses auth.Public (no-op) — fine for the public bank endpoints via the bank sub-package, but not for personal, corporate, business or acquiring (which require real authorization; they normally call New themselves, adding their own auth.Authorizer).

c := monobank.New(
    monobank.WithHTTPClient(myHTTP),
    monobank.WithRetry(5, 0, 0),
)

Options are applied in two passes so WithInsecureBaseURL takes effect regardless of where it appears in the list. Each option runs twice — they are expected to be pure setters; if you wrote a custom Option with side effects, scope them to a single pass.

func (*Client) ChainRequestHook

func (c *Client) ChainRequestHook(fn func(*http.Request))

ChainRequestHook composes fn on top of the client's existing request hook so the previous hook still fires (first), then fn. If no hook was installed before, fn becomes the sole hook.

Used by integrations that want to add their own request-side behavior (OpenTelemetry span start, custom headers) without stomping on a hook the application installed via WithRequestHook. nil is ignored.

func (*Client) ChainResponseHook

func (c *Client) ChainResponseHook(fn func(*http.Response, error))

ChainResponseHook composes fn on top of the client's existing response hook. Existing hook runs first, then fn. nil is ignored.

func (*Client) Close

func (c *Client) Close() error

Close stops the background resources attached to the client (currently the sweeper goroutine of KeyedLimiter, when such a limiter was passed via WithRateLimiter). Safe to call on a client that does not need Close (returns nil).

Implements io.Closer, so the standard defer pattern just works:

cli := personal.New(token, monobank.WithRateLimiter(klim))
defer cli.Close()

Without Close, the sweeper goroutine of KeyedLimiter stays alive until the process exits (a leak in tests, but normal in long-running services with a single global client).

Pointer receiver for consistency with Client.SetBaseURL / ChainRequestHook / ChainResponseHook. Existing callers using a value receiver via sub-package wrappers still work — Go addresses values automatically when needed.

func (Client) Do

func (c Client) Do(req *http.Request, v any, expectedStatusCodes ...int) error

Do executes req against c.baseURL and decodes the response into v. The number of expected status codes is arbitrary; the default is http.StatusOK. If the response has a different code, returns *APIError.

The type of v selects the decoding mode:

• nil — the body is simply read and discarded;
• *[]byte — the raw body bytes are written into v;
• io.Writer — the body is copied to the Writer;
• otherwise — decoded as JSON into v.

Transient failures (5xx, 429) are retried per WithRetry (honoring Retry-After). Context cancellation exits immediately.

The method is exported so sub-packages (bank, personal, corporate, business, acquiring) share one HTTP plumbing (retry, base-URL resolution, error mapping) instead of reimplementing it. Pass an *http.Request with a path-only URL — it is resolved against the configured base URL.

func (*Client) SetBaseURL

func (c *Client) SetBaseURL(uri string)

SetBaseURL overrides the base URL of an already-constructed client. On a parse failure it records the error in c.optErr (which surfaces from the very first Client.Do) and leaves the previous value in place. For routine code use WithBaseURL when constructing through New; this method exists for sub-packages that assemble Client incrementally.

Previously SetBaseURL silently kept the old value — a fat-finger in the URL would mean every request went to the default production host, which is the worst kind of "works on my machine" bug for staging configs.

type HTTPDoer

type HTTPDoer interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPDoer is the minimal subset of *http.Client that Client depends on. Any transport that implements this interface (the standard client, a custom round-tripper, a test fake) plugs in via WithHTTPDoer.

type KeyedLimiter

type KeyedLimiter struct {
	// contains filtered or unexported fields
}

KeyedLimiter lazily creates a separate Limiter per key — typically the accountID, because Mono limits /personal/statement/{account}/… independently per account. Implements RateLimiter: the key is taken from the context via WithLimiterKey.

// idleTTL=10*time.Minute — buckets that have not been used for
// 10 min are removed by a background sweeper so the map does
// not grow without bound in long-running processes.
klim := monobank.NewKeyedLimiter(time.Minute, 1, 10*time.Minute)
defer klim.Stop()

cli := personal.New(token, monobank.WithRateLimiter(klim))

for _, acc := range info.Accounts {
    ctx := monobank.WithLimiterKey(ctx, acc.ID)
    txs, err := cli.Transactions(ctx, acc.ID, from, to)
    // …
}

Safe for concurrent use.

func NewKeyedLimiter

func NewKeyedLimiter(every time.Duration, burst int, idleTTL time.Duration) *KeyedLimiter

NewKeyedLimiter returns a limiter that, for each unique key, creates its own bucket with the every / burst parameters (as in NewLimiter).

idleTTL > 0 starts a background sweeper that removes buckets not touched for longer than idleTTL (guards against memory leaks with a large number of unique keys). idleTTL <= 0 disables eviction; fine for short-lived CLI utilities, but long-running processes should always pass a reasonable value (for example, 10× every).

Always call KeyedLimiter.Stop on shutdown (via defer right after construction) to stop the sweeper goroutine.

Example

Per-account ліміт виписки: на кожен accountID — окрема корзина. idleTTL=10*time.Minute видаляє корзини, до яких не зверталися довше 10 хв, щоб мапа не росла на сервісах із багатьма accountID.

package main

import (
	"context"
	"log"
	"os"
	"time"

	monobank "github.com/OlexiyOdarchuk/go-monobank-sdk"
	"github.com/OlexiyOdarchuk/go-monobank-sdk/personal"
)

func main() {
	klim := monobank.NewKeyedLimiter(time.Minute, 1, 10*time.Minute)
	defer klim.Stop()

	cli := personal.New(os.Getenv("MONO_TOKEN"),
		monobank.WithRateLimiter(klim),
	)

	to := time.Now()
	from := to.Add(-time.Hour)
	for _, acc := range []string{"acc-1", "acc-2"} {
		ctx := monobank.WithLimiterKey(context.Background(), acc)
		if _, err := cli.Transactions(ctx, acc, from, to); err != nil {
			log.Printf("%s: %v", acc, err)
		}
	}
}

func (*KeyedLimiter) Stop

func (k *KeyedLimiter) Stop()

Stop stops the background sweeper. Safe to call multiple times, and on a limiter without a sweeper (idleTTL <= 0) — in that case it is a no-op. After Stop the limiter still serves Wait/WaitKey calls correctly; the buckets are simply no longer evicted automatically.

func (*KeyedLimiter) Wait

func (k *KeyedLimiter) Wait(ctx context.Context) error

Wait implements RateLimiter. It extracts the key from the context via WithLimiterKey; if no key is present, it uses the shared bucket with the "" key.

func (*KeyedLimiter) WaitKey

func (k *KeyedLimiter) WaitKey(ctx context.Context, key string) error

WaitKey blocks until a token is available in the bucket for key. Handy when the caller does not want to thread the key through the context.

type Limiter

type Limiter struct {
	// contains filtered or unexported fields
}

Limiter is a simple token bucket. The bucket refills at one token every every; up to burst tokens are stored at once. Safe for concurrent use.

Mono's default limits:

• /personal/client-info — 1 call per 60 s (every=time.Minute, burst=1)
• /personal/statement/{account}/… — 1 call per account per 60 s

For per-account limits, create a separate Limiter (and a separate client) for each account, or implement a custom RateLimiter.

func NewLimiter

func NewLimiter(every time.Duration, burst int) *Limiter

NewLimiter returns a limiter that allows one request every every with short bursts up to burst. every <= 0 means "no limit" — Wait always returns immediately. burst < 1 is normalized to 1.

// 1 request per 60 seconds (as in /personal/client-info)
lim := monobank.NewLimiter(time.Minute, 1)
cli := personal.New(token, monobank.WithRateLimiter(lim))

Example

Token-bucket: 1 запит на 60 секунд (типовий ліміт /personal/client-info).

package main

import (
	"context"
	"log"
	"os"
	"time"

	monobank "github.com/OlexiyOdarchuk/go-monobank-sdk"
	"github.com/OlexiyOdarchuk/go-monobank-sdk/personal"
)

func main() {
	lim := monobank.NewLimiter(time.Minute, 1)

	cli := personal.New(os.Getenv("MONO_TOKEN"),
		monobank.WithRateLimiter(lim),
	)

	if _, err := cli.ClientInfo(context.Background()); err != nil {
		log.Fatal(err)
	}
}

func (*Limiter) Wait

func (l *Limiter) Wait(ctx context.Context) error

Wait blocks until at least one token is available or the context is canceled.

type Option

type Option func(*Client)

Option configures Client. Pass it to New (and likewise to sub-package factories — [personal.New], [bank.New] etc., which forward options to New). Additive design: new options are added without breaking existing call sites.

func WithAuth

func WithAuth(a auth.Authorizer) Option

WithAuth attaches an auth.Authorizer to the client. Sub-packages (personal, corporate, business, acquiring) use it to plug in their authorization scheme (X-Token, ECDSA signature, etc.). nil is ignored — the default stays auth.Public (no authorization).

func WithBaseURL

func WithBaseURL(uri string) Option

WithBaseURL overrides the default base URL (https://api.monobank.ua). Handy for testing against httptest.Server, a recorded proxy, or alternative hosts (corp-api.monobank.ua is applied automatically inside [business.New], no need to set it here).

SECURITY: if uri uses a non-https scheme AND the host is not a loopback, the client remembers ErrInsecureBaseURL and returns it from the very first Client.Do. Loopback covers the literal hostname "localhost" plus any IP for which net.IP.IsLoopback is true (127.0.0.0/8 and ::1 — not just 127.0.0.1). This guards against accidentally deploying with a staging config that sends X-Token in cleartext. Opt out deliberately via WithInsecureBaseURL.

Option order does NOT matter: New applies WithInsecureBaseURL first in a separate pass before evaluating the base-URL guard.

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient sets a custom *http.Client (handy for timeouts, custom transports, proxies). nil or omission falls back to the standard &http.Client{} with no timeout.

func WithHTTPDoer

func WithHTTPDoer(d HTTPDoer) Option

WithHTTPDoer accepts any HTTPDoer. Useful for plugging in middleware (circuit breakers, custom transports, test fakes). nil is ignored.

func WithInsecureBaseURL

func WithInsecureBaseURL(allow bool) Option

WithInsecureBaseURL deliberately allows an http:// URL on a non-loopback host in WithBaseURL. Useful for a recorded MITM proxy used for debugging (mitmproxy, burp) or staging setups behind a VPN where https is overkill. The default is false; turn it on only if you understand that the token will travel in cleartext and that is acceptable on your network.

Option order is irrelevant — New resolves WithInsecureBaseURL in a dedicated pass before any other option runs.

func WithLogger

func WithLogger(l *slog.Logger) Option

WithLogger attaches a *slog.Logger to the client. When set, the SDK logs:

• Debug "monobank: sending request" — before every HTTP call (method, url).
• Debug "monobank: http response" — successful response (method, url, status, duration).
• Warn "monobank: http error" — transport failure (method, url, duration, err).

The logger fires per attempt — retries produce multiple records. nil is ignored. Default: do not log.

CAUTION (PII): at Debug level the full request URL goes into the log, including the accountID path segment for /personal/statement/{acc}/... Do not enable Debug in production, or wire up a handler-side filter in your own slog.Handler (banking secrecy). Info/Warn are safe.

cli := personal.New(token, monobank.WithLogger(slog.Default()))

func WithRateLimiter

func WithRateLimiter(l RateLimiter) Option

WithRateLimiter sets a client-side throttle. RateLimiter.Wait is called on EVERY attempt, including each retry — so a burst of retries after a 502/429 cannot blow past the limiter the moment the upstream recovers. nil is ignored.

Mono has strict limits (for example, /personal/client-info is one call per 60 s); without a limiter the SDK relies solely on server-side 429 plus WithRetry backoff. A local limiter helps avoid getting 429-ed right away.

lim := monobank.NewLimiter(time.Minute, 1)
cli := personal.New(token, monobank.WithRateLimiter(lim))

You can drop in any *golang.org/x/time/rate.Limiter — its Wait(ctx) signature matches RateLimiter.

func WithRequestHook

func WithRequestHook(fn func(*http.Request)) Option

WithRequestHook installs a callback invoked before every HTTP request (including each retry). The request has been resolved to its full URL and has the authorization headers set — the hook may add its own (for example, OpenTelemetry trace context, X-Correlation-Id). nil is ignored.

cli := personal.New(token, monobank.WithRequestHook(func(r *http.Request) {
    r.Header.Set("X-Correlation-Id", uuid.NewString())
}))

func WithResponseHook

func WithResponseHook(fn func(*http.Response, error)) Option

WithResponseHook installs a callback invoked after every HTTP response (success and failure). It runs IMMEDIATELY after http.Doer.Do, before parsing and before the expected-status check. resp may be nil (if err != nil); err may be nil (when everything is fine). Useful for metrics (per-attempt latency, error counts). nil is ignored.

cli := personal.New(token, monobank.WithResponseHook(func(r *http.Response, err error) {
    if r != nil {
        metrics.Counter("mono.responses", "status", strconv.Itoa(r.StatusCode)).Inc()
    }
}))

func WithRetry

func WithRetry(attempts int, baseDelay, maxDelay time.Duration) Option

WithRetry enables automatic retry for transient failures (5xx and 429). Backoff is exponential with full jitter; Retry-After from the response is honored when present.

attempts == 0 inherits the defaults (4 attempts, base 500ms, max 30s). attempts <= 1 explicitly disables retry. Non-positive baseDelay / maxDelay inherit the defaults.

Only transient failures (5xx, 429) are retried; 4xx errors come back as APIError without a retry, because they are genuine client-side errors.

func WithRoundTripper

func WithRoundTripper(rt http.RoundTripper) Option

WithRoundTripper installs a custom http.RoundTripper without touching the rest of the embedded *http.Client settings (timeout, Cookie jar, redirect policy). This is the standard middleware slot: OpenTelemetry / Datadog / Prometheus / custom auth-refresh or circuit-breaker logic that does not require rewriting the whole HTTP stack.

type loggingRT struct{ next http.RoundTripper }
func (l loggingRT) RoundTrip(r *http.Request) (*http.Response, error) {
    log.Println("→", r.Method, r.URL.Path)
    return l.next.RoundTrip(r)
}

cli := personal.New(token, monobank.WithRoundTripper(
    loggingRT{next: http.DefaultTransport},
))

Compose by ordinary wrapping: build the middleware chain from the outside in, or via a helper function. nil is ignored.

Option order: WithRoundTripper MUST come AFTER WithHTTPClient (otherwise WithHTTPClient overwrites the transport). If you pass your own http.Client that already has the right Transport, use WithHTTPClient alone, without WithRoundTripper.

func WithUnsafeRetries

func WithUnsafeRetries(enabled bool) Option

WithUnsafeRetries enables automatic retries for POST/PATCH without an Idempotency-Key header. By default such methods are not retried, because a 502/504 from the load balancer can arrive AFTER upstream has already processed the request — a retry then creates a duplicate operation (for example, two invoices via [acquiring.Client.CreateInvoice]).

Mono accepts Idempotency-Key for every mutating endpoint where it makes sense (see [business.NewIdempotencyKey], which is set automatically in [business.Client.PreparePayment] / [business.Client.CreateSalaryRegistry]). For the remaining POST methods, if you are sure the endpoint is idempotent on Mono's side or are happy to live with duplicates, set WithUnsafeRetries(true).

Example

За замовчуванням POST/PATCH без Idempotency-Key НЕ ретраяться, щоб 502 від балансера не створив дублікат операції. WithUnsafeRetries явно вмикає ретрай — лише коли впевнений, що endpoint ідемпотентний.

package main

import (
	"os"

	monobank "github.com/OlexiyOdarchuk/go-monobank-sdk"
	"github.com/OlexiyOdarchuk/go-monobank-sdk/personal"
)

func main() {
	cli := personal.New(os.Getenv("MONO_TOKEN"),
		monobank.WithUnsafeRetries(true),
	)
	_ = cli
}

func WithUserAgent

func WithUserAgent(ua string) Option

WithUserAgent overrides the User-Agent the SDK sets on every request (default is UserAgent). Helpful so Mono support can tell your service apart from other SDK users:

cli := personal.New(token,
    monobank.WithUserAgent("acme-receipts/2.1.0 "+monobank.UserAgent()),
)

An empty string is ignored (the SDK default is kept).

type RateLimiter

type RateLimiter interface {
	Wait(ctx context.Context) error
}

RateLimiter throttles outbound requests. Implementations must be safe for concurrent use. [Wait] blocks until a token is available or ctx is canceled.

The signature matches *golang.org/x/time/rate.Limiter.Wait — any existing limiter can be dropped in without a wrapper.