telebirr-nodejs 1.0.1

package/dist/index.d.cts

@@ -0,0 +1,104 @@
+type TelebirrMode = "simulate" | "sandbox" | "production";
+type IntegrationOption = "C2B" | "B2B";
+interface TelebirrConfig {
+    appId: string;
+    appSecret: string;
+    merchantAppId: string;
+    merchantCode: string;
+    privateKey: string;
+    notifyUrl: string;
+    redirectUrl: string;
+    mode: TelebirrMode;
+    http: boolean;
+    integrationOption: IntegrationOption;
+}
+
+interface GenerateCheckoutUrlInput {
+    title: string;
+    amount: string;
+    merchOrderId?: string;
+    callbackInfo?: string;
+}
+
+type TelebirrTradeStatus = "PAY_SUCCESS" | "PAY_FAILED" | "WAIT_PAY" | "ORDER_CLOSED" | "PAYING" | "ACCEPTED" | "REFUNDING" | "REFUND_SUCCESS" | "REFUND_FAILED";
+interface QueryOrderResponse {
+    result: "SUCCESS" | "FAIL";
+    code: string;
+    msg: string;
+    sign: string;
+    sign_type: "SHA256WithRSA";
+    nonce_str: string;
+    biz_content: {
+        merch_order_id: string;
+        order_status: TelebirrTradeStatus;
+        payment_order_id: string;
+        trans_time: string;
+        trans_currency: "ETB";
+        total_amount: string;
+        trans_id: string;
+    };
+}
+
+interface RefundInput {
+    merchOrderId: string;
+    refundRequestNo: string;
+    amount: string;
+    refundReason?: string;
+}
+type TelebirrRefundStatus = "REFUND_SUCCESS" | "REFUNDING" | "REFUND_FAILED" | "REFUND_DUPLICATED";
+interface RefundResponse {
+    result: "SUCCESS" | "FAIL";
+    code: string;
+    msg: string;
+    sign: string;
+    sign_type: "SHA256WithRSA";
+    nonce_str: string;
+    biz_content: {
+        /** Short code registered by a merchant with Mobile Money */
+        merch_code: string;
+        /** Order ID on the merchant side */
+        merch_order_id: string;
+        /** Original transaction order ID on the payment side */
+        trans_order_id: string;
+        /** Refund transaction order ID on the payment side */
+        refund_order_id: string;
+        /** Refund amount */
+        refund_amount: string;
+        /** Refund currency (e.g. ETB) */
+        refund_currency: string;
+        /** Refund status */
+        refund_status: TelebirrRefundStatus;
+        /**
+         * Refund success timestamp.
+         * Only present when refund_status === "REFUND_SUCCESS"
+         */
+        refund_time?: string;
+    };
+}
+
+declare class TelebirrClient {
+    private token?;
+    private config;
+    constructor(config: TelebirrConfig);
+    getFabricToken(): Promise<any>;
+    private createCheckoutUrl;
+    preOrder(input: GenerateCheckoutUrlInput): Promise<string | void>;
+    queryOrder(input: string): Promise<QueryOrderResponse | void>;
+    refundOrder(input: RefundInput): Promise<RefundResponse | void>;
+    private static readonly TOKEN_EXPIRY_SAFETY_WINDOW_MS;
+    private isTokenExpired;
+    private parseTelebirrDate;
+}
+
+interface KeyPairOptions {
+    dir?: string;
+    privateKeyName?: string;
+    publicKeyName?: string;
+    overwrite?: boolean;
+}
+declare function generateKeys(options?: KeyPairOptions): {
+    privateKeyPath: string;
+    publicKeyPath: string;
+};
+
+export { TelebirrClient, type TelebirrConfig, generateKeys };

package/dist/index.d.ts

@@ -0,0 +1,104 @@
+type TelebirrMode = "simulate" | "sandbox" | "production";
+type IntegrationOption = "C2B" | "B2B";
+interface TelebirrConfig {
+    appId: string;
+    appSecret: string;
+    merchantAppId: string;
+    merchantCode: string;
+    privateKey: string;
+    notifyUrl: string;
+    redirectUrl: string;
+    mode: TelebirrMode;
+    http: boolean;
+    integrationOption: IntegrationOption;
+}
+
+interface GenerateCheckoutUrlInput {
+    title: string;
+    amount: string;
+    merchOrderId?: string;
+    callbackInfo?: string;
+}
+
+type TelebirrTradeStatus = "PAY_SUCCESS" | "PAY_FAILED" | "WAIT_PAY" | "ORDER_CLOSED" | "PAYING" | "ACCEPTED" | "REFUNDING" | "REFUND_SUCCESS" | "REFUND_FAILED";
+interface QueryOrderResponse {
+    result: "SUCCESS" | "FAIL";
+    code: string;
+    msg: string;
+    sign: string;
+    sign_type: "SHA256WithRSA";
+    nonce_str: string;
+    biz_content: {
+        merch_order_id: string;
+        order_status: TelebirrTradeStatus;
+        payment_order_id: string;
+        trans_time: string;
+        trans_currency: "ETB";
+        total_amount: string;
+        trans_id: string;
+    };
+}
+
+interface RefundInput {
+    merchOrderId: string;
+    refundRequestNo: string;
+    amount: string;
+    refundReason?: string;
+}
+type TelebirrRefundStatus = "REFUND_SUCCESS" | "REFUNDING" | "REFUND_FAILED" | "REFUND_DUPLICATED";
+interface RefundResponse {
+    result: "SUCCESS" | "FAIL";
+    code: string;
+    msg: string;
+    sign: string;
+    sign_type: "SHA256WithRSA";
+    nonce_str: string;
+    biz_content: {
+        /** Short code registered by a merchant with Mobile Money */
+        merch_code: string;
+        /** Order ID on the merchant side */
+        merch_order_id: string;
+        /** Original transaction order ID on the payment side */
+        trans_order_id: string;
+        /** Refund transaction order ID on the payment side */
+        refund_order_id: string;
+        /** Refund amount */
+        refund_amount: string;
+        /** Refund currency (e.g. ETB) */
+        refund_currency: string;
+        /** Refund status */
+        refund_status: TelebirrRefundStatus;
+        /**
+         * Refund success timestamp.
+         * Only present when refund_status === "REFUND_SUCCESS"
+         */
+        refund_time?: string;
+    };
+}
+
+declare class TelebirrClient {
+    private token?;
+    private config;
+    constructor(config: TelebirrConfig);
+    getFabricToken(): Promise<any>;
+    private createCheckoutUrl;
+    preOrder(input: GenerateCheckoutUrlInput): Promise<string | void>;
+    queryOrder(input: string): Promise<QueryOrderResponse | void>;
+    refundOrder(input: RefundInput): Promise<RefundResponse | void>;
+    private static readonly TOKEN_EXPIRY_SAFETY_WINDOW_MS;
+    private isTokenExpired;
+    private parseTelebirrDate;
+}
+
+interface KeyPairOptions {
+    dir?: string;
+    privateKeyName?: string;
+    publicKeyName?: string;
+    overwrite?: boolean;
+}
+declare function generateKeys(options?: KeyPairOptions): {
+    privateKeyPath: string;
+    publicKeyPath: string;
+};
+
+export { TelebirrClient, type TelebirrConfig, generateKeys };

package/dist/index.js

@@ -0,0 +1,489 @@
+// src/utils/credentials.ts
+import fs2 from "fs";
+import { randomUUID, randomBytes } from "crypto";
+import { customAlphabet } from "nanoid";
+
+// src/utils/keys.ts
+import { generateKeyPairSync } from "crypto";
+import fs from "fs";
+import path from "path";
+function generateKeys(options = {}) {
+  const {
+    dir = process.cwd(),
+    privateKeyName = "telebirr_private.pem",
+    publicKeyName = "telebirr_public.pem",
+    overwrite = false
+  } = options;
+  const privateKeyPath = path.join(dir, privateKeyName);
+  const publicKeyPath = path.join(dir, publicKeyName);
+  const exists = fs.existsSync(privateKeyPath) && fs.existsSync(publicKeyPath);
+  if (exists && !overwrite) {
+    return { privateKeyPath, publicKeyPath };
+  }
+  const { privateKey, publicKey } = generateKeyPairSync("rsa", {
+    modulusLength: 2048,
+    publicKeyEncoding: {
+      type: "pkcs1",
+      format: "pem"
+    },
+    privateKeyEncoding: {
+      type: "pkcs1",
+      format: "pem"
+    }
+  });
+  fs.writeFileSync(privateKeyPath, privateKey, { mode: 384 });
+  fs.writeFileSync(publicKeyPath, publicKey);
+  return { privateKeyPath, publicKeyPath };
+}
+
+// src/utils/credentials.ts
+var numeric16 = customAlphabet("0123456789", 16);
+var numeric6 = customAlphabet("0123456789", 6);
+function generateCredentials() {
+  const { privateKeyPath } = generateKeys();
+  const merchantPrivateKey = fs2.readFileSync(privateKeyPath, "utf8");
+  return {
+    fabricAppId: randomUUID(),
+    fabricAppSecret: randomBytes(16).toString("hex"),
+    merchantAppId: numeric16(),
+    merchantCode: numeric6(),
+    merchantPrivateKey
+  };
+}
+
+// src/services/requestToken.ts
+import http from "http";
+import https from "https";
+
+// src/constants/urls.ts
+var TELEBIRR_URLS = {
+  sandbox: {
+    apiBase: "https://developerportal.ethiotelebirr.et:38443/apiaccess/payment/gateway",
+    webBase: "https://developerportal.ethiotelebirr.et:38443/payment/web/paygate?"
+  },
+  production: {
+    apiBase: "https://telebirrappcube.ethiomobilemoney.et:38443/apiaccess/payment/gateway",
+    webBase: "https://telebirrappcube.ethiomobilemoney.et:38443/payment/web/paygate?"
+  },
+  simulate: {
+    apiBase: "http://localhost:3000",
+    webBase: "http://localhost:3000/web/?"
+  }
+  // simulate: {
+  //   apiBase: "https://telebirr-node-simulator.onrender.com",
+  //   webBase: "https://telebirr-node-simulator.onrender.com/web/?",
+  // },
+};
+var CHECKOUT_OTHER_PARAMS = "&version=1.0&trade_type=Checkout";
+
+// src/services/requestToken.ts
+function requestToken(config) {
+  const isHttps = TELEBIRR_URLS[config.mode].apiBase.startsWith("https://");
+  const client = isHttps ? https : http;
+  return new Promise((resolve, reject) => {
+    const req = client.request(
+      ` ${TELEBIRR_URLS[config.mode].apiBase}/payment/v1/token`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-APP-Key": config.appId
+        },
+        ...isHttps && { rejectUnauthorized: false }
+      },
+      (res) => {
+        let body = "";
+        res.on("data", (chunk) => body += chunk);
+        res.on("end", () => resolve(body));
+      }
+    );
+    req.on("error", reject);
+    req.write(JSON.stringify({ appSecret: config.appSecret }));
+    req.end();
+  });
+}
+
+// src/services/requestCreateOrder.ts
+import http2 from "http";
+import https2 from "https";
+
+// src/utils/nonce.ts
+import { randomBytes as randomBytes2 } from "crypto";
+function createNonceStr() {
+  const bytes = Math.ceil(16);
+  return randomBytes2(bytes).toString("hex").slice(0, 32);
+}
+
+// src/utils/timestamp.ts
+function createTimestamp() {
+  return Math.floor(Date.now() / 1e3).toString();
+}
+
+// src/utils/signature.ts
+import crypto from "crypto";
+function flattenParams(params) {
+  const flat = {};
+  for (const key in params) {
+    const value = params[key];
+    if (value === void 0 || value === null || value === "" || key === "sign" || key === "signType" || key === "sign_type") {
+      continue;
+    }
+    if (key === "biz_content" && typeof value === "object") {
+      for (const bizKey in value) {
+        const bizValue = value[bizKey];
+        if (bizValue !== void 0 && bizValue !== null && bizValue !== "") {
+          flat[bizKey] = String(bizValue);
+        }
+      }
+    } else {
+      flat[key] = String(value);
+    }
+  }
+  return flat;
+}
+function buildSignString(params) {
+  const flat = flattenParams(params);
+  return Object.keys(flat).sort().map((key) => `${key}=${flat[key]}`).join("&");
+}
+function signRequest(data, privateKey) {
+  const signString = buildSignString(data);
+  return crypto.createSign("RSA-SHA256").update(signString, "utf8").sign(privateKey, "base64");
+}
+
+// src/services/requestCreateOrder.ts
+function requestCreateOrder(fabricToken, input, config) {
+  const reqBody = {
+    timestamp: createTimestamp(),
+    nonce_str: createNonceStr(),
+    method: "payment.preorder",
+    version: "1.0",
+    biz_content: {
+      appid: config.merchantAppId,
+      merch_code: config.merchantCode,
+      merch_order_id: input.merchOrderId,
+      notify_url: config.notifyUrl,
+      redirect_url: config.redirectUrl,
+      trade_type: "Checkout",
+      title: input.title,
+      total_amount: input.amount,
+      trans_currency: "ETB",
+      timeout_express: "120m",
+      business_type: "BuyGoods",
+      payee_type: "3000",
+      payee_identifier: config.merchantCode,
+      payee_identifier_type: "04",
+      callback_info: "From web"
+    }
+  };
+  reqBody.sign = signRequest(reqBody, config.privateKey);
+  reqBody.sign_type = "SHA256WithRSA";
+  const payload = JSON.stringify(reqBody);
+  const baseUrl = TELEBIRR_URLS[config.mode].apiBase;
+  const isHttps = baseUrl.startsWith("https://");
+  const client = isHttps ? https2 : http2;
+  return new Promise((resolve, reject) => {
+    const req = client.request(
+      `${baseUrl}/payment/v1/merchant/preOrder`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Content-Length": Buffer.byteLength(payload),
+          "X-APP-Key": config.appId,
+          Authorization: fabricToken
+        },
+        ...isHttps && { rejectUnauthorized: false }
+      },
+      (res) => {
+        let raw = "";
+        res.on("data", (chunk) => {
+          raw += chunk;
+        });
+        res.on("end", () => {
+          const status = res.statusCode || 0;
+          let parsed = raw;
+          try {
+            parsed = JSON.parse(raw);
+          } catch {
+          }
+          if (status < 200 || status >= 300) {
+            return reject({
+              message: "Telebirr preorder request failed",
+              status,
+              data: parsed,
+              headers: res.headers
+            });
+          }
+          resolve({
+            data: parsed,
+            status,
+            headers: res.headers
+          });
+        });
+      }
+    );
+    req.on("error", (err) => {
+      reject({
+        message: "Telebirr preorder network error",
+        cause: err,
+        code: err.code
+      });
+    });
+    req.write(payload);
+    req.end();
+  });
+}
+
+// src/services/requestRefundOrder.ts
+import http3 from "http";
+import https3 from "https";
+function requestRefund(fabricToken, input, config) {
+  const reqBody = {
+    timestamp: createTimestamp(),
+    nonce_str: createNonceStr(),
+    method: "payment.refund",
+    version: "1.0",
+    biz_content: {
+      appid: config.merchantAppId,
+      merch_code: config.merchantCode,
+      merch_order_id: input.merchOrderId,
+      trans_currency: "ETB",
+      actual_amount: input.amount,
+      refund_request_no: input.refundRequestNo,
+      refund_reason: input.refundReason
+    }
+  };
+  reqBody.sign = signRequest(reqBody, config.privateKey);
+  reqBody.sign_type = "SHA256WithRSA";
+  const payload = JSON.stringify(reqBody);
+  const baseUrl = TELEBIRR_URLS[config.mode].apiBase;
+  const isHttps = baseUrl.startsWith("https://");
+  const client = isHttps ? https3 : http3;
+  return new Promise((resolve, reject) => {
+    const req = client.request(
+      `${baseUrl}/payment/v1/merchant/refund`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Content-Length": Buffer.byteLength(payload),
+          "X-APP-Key": config.appId,
+          Authorization: fabricToken
+        },
+        ...isHttps && { rejectUnauthorized: false }
+      },
+      (res) => {
+        let raw = "";
+        res.on("data", (chunk) => {
+          raw += chunk;
+        });
+        res.on("end", () => {
+          const status = res.statusCode || 0;
+          let parsed = raw;
+          try {
+            parsed = JSON.parse(raw);
+          } catch {
+          }
+          if (status < 200 || status >= 300) {
+            return reject({
+              message: "Telebirr refund request failed",
+              status,
+              data: parsed,
+              headers: res.headers
+            });
+          }
+          resolve({
+            data: parsed,
+            status,
+            headers: res.headers
+          });
+        });
+      }
+    );
+    req.on("error", (err) => {
+      reject({
+        message: "Telebirr refund network error",
+        cause: err,
+        code: err.code
+      });
+    });
+    req.write(payload);
+    req.end();
+  });
+}
+
+// src/services/requestQueryOrder.ts
+import http4 from "http";
+import https4 from "https";
+function requestQueryOrder(fabricToken, merchOrderId, config) {
+  const reqBody = {
+    timestamp: createTimestamp(),
+    nonce_str: createNonceStr(),
+    method: "payment.queryorder",
+    version: "1.0",
+    biz_content: {
+      appid: config.merchantAppId,
+      merch_code: config.merchantCode,
+      merch_order_id: merchOrderId
+    }
+  };
+  reqBody.sign = signRequest(reqBody, config.privateKey);
+  reqBody.sign_type = "SHA256WithRSA";
+  const payload = JSON.stringify(reqBody);
+  const baseUrl = TELEBIRR_URLS[config.mode].apiBase;
+  const isHttps = baseUrl.startsWith("https://");
+  const client = isHttps ? https4 : http4;
+  return new Promise((resolve, reject) => {
+    const req = client.request(
+      `${baseUrl}/payment/v1/merchant/queryOrder`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Content-Length": Buffer.byteLength(payload),
+          "X-APP-Key": config.appId,
+          Authorization: fabricToken
+        },
+        ...isHttps && { rejectUnauthorized: false }
+      },
+      (res) => {
+        let raw = "";
+        res.on("data", (chunk) => {
+          raw += chunk;
+        });
+        res.on("end", () => {
+          const status = res.statusCode || 0;
+          let parsed = raw;
+          try {
+            parsed = JSON.parse(raw);
+          } catch {
+          }
+          if (status < 200 || status >= 300) {
+            return reject({
+              message: "Telebirr queryOrder request failed",
+              status,
+              data: parsed,
+              headers: res.headers
+            });
+          }
+          resolve({
+            data: parsed,
+            status,
+            headers: res.headers
+          });
+        });
+      }
+    );
+    req.on("error", (err) => {
+      reject({
+        message: "Telebirr queryOrder network error",
+        cause: err,
+        code: err.code
+      });
+    });
+    req.write(payload);
+    req.end();
+  });
+}
+
+// src/client.ts
+var TelebirrClient = class _TelebirrClient {
+  token;
+  config;
+  constructor(config) {
+    if (config.mode === "simulate") {
+      const creds = generateCredentials();
+      this.config = {
+        ...config,
+        appId: config.appId ?? creds.fabricAppId,
+        appSecret: config.appSecret ?? creds.fabricAppSecret,
+        merchantAppId: config.merchantAppId ?? creds.merchantAppId,
+        merchantCode: config.merchantCode ?? creds.merchantCode,
+        privateKey: creds.merchantPrivateKey
+      };
+    } else {
+      this.config = config;
+    }
+  }
+  async getFabricToken() {
+    if (this.token && !this.isTokenExpired(this.token)) {
+      return this.token;
+    }
+    let token = await requestToken(this.config);
+    token = JSON.parse(token);
+    if (!token) return;
+    this.token = token;
+    return token;
+  }
+  createCheckoutUrl(prepayId) {
+    const map = {
+      appid: this.config.merchantAppId,
+      merch_code: this.config.merchantCode,
+      nonce_str: createNonceStr(),
+      prepay_id: prepayId,
+      timestamp: createTimestamp()
+    };
+    const sign = signRequest(map, this.config.privateKey);
+    const rawRequest = [
+      `appid=${map.appid}`,
+      `merch_code=${map.merch_code}`,
+      `nonce_str=${map.nonce_str}`,
+      `prepay_id=${map.prepay_id}`,
+      `timestamp=${map.timestamp}`,
+      `sign=${sign}`,
+      `sign_type=SHA256WithRSA`
+    ].join("&");
+    const webBase = TELEBIRR_URLS[this.config.mode].webBase;
+    return webBase + rawRequest + CHECKOUT_OTHER_PARAMS;
+  }
+  async preOrder(input) {
+    const token = await this.getFabricToken();
+    if (!token) return;
+    let response = await requestCreateOrder(
+      token.token,
+      input,
+      this.config
+    );
+    if (!response) return;
+    return this.createCheckoutUrl(response.data.biz_content.prepay_id);
+  }
+  async queryOrder(input) {
+    let token = await this.getFabricToken();
+    if (!token) return;
+    const response = await requestQueryOrder(
+      token.token,
+      input,
+      this.config
+    );
+    return response.data;
+  }
+  async refundOrder(input) {
+    const token = await this.getFabricToken();
+    if (!token) return;
+    const response = await requestRefund(token.token, input, this.config);
+    return response.data;
+  }
+  static TOKEN_EXPIRY_SAFETY_WINDOW_MS = 5 * 60 * 1e3;
+  isTokenExpired(token) {
+    if (!token) {
+      return true;
+    }
+    const now = Date.now();
+    const expiry = this.parseTelebirrDate(token.expirationDate).getTime();
+    return now >= expiry - _TelebirrClient.TOKEN_EXPIRY_SAFETY_WINDOW_MS;
+  }
+  parseTelebirrDate(value) {
+    const year = Number(value.slice(0, 4));
+    const month = Number(value.slice(4, 6)) - 1;
+    const day = Number(value.slice(6, 8));
+    const hour = Number(value.slice(8, 10));
+    const minute = Number(value.slice(10, 12));
+    const second = Number(value.slice(12, 14));
+    return new Date(Date.UTC(year, month, day, hour, minute, second));
+  }
+};
+export {
+  TelebirrClient,
+  generateKeys
+};
+//# sourceMappingURL=index.js.map