telebirr-nodejs 1.0.3 → 1.0.5

package/README.md

@@ -8,11 +8,15 @@ A simple, opinionated Node.js SDK for integrating **Telebirr C2B payments** with
 
 ```bash
 npm install telebirr-nodejs
-Required Configuration
+```
+
+## Required Configuration
+
 Telebirr requires credentials and callback URLs.
 You should never hard-code secrets. Always load them from process.env.
 
-Required Credentials
+### Required Credentials
+
 | Name                   | Description                  |
 | ---------------------- | ---------------------------- |
 | `FABRIC_APP_ID`        | Fabric application ID        |
@@ -21,171 +25,151 @@ Required Credentials
 | `MERCHANT_CODE`        | Merchant code                |
 | `MERCHANT_PRIVATE_KEY` | RSA private key (PEM string) |
 
+### Required URLs
 
-Required URLs
 | Name                    | Description                     |
 | ----------------------- | ------------------------------- |
 | `TELEBIRR_NOTIFY_URL`   | Server-to-server callback URL   |
 | `TELEBIRR_REDIRECT_URL` | User redirect URL after payment |
 
+### Basic Setup
 
-Basic Setup
+```bash
 import { TelebirrClient } from "telebirr-nodejs";
 
 const client = new TelebirrClient({
   mode: "sandbox", // "simulate" | "sandbox" | "production"
-
   appId: process.env.FABRIC_APP_ID!,
   appSecret: process.env.FABRIC_APP_SECRET!,
-
   merchantAppId: process.env.MERCHANT_APP_ID!,
   merchantCode: process.env.MERCHANT_CODE!,
   privateKey: process.env.MERCHANT_PRIVATE_KEY!,
-
   notifyUrl: process.env.TELEBIRR_NOTIFY_URL!,
   redirectUrl: process.env.TELEBIRR_REDIRECT_URL!,
-
   http: true, // allow HTTP in simulator mode
   IntegrationOption: "C2B",
 });
+```
 
+### Important
 
-
-Important
 MERCHANT_PRIVATE_KEY must be the full PEM string, including:
 
+```bash
 -----BEGIN RSA PRIVATE KEY-----
 ...
 -----END RSA PRIVATE KEY-----
+```
 
-
-Example API Routes
+### Example API Routes
 
 Below is a complete demo using three routes:
 
 POST /payment/initiate
-
 GET /payment/status/:merchOrderId
-
 POST /payment/refund
 
-Initiate Payment
+### 1 Initiate Payment
+
 Creates an order and redirects the user to the Telebirr checkout page.
 
+```bash
 app.post("/payment/initiate", async (req, res) => {
-  const checkoutUrl = await client.preOrder({
-    merchOrderId: "order123",
-    title: "Phone",
-    amount: "12",
-    callbackInfo: "from web checkout",
-  });
-
-  res.redirect(checkoutUrl);
+    const checkoutUrl = await client.preOrder({
+            merchOrderId: "order123",
+            title: "Phone",
+            amount: "12",
+            callbackInfo: "from web checkout",
+        });
+
+    res.redirect(checkoutUrl);
 });
-
-
-What happens internally
-
-Fabric token is fetched and cached
-
-Order is signed and created
-
-Checkout URL is generated
-
-User is redirected to Telebirr
+```
 
 If you are using a frontend framework (for example React) and do not want to lose application state, return the checkout URL as JSON and let the frontend handle the redirection.
 
-Query Payment Status
+### 2 Query Payment Status
+
 Used to check the payment result using the merchant order ID.
 
+```bash
 app.get("/payment/status/:merchOrderId", async (req, res) => {
-  const { merchOrderId } = req.params;
+    const { merchOrderId } = req.body;
 
-  const info = await client.queryOrder(merchOrderId);
+    const info = await client.queryOrder(merchOrderId);
 
-  res.json(info);
+    res.json(info);
 });
+```
 
+### 3 Refund Payment
 
-Typical Use Cases
-Payment confirmation pages
-
-Background reconciliation jobs
-
-Admin dashboards
-
-Refund Payment
 Refunds a completed transaction.
 
+```bash
 app.post("/payment/refund", async (req, res) => {
-  const refundData = await client.refundOrder({
-    merchOrderId: "order123",
-    refundRequestNo: "original-transaction-id",
-    refundReason: "customer request",
-    amount: "12",
-  });
-
-  res.json(refundData);
-});
 
-Notes
-refundRequestNo must be unique
+    const refundData = await client.refundOrder({
+        merchOrderId: "order123",
+        refundRequestNo: "original-transaction-id",
+        refundReason: "customer request",
+        amount: "12",
+    });
+
+    res.json(refundData);
+});
+```
 
 Refund amount must not exceed the original payment amount
 
-Simulator Mode
+### Simulator Mode
 
 To use the simulator provided by this package, set the mode to simulate.
 
+```bash
 import { TelebirrClient } from "telebirr-nodejs";
 
-const client = new TelebirrClient({
-  mode: "simulate",
-  notifyUrl: "https://example.com/notify",
-  redirectUrl: "https://example.com/redirect",
-  http: true,
-  IntegrationOption: "C2B",
-});
-
+    const client = new TelebirrClient({
+            mode: "simulate",
+            notifyUrl: "https://example.com/notify",
+            redirectUrl: "https://example.com/redirect",
+            http: true,
+            IntegrationOption: "C2B",
+        });
+```
 
 This simulator is for learning and development purposes only.
-The simulation server is provided by this package, not by Telebirr.
+The simulation server is provided by this package, not by Telebirr. For real testing, use Telebirr’s sandbox mode and whitelist your public IP address in the Telebirr portal.
 
-For real testing, use Telebirr’s sandbox mode and whitelist your public IP address in the Telebirr portal.
+### Supported Features
 
-Supported Features
 Fabric token handling
-
 RSA-SHA256 request signing
-
 C2B checkout
-
 Order query
-
 Refunds
-
 Simulator support
-
 Notify URL Handling
+
 Please refer to Telebirr’s official documentation to correctly handle notify callbacks:
 
 https://developer.ethiotelecom.et/docs/H5%20C2B%20Web%20Payment%20Integration%20Quick%20Guide/Notify_Callback
 
-RSA Key Generation
+### RSA Key Generation
+
 You can generate private and public keys instantly.
 
+```bash
 import { generateKeys } from "telebirr-nodejs";
 
 generateKeys({
-  dir: process.cwd(),
-  privateKeyName: "telefy_private.pem",
-  publicKeyName: "telefy_public.pem",
-  overwrite: false,
+    dir: process.cwd(),
+    privateKeyName: "telefy_private.pem",
+    publicKeyName: "telefy_public.pem",
+    overwrite: false,
 });
-
+```
 
 This will generate two .pem files in your root directory.
 
 The merchantPrivateKey option always accepts a string, so you must read the private key file using Node.js fs and pass the value to the client configuration.
-```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "telebirr-nodejs",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Unofficial Telebirr Node.js SDK.",
   "type": "module",
   "main": "./dist/index.cjs",