@tatogi/bog-payment-js 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tato
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# @tatogi/bog-payment-js
+
+JavaScript client for Bank of Georgia iPay API.
+
+## Install
+
+```bash
+npm install @tatogi/bog-payment-js
+```
+
+## Usage
+
+```js
+import { BogPaymentClient } from "@tatogi/bog-payment-js";
+
+const bog = new BogPaymentClient({
+  clientId: process.env.BOG_CLIENT_ID,
+  clientSecret: process.env.BOG_CLIENT_SECRET
+});
+
+const order = await bog.createOrder(
+  {
+    callback_url: "https://example.com/bog/callback",
+    external_order_id: "order-1001",
+    purchase_units: {
+      total_amount: 100,
+      currency: "GEL",
+      basket: [
+        {
+          product_id: "product-1",
+          name: "T-Shirt",
+          quantity: 1,
+          unit_price: 100
+        }
+      ]
+    },
+    redirect_urls: {
+      success: "https://example.com/checkout/success",
+      fail: "https://example.com/checkout/fail"
+    }
+  },
+  {
+    idempotencyKey: crypto.randomUUID(),
+    acceptLanguage: "en"
+  }
+);
+
+console.log(order._links.redirect.href);
+```
+
+## Configuration
+
+- `clientId` (required)
+- `clientSecret` (required)
+- `authUrl` (optional)  
+  default: `https://oauth2.bog.ge/auth/realms/bog/protocol/openid-connect/token`
+- `baseUrl` (optional)  
+  default: `https://ipay.ge/opay/api/v1`
+- `timeoutMs` (optional)  
+  default: `30000`
+- `fetchImpl` (optional) for custom runtime fetch
+
+## Methods
+
+- `getAccessToken(forceRefresh = false)`
+- `createOrder(payload, { idempotencyKey, acceptLanguage } = {})`
+- `getOrderDetails(orderId)`
+- `payWithSavedCard(parentOrderId, payload, { idempotencyKey, acceptLanguage } = {})`
+- `saveCard(orderId, { idempotencyKey } = {})`
+- `deleteSavedCard(orderId, { idempotencyKey })`
+- `confirmPreAuthorization(orderId, payload = {})`
+- `rejectPreAuthorization(orderId, payload = {})`
+
+## Test
+
+```bash
+npm test
+```
+
+## Publish
+
+```bash
+npm login
+npm publish --access public
+```
+
+For automated publish from GitHub Actions:
+- add repository secret `NPM_TOKEN`
+- push a tag like `v1.0.0`

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@tatogi/bog-payment-js",
+  "version": "1.0.0",
+  "description": "JavaScript client for Bank of Georgia iPay API",
+  "private": false,
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test/client.test.js",
+    "prepublishOnly": "npm test",
+    "release:patch": "npm version patch && npm publish --access public",
+    "release:minor": "npm version minor && npm publish --access public",
+    "release:major": "npm version major && npm publish --access public"
+  },
+  "keywords": [
+    "bog",
+    "bank-of-georgia",
+    "ipay",
+    "payments",
+    "javascript",
+    "node"
+  ],
+  "author": "Tato",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tatoGi/bog-payment-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tatoGi/bog-payment-js/issues"
+  },
+  "homepage": "https://github.com/tatoGi/bog-payment-js#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/BogPaymentClient.js

@@ -0,0 +1,236 @@
+import { BogPaymentError } from "./errors.js";
+
+const DEFAULT_AUTH_URL =
+  "https://oauth2.bog.ge/auth/realms/bog/protocol/openid-connect/token";
+const DEFAULT_BASE_URL = "https://ipay.ge/opay/api/v1";
+
+function trimSlash(value) {
+  return String(value || "").replace(/\/+$/, "");
+}
+
+export class BogPaymentClient {
+  constructor(options = {}) {
+    this.clientId = options.clientId;
+    this.clientSecret = options.clientSecret;
+    this.authUrl = options.authUrl || DEFAULT_AUTH_URL;
+    this.baseUrl = trimSlash(options.baseUrl || DEFAULT_BASE_URL);
+    this.timeoutMs = options.timeoutMs ?? 30000;
+    this.fetchImpl = options.fetchImpl || globalThis.fetch;
+    this.cachedToken = null;
+    this.cachedTokenExpiresAt = 0;
+
+    if (!this.fetchImpl) {
+      throw new BogPaymentError(
+        "Fetch API is not available. Use Node 18+ or pass fetchImpl."
+      );
+    }
+  }
+
+  async getAccessToken(forceRefresh = false) {
+    const now = Date.now();
+    if (
+      !forceRefresh &&
+      this.cachedToken &&
+      this.cachedTokenExpiresAt > now + 10_000
+    ) {
+      return this.cachedToken;
+    }
+
+    if (!this.clientId || !this.clientSecret) {
+      throw new BogPaymentError(
+        "Missing BOG credentials: clientId and clientSecret are required."
+      );
+    }
+
+    const body = new URLSearchParams({ grant_type: "client_credentials" });
+
+    const basicAuth = Buffer.from(
+      `${this.clientId}:${this.clientSecret}`,
+      "utf8"
+    ).toString("base64");
+
+    const response = await this.#fetchWithTimeout(this.authUrl, {
+      method: "POST",
+      headers: {
+        Authorization: `Basic ${basicAuth}`,
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json"
+      },
+      body
+    });
+
+    const payload = await this.#parseJson(response);
+    if (!response.ok) {
+      throw new BogPaymentError("BOG authentication failed.", {
+        status: response.status,
+        body: payload
+      });
+    }
+
+    this.cachedToken = payload.access_token;
+    const expiresInSeconds = Number(payload.expires_in || 3600);
+    this.cachedTokenExpiresAt = now + expiresInSeconds * 1000;
+
+    return this.cachedToken;
+  }
+
+  async createOrder(payload, options = {}) {
+    return this.#authorizedRequest("/checkout/orders", {
+      method: "POST",
+      body: payload,
+      idempotencyKey: options.idempotencyKey,
+      acceptLanguage: options.acceptLanguage
+    });
+  }
+
+  async getOrderDetails(orderId) {
+    if (!orderId) {
+      throw new BogPaymentError("orderId is required.");
+    }
+
+    return this.#authorizedRequest(`/checkout/payment/${orderId}`, {
+      method: "GET"
+    });
+  }
+
+  async payWithSavedCard(parentOrderId, payload, options = {}) {
+    if (!parentOrderId) {
+      throw new BogPaymentError("parentOrderId is required.");
+    }
+
+    return this.#authorizedRequest(`/checkout/orders/${parentOrderId}/payments`, {
+      method: "POST",
+      body: payload,
+      idempotencyKey: options.idempotencyKey,
+      acceptLanguage: options.acceptLanguage
+    });
+  }
+
+  async saveCard(orderId, options = {}) {
+    if (!orderId) {
+      throw new BogPaymentError("orderId is required.");
+    }
+
+    return this.#authorizedRequest(`/checkout/orders/${orderId}/save-card`, {
+      method: "POST",
+      body: {},
+      idempotencyKey: options.idempotencyKey
+    });
+  }
+
+  async deleteSavedCard(orderId, options = {}) {
+    if (!orderId) {
+      throw new BogPaymentError("orderId is required.");
+    }
+
+    if (!options.idempotencyKey) {
+      throw new BogPaymentError("idempotencyKey is required.");
+    }
+
+    return this.#authorizedRequest(`/checkout/orders/${orderId}/saved-card`, {
+      method: "DELETE",
+      idempotencyKey: options.idempotencyKey
+    });
+  }
+
+  async confirmPreAuthorization(orderId, payload = {}) {
+    if (!orderId) {
+      throw new BogPaymentError("orderId is required.");
+    }
+
+    return this.#authorizedRequest(
+      `/checkout/orders/${orderId}/preauthorization/confirm`,
+      {
+        method: "POST",
+        body: payload
+      }
+    );
+  }
+
+  async rejectPreAuthorization(orderId, payload = {}) {
+    if (!orderId) {
+      throw new BogPaymentError("orderId is required.");
+    }
+
+    return this.#authorizedRequest(
+      `/checkout/orders/${orderId}/preauthorization/reject`,
+      {
+        method: "POST",
+        body: payload
+      }
+    );
+  }
+
+  async #authorizedRequest(path, options = {}) {
+    const token = await this.getAccessToken();
+    const url = `${this.baseUrl}${path}`;
+
+    const headers = {
+      Accept: "application/json",
+      Authorization: `Bearer ${token}`,
+      ...(options.body ? { "Content-Type": "application/json" } : {})
+    };
+
+    if (options.idempotencyKey) {
+      headers["Idempotency-Key"] = options.idempotencyKey;
+    }
+
+    if (options.acceptLanguage) {
+      headers["Accept-Language"] = options.acceptLanguage;
+    }
+
+    const response = await this.#fetchWithTimeout(url, {
+      method: options.method || "GET",
+      headers,
+      body: options.body ? JSON.stringify(options.body) : undefined
+    });
+
+    const payload = await this.#parseJson(response);
+    if (!response.ok) {
+      throw new BogPaymentError("BOG API request failed.", {
+        status: response.status,
+        body: payload
+      });
+    }
+
+    return payload;
+  }
+
+  async #fetchWithTimeout(url, options) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    try {
+      return await this.fetchImpl(url, {
+        ...options,
+        signal: controller.signal
+      });
+    } catch (error) {
+      if (error.name === "AbortError") {
+        throw new BogPaymentError("BOG API request timed out.", {
+          code: "REQUEST_TIMEOUT"
+        });
+      }
+
+      throw new BogPaymentError(error.message || "BOG API network error.", {
+        code: "NETWORK_ERROR"
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async #parseJson(response) {
+    const contentType = response.headers.get("content-type") || "";
+    if (contentType.includes("application/json")) {
+      return response.json();
+    }
+
+    const text = await response.text();
+    try {
+      return JSON.parse(text);
+    } catch {
+      return { raw: text };
+    }
+  }
+}

package/src/errors.js

@@ -0,0 +1,9 @@
+export class BogPaymentError extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "BogPaymentError";
+    this.status = options.status ?? null;
+    this.body = options.body ?? null;
+    this.code = options.code ?? null;
+  }
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { BogPaymentClient } from "./BogPaymentClient.js";
+export { BogPaymentError } from "./errors.js";