Bog Bonline

BOG Business Online API

RESTful API for Bank of Georgia corporate internet banking.

Base URL: https://api.businessonline.ge/api Auth Server: https://account.bog.ge

Quick Reference

| Operation | Endpoint | Reference | |-----------|----------|-----------| | Token (Client Credentials) | POST /auth/.../token | [authentication.md](references/authentication.md) | | Auth (Authorization Code) | GET /auth/.../auth | [authentication.md](references/authentication.md) | | Balance | GET api/accounts/{account}/{currency} | [accounts.md](references/accounts.md) | | Statement | GET api/statement/{account}/{currency}/{start}/{end} | [accounts.md](references/accounts.md) | | Domestic Transfer | POST api/documents/domestic | [transfers.md](references/transfers.md) | | Foreign Transfer | POST api/documents/foreign | [transfers.md](references/transfers.md) | | Conversion | POST api/documents/conversion | [transfers.md](references/transfers.md) | | Sign Document | POST api/sign/document | [transfers.md](references/transfers.md) | | NBG Rate | GET api/rates/nbg/{currency} | [rates.md](references/rates.md) | | Commercial Rate | GET api/rates/commercial/{currency} | [rates.md](references/rates.md) |

Authentication

OAuth 2.0 flow. Register app at bonline.bog.ge/admin/api/ to get clientid and clientsecret.

Option 1: Client Credentials Flow (Backend/Service)

For server-to-server integrations without user login. Enable "Service accounts roles" in BOG admin panel.

// Token endpoint - works from Node.js/backend only (CORS blocks browser calls)
const tokenResponse = await fetch(
  'https://account.bog.ge/auth/realms/bog/protocol/openid-connect/token',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString('base64')}`
    },
    body: 'grant_type=client_credentials&scope=corp'
  }
);
const { access_token, expires_in } = await tokenResponse.json();

Option 2: Authorization Code Flow (Web Apps with User Login)

For apps requiring user authentication via BOG login page.

// 1. Redirect user to authorization URL
const authUrl = `https://account.bog.ge/auth/realms/bog/protocol/openid-connect/auth?` +
  `client_id=${clientId}&response_type=code&scope=corp&redirect_uri=${redirectUri}`;

// 2. Exchange code for token (must be done server-side due to CORS)
const tokenResponse = await fetch(
  'https://account.bog.ge/auth/realms/bog/protocol/openid-connect/token',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString('base64')}`
    },
    body: `grant_type=authorization_code&code=${code}&redirect_uri=${redirectUri}`
  }
);

CORS Limitation

Important: BOG token endpoint blocks cross-origin requests. For web apps, use a backend proxy:

// server.js - Express proxy for web apps
app.post('/api/auth', async (req, res) => {
  const credentials = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64');
  const response = await fetch(TOKEN_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Basic ${credentials}`
    },
    body: 'grant_type=client_credentials&scope=corp'
  });
  const data = await response.json();
  // Cache token server-side, return auth status to client
  res.json({ authenticated: true, expiresAt: Date.now() + data.expires_in * 1000 });
});

// Proxy API calls with token
app.all('/api/bog/*', async (req, res) => {
  const apiPath = req.path.replace('/api/bog', '');
  const response = await fetch(`https://api.businessonline.ge/api${apiPath}`, {
    method: req.method,
    headers: { 'Authorization': `Bearer ${cachedToken}`, 'Content-Type': 'application/json' },
    body: req.method !== 'GET' ? JSON.stringify(req.body) : undefined
  });
  res.status(response.status).json(await response.json());
});

All API calls require: Authorization: Bearer {access_token}

See [authentication.md](references/authentication.md) for full OAuth flow details.

Common Patterns

Get Account Balance

const balance = await fetch(
  `${BASE_URL}/accounts/${accountNumber}/${currency}`,
  { headers: { Authorization: `Bearer ${token}` } }
).then(r => r.json());
// { AvailableBalance: 15000.50, CurrentBalance: 18500.00 }

Create Domestic Transfer

const transfer = [{
  UniqueId: crypto.randomUUID(),
  DocumentNo: 'PAY001',
  ValueDate: new Date().toISOString().split('T')[0],
  Amount: 1500.00,
  SourceAccountNumber: 'GE12BG0000000123456789',
  BeneficiaryAccountNumber: 'GE12TB0000000987654321',
  BeneficiaryBankCode: 'TBCBGE22',
  BeneficiaryInn: '12345678901',
  PayerInn: '98765432101',
  Nomination: 'Invoice #123 payment'
}];

const result = await fetch(`${BASE_URL}/documents/domestic`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(transfer)
}).then(r => r.json());

// Sign if ResultCode === 0
if (result[0].ResultCode === 0) {
  await fetch(`${BASE_URL}/sign/document`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ Otp: otpCode, ObjectKey: result[0].UniqueKey })
  });
}

Get Exchange Rates

// NBG official rate
const nbgRate = await fetch(`${BASE_URL}/rates/nbg/USD`, {
  headers: { Authorization: `Bearer ${token}` }
}).then(r => r.json()); // 2.75

// Bank commercial rate
const commercialRate = await fetch(`${BASE_URL}/rates/commercial/USD`, {
  headers: { Authorization: `Bearer ${token}` }
}).then(r => r.json()); // { Sell: 2.78, Buy: 2.72 }

Error Handling

Check ResultCode in responses:

• 0 = Success (ready to sign)
• 333 = Insufficient working balance
• 444 = Insufficient funds
• 363 = Duplicate document

See [result-codes.md](references/result-codes.md) for complete list.

Response Headers

Every response includes x-correlationid header with unique request ID for troubleshooting.

Environment

• Production: https://api.businessonline.ge/api
• Test: Contact customerservice@bog.ge for test environment access

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sepivip
• Source: sepivip/claude-skill-bog-bonline
• License: MIT

Install and usage instructions live in the source repository linked above.