OpenDinar API

OpenDinar is the open banking infrastructure for Serbia. It lets your app connect to Serbian bank accounts and read balances, transactions, identity data, and recurring payments — through a single, consistent API.

Instead of building separate integrations with Raiffeisen, Erste, AIK, and others, you integrate once with OpenDinar and get access to all supported banks.

Base URL

https://api.opendinar.com

Supported banks

Live bank connections open once the NBS licence is granted. Until then all six banks report status: "sandbox" from GET /banks.

Authentication

All banking API requests must include your API key in the Authorization header as a Bearer token.

# Every protected request needs this header
Authorization: Bearer od_test_sk_9x2mABC123sandbox

API keys are prefixed to indicate their type:

API keys are issued through the Developer Dashboard — sign-ups open at launch.

Quickstart

Get from zero to fetching transactions in 5 steps.

1. Get your API key

Developer sign-ups open at launch — join the waitlist to be notified. Once sign-ups open: register, verify your email, and your sandbox key will be waiting in the dashboard.

2. Add the Link Widget to your page

<script src="https://api.opendinar.com/v1/opendinar.js"></script>

3. Let a user connect their bank

First create a short-lived link_token from your backend, so your real API key never appears in browser code:

# On your backend
POST /link/token/create
Authorization: Bearer od_test_sk_your_key
Content-Type: application/json

{ "user_id": "user_123" }

# Response — pass link_token to your frontend
{ "link_token": "lt_abc123...", "expires_in": 1800 }

Then initialise the widget with it:

const handler = OpenDinar.create({
  linkToken: 'lt_abc123...',          // from step above
  userId:    'user_123',             // your internal user ID
  appName:   'Your App Name',        // shown to the user in the widget
  onSuccess: (publicToken, meta) => {
    // Send publicToken to your backend and exchange it
    console.log('Connected:', meta.bank_name);
  },
  onExit: () => console.log('User closed the widget'),
});

document.getElementById('connect-btn').onclick = () => handler.open();

4. Exchange the public token on your backend

# Exchange the one-time public_token for a permanent connection_id
POST /connect/exchange
Authorization: Bearer od_test_sk_your_key
Content-Type: application/json

{ "public_token": "public_abc123..." }

# Response
{
  "connection_id": "conn_xyz...",   // store this in your database
  "bank_id": "raiffeisen",
  "status": "active"
}

5. Fetch accounts and transactions

# List accounts — returns the account IDs for this connection
GET /accounts
Authorization: Bearer od_test_sk_your_key

# Get transactions for an account (use an id from the response above)
GET /accounts/acc_1a2b3c4d5e6f7a8b/transactions?limit=50
Authorization: Bearer od_test_sk_your_key

Environments

Versioning

Every banking endpoint also works under a /v1 prefix — GET /v1/accounts behaves exactly like GET /accounts. Every response carries an X-OpenDinar-Version: v1 header.

GET /v1/accounts
Authorization: Bearer od_test_sk_your_key

# Response header
X-OpenDinar-Version: v1

Rate Limits

Every rate-limited response includes standard RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers so you can pace your requests. Exceeding a limit returns HTTP 429 with error code RATE_LIMIT_EXCEEDED.

Error Handling

Every error response has the same shape — always check error_code rather than HTTP status codes for handling logic.

{
  "error_type":    "AUTH_ERROR",
  "error_code":    "INVALID_API_KEY",
  "error_message": "The API key provided is not valid.",
  "docs":          "https://api.opendinar.com/docs/#error-codes",
  "request_id":    "a3f9c2d1-..."
}

Error types

See the full error code reference below.

Link Widget

The Link Widget is a drop-in JavaScript UI that handles the entire bank connection experience. It shows a list of supported banks, opens a secure authorization popup, and returns a public_token when the user connects successfully.

You never handle bank credentials or OAuth flows yourself — the widget handles everything.

Installation

Include the widget script on any page where users need to connect a bank:

<script src="https://api.opendinar.com/v1/opendinar.js"></script>

The script is lightweight (~30 KB), self-contained, and has no dependencies.

Configuration

Create a handler using OpenDinar.create(config):

const handler = OpenDinar.create({
  linkToken: 'lt_...',              // recommended — from POST /link/token/create
  userId:    'user_123',            // optional — your internal user ID
  appName:   'Your App Name',       // optional — shown to the user
  onSuccess: (publicToken, meta) => { },  // called on successful connection
  onExit:    () => { },                   // called when user closes widget
});

Config options

The widget's intro screen also shows a privacy consent checkbox — the user must tick "I have read and agree to the Privacy Policy" before they can continue. This is built in; no configuration needed.

Handler methods

Token Flow

The connection process uses a 3-step token exchange — the same pattern as Plaid and Stripe Connect.

1. Widget calls POST /connect — creates a 10-minute session_token and opens the bank's authorization page
2. User authorizes — bank confirms access and the session is marked authorized with a 5-minute public_token
3. Your backend calls POST /connect/exchange — trades the one-time public_token for a permanent connection_id

Banks

These endpoints are public — no API key required.

List banks

Query parameters

Get one bank

# Example response
{
  "id": "raiffeisen",
  "name": "Raiffeisen Banka",
  "country": "RS",
  "bic": "RZBSRSBG",
  "status": "sandbox",
  "color": "#FFE500",
  "market_share_pct": 11.19,
  "feat_accounts": 1,
  "feat_transactions": 1,
  "feat_balance": 1,
  "feat_identity": 1
}

Connect

These endpoints power the 3-step bank authorization flow used by the Link Widget.

Create link token

Creates a short-lived lt_… token to initialise the Link Widget with, so your real API key never appears in frontend code. Valid for 30 minutes.

Request body

# Response
{
  "object":     "link_token",
  "link_token": "lt_abc123...",
  "expires_in": 1800,
  "expires_at": "2026-08-25T10:30:00.000Z"
}

Start authorization

Creates a 10-minute session and returns a URL to open for bank authorization.

Request body

Check status

Poll this endpoint to check if the user has completed authorization. When status is authorized, a public_token is included.

# Pending response
{ "status": "pending" }

# Authorized response
{
  "status": "authorized",
  "public_token": "public_abc123...",
  "expires_in": 300
}

Exchange public token

Exchanges the one-time public_token for a permanent connection_id. Must be called from your backend.

Request body

Connections

A connection is the permanent authorized link between a user and a bank. Store the connection_id in your database — it's what ties a user to their bank data.

List connections

Returns all connections made through your API key, including each connection's consent status:

{
  "connection_id":     "conn_abc123...",
  "bank_id":           "raiffeisen",
  "user_id":           "user_123",
  "status":            "active",        // active | expired | revoked
  "connected_at":      "2026-08-01T09:00:00.000Z",
  "expires_at":        "2026-10-30T09:00:00.000Z",
  "days_until_expiry": 66
}

Revoke a connection

Permanently revokes a user's bank connection and erases its personal data — the connection's accounts, transactions, and consent record are deleted. Use this for GDPR/ZZPL "right to erasure" requests. The user will need to re-authorize to reconnect.

Keys created through the Developer Dashboard have the connections:write scope. The shared public demo keys are read-only and cannot delete anything — calling this with one returns 403 INSUFFICIENT_PERMISSIONS.

Export a connection's data (right of access)

Returns everything OpenDinar holds for one connection — accounts, transactions, and the consent record. Call this on behalf of your end user when they make a GDPR/ZZPL "right of access" request.

Consent & Expiry

A user's consent to share their bank data does not last forever. Every connection expires 90 days after it is created — the standard open-banking consent period.

• Data requests on an expired connection return HTTP 401 with error code CONSENT_EXPIRED and hints on how to reconnect.
• Re-connecting the same user to the same bank renews the existing connection in place — the connection_id stays the same, no duplicate is created.
• A daily scan fires the ITEM.CONNECTION_EXPIRING webhook when a connection is within 7 days of expiry, and ITEM.CONNECTION_EXPIRED once it lapses — so your app can prompt the user to reconnect in time.

# Request on an expired connection
GET /accounts/acc_1a2b.../balance

# 401 response
{
  "error_type":    "ITEM_ERROR",
  "error_code":    "CONSENT_EXPIRED",
  "error_message": "The user's consent for this bank connection has expired...",
  "docs":          "https://api.opendinar.com/docs/#error-codes",
  "request_id":    "a3f9c2d1-..."
}

Check expires_at and days_until_expiry on GET /connections to see where each connection stands.

Accounts

List accounts

Returns all bank accounts across all active connections for this API key. Accounts are isolated — you only see accounts connected through your key.

Query parameters

Get balance

{
  "object": "balance",
  "account_id": "acc_1a2b3c4d5e6f7a8b",
  "currency": "RSD",
  "balance": 185420.50,
  "available_balance": 183200.00,
  "retrieved_at": "2026-04-04T10:30:00.000Z"
}

Get identity

Returns the account holder's personal details. Only available if the bank supports identity data (feat_identity = true). Currently supported by Raiffeisen.

Get auth (account verification)

Returns the account's verified IBAN, BIC, and holder name — for confirming account ownership before, say, paying out a salary or a refund. OpenDinar never moves money itself; this endpoint only verifies account details.

{
  "object":     "auth",
  "account_id": "acc_1a2b3c4d5e6f7a8b",
  "bank_id":    "raiffeisen",
  "bank_name":  "Raiffeisen Banka",
  "numbers": {
    "iban":     "RS35265100000012345678",
    "bic":      "RZBSRSBG",
    "currency": "RSD"
  },
  "account_holder": {
    "name":     "Marko Kovačević",
    "verified": true
  },
  "account_type": "current",
  "retrieved_at": "2026-08-25T10:30:00.000Z"
}

Returns AUTH_UNAVAILABLE (404) if the bank doesn't expose account data or the account has no IBAN.

Force refresh

Triggers a fresh data pull from the bank and resets the sync cursor. Fires the TRANSACTIONS.SYNC_UPDATES_AVAILABLE webhook.

Transactions

Get transactions

Query parameters

Transaction object

{
  "id":                       "txn_5c4d3e2f1a0b9c8d",
  "account_id":               "acc_1a2b3c4d5e6f7a8b",
  "date":                     "2026-04-04",
  "amount":                   -1650.00,
  "currency":                 "RSD",
  "description":              "DIS market Vracar",
  "category":                 "groceries",
  "type":                     "debit",
  "pending":                  1,          // 1 = not yet posted, 0 = cleared
  "pending_transaction_id":   null        // links pending → posted once cleared
}

Cursor-based sync

Use ?cursor= to efficiently fetch only new transactions since your last call — like Plaid's /transactions/sync.

# First call — no cursor, returns full history
GET /accounts/acc_1a2b3c4d5e6f7a8b/transactions?cursor=

# Response includes next_cursor
{
  "sync_status": "HISTORICAL_UPDATE_COMPLETE",
  "added": [ /* transactions */ ],
  "next_cursor": "txn_9f8e7d6c5b4a3f2e"
}

# Next call — only returns NEW transactions since last time
GET /accounts/acc_1a2b3c4d5e6f7a8b/transactions?cursor=txn_9f8e7d6c5b4a3f2e

Recurring Transactions

Detects recurring payments and income from transaction history. Groups transactions by description and category, identifies patterns, and returns outgoing (subscriptions, rent) and incoming (salary) streams separately.

{
  "outgoing": [
    {
      "description": "Netflix",
      "category": "subscriptions",
      "frequency": "monthly",
      "amount_type": "fixed",
      "typical_amount": 790.00,
      "occurrences": 3
    }
  ],
  "incoming": [
    {
      "description": "Plata - januar 2026",
      "category": "salary",
      "frequency": "monthly",
      "typical_amount": 95000.00
    }
  ],
  "monthly_outgoing_total": 3240.00,
  "monthly_incoming_total": 95000.00
}

Webhooks

Instead of polling the API for changes, register a webhook URL and OpenDinar will send you an HTTP POST whenever something happens — a bank connects, a connection is revoked, or new transactions are ready.

Register webhooks from the Developer Dashboard or via the Webhooks API.

Webhook Events

AUTH.AUTOMATICALLY_VERIFIED

Fired when a user successfully connects a bank through the Link Widget.

{
  "webhook_type": "AUTH",
  "webhook_code": "AUTOMATICALLY_VERIFIED",
  "connection_id": "conn_abc123",
  "bank_id": "raiffeisen",
  "user_id": "user_123",
  "timestamp": 1743760200
}

ITEM.CONNECTION_REVOKED

Fired when a connection is revoked (either by the user or via DELETE /connections/:id).

{
  "webhook_type": "ITEM",
  "webhook_code": "CONNECTION_REVOKED",
  "connection_id": "conn_abc123",
  "bank_id": "raiffeisen",
  "user_id": "user_123",
  "timestamp": 1743760200
}

ITEM.CONNECTION_EXPIRING

Fired once when a connection's 90-day consent is within 7 days of expiring — prompt your user to reconnect. See Consent & Expiry.

{
  "webhook_type": "ITEM",
  "webhook_code": "CONNECTION_EXPIRING",
  "connection_id": "conn_abc123",
  "bank_id": "raiffeisen",
  "user_id": "user_123",
  "expires_at": "2026-09-01T09:00:00.000Z",
  "days_until_expiry": 5,
  "timestamp": 1743760200
}

ITEM.CONNECTION_EXPIRED

Fired once when a connection's consent has lapsed. Data requests on it now return CONSENT_EXPIRED until the user reconnects.

{
  "webhook_type": "ITEM",
  "webhook_code": "CONNECTION_EXPIRED",
  "connection_id": "conn_abc123",
  "bank_id": "raiffeisen",
  "user_id": "user_123",
  "expired_at": "2026-09-01T09:00:00.000Z",
  "timestamp": 1743760200
}

TRANSACTIONS.SYNC_UPDATES_AVAILABLE

Fired when new transactions are available for an account (after a force sync via POST /accounts/:id/sync, or when the bank reports new data).

{
  "webhook_type": "TRANSACTIONS",
  "webhook_code": "SYNC_UPDATES_AVAILABLE",
  "account_id": "acc_1a2b3c4d5e6f7a8b",
  "bank_id": "raiffeisen",
  "timestamp": 1743760200
}

Verifying Webhooks

Every webhook request includes an OpenDinar-Signature header. Always verify this before processing the event.

# Header format (same as Stripe)
OpenDinar-Signature: t=1743760200,v1=abc123...

Verification steps

1. Extract t (timestamp) and v1 (signature) from the header
2. Construct the signed string: t + "." + raw_request_body
3. Compute HMAC-SHA256 of that string using your webhook secret
4. Compare your result to v1 — reject if they don't match
5. Reject if the timestamp is more than 5 minutes old (prevents replay attacks)

// Node.js verification example
const { createHmac } = require('crypto');

function verifyWebhook(secret, rawBody, signatureHeader) {
  const parts    = Object.fromEntries(signatureHeader.split(',').map(p => p.split('=')));
  const expected = createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');
  return expected === parts.v1;
}

Developer Portal — Auth

These endpoints let developers manage their accounts programmatically. All management endpoints require a developer session token (devses_…) obtained from POST /developers/login.

Register

Creates an account and sends a verification email. You must verify your email before you can log in — the API key is shown in the dashboard after verification, not in the register response.

Login

Returns a devses_… session token valid for 24 hours. Unverified accounts get an EMAIL_NOT_VERIFIED error.

Logout

Get account

Email verification

Resend takes just { "email": "…" } — no login needed.

Password reset

Forgot-password emails a one-time reset link; reset-password takes the token from that link plus the new password.

Developer Portal — API Keys

List keys

Returns key prefix, app name, environment, and status. Full keys are never shown after creation.

Generate a key

Revoke a key

Takes effect immediately. Any requests using the revoked key will receive a 401 REVOKED_API_KEY error.

Developer Portal — Usage

Returns total request counts, breakdown by endpoint, error rates, and recent errors for all your API keys.

Developer Portal — Webhooks

Register a webhook

Request body

List webhooks

Remove a webhook

Developer Portal — Your Data (GDPR/ZZPL)

Every developer account has full data-protection rights, exercisable via the API:

See what we hold (right of access)

Download everything (right to portability)

Returns all your account data as a JSON download.

Delete your account (right to erasure)

Permanently deletes your account, keys, webhooks, and connections, and anonymises request logs. This cannot be undone.

Error Codes

Sandbox

The sandbox environment is fully functional with pre-seeded fake data. No real bank connections or real user data is involved.

Test API keys

These shared keys are read-only: they can browse sandbox data and connect banks, but cannot delete or modify anything. For the full experience (including revoking connections), use your own key.

Sandbox dataset

Each new connection gets its own private copy of the bank's test accounts and transactions, with freshly generated IDs (acc_… / txn_…). Two connections never share data — just like in production. Call GET /accounts after connecting to get your account IDs.

Sandbox auth flow

When connecting a bank in sandbox, the Link Widget opens a fake bank login page at /sandbox/auth.html. Enter any username and password — click Odobri pristup to authorize. The widget picks it up automatically.

Sandbox-only endpoint

Called by the sandbox auth page to programmatically authorize a session. Pass { "session_token": "sess_..." }. Useful for automated testing.