telebirr-nodejs 1.0.4 → 1.0.6

package/README.md

@@ -10,173 +10,194 @@ A simple, opinionated Node.js SDK for integrating **Telebirr C2B payments** with
 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
-| Name | Description |
+---
+
+### Required Credentials
+
+| Name                   | Description                  |
 | ---------------------- | ---------------------------- |
-| `FABRIC_APP_ID` | Fabric application ID |
-| `FABRIC_APP_SECRET` | Fabric application secret |
-| `MERCHANT_APP_ID` | Merchant application ID |
-| `MERCHANT_CODE` | Merchant code |
+| `FABRIC_APP_ID`        | Fabric application ID        |
+| `FABRIC_APP_SECRET`    | Fabric application secret    |
+| `MERCHANT_APP_ID`      | Merchant application ID      |
+| `MERCHANT_CODE`        | Merchant code                |
 | `MERCHANT_PRIVATE_KEY` | RSA private key (PEM string) |
 
-Required URLs
-| Name | Description |
+---
+
+### Required URLs
+
+| Name                    | Description                     |
 | ----------------------- | ------------------------------- |
-| `TELEBIRR_NOTIFY_URL` | Server-to-server callback URL |
+| `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
+1. POST /payment/initiate
+2. GET /payment/status/:merchOrderId
+3. POST /payment/refund
 
-GET /payment/status/:merchOrderId
+---
 
-POST /payment/refund
+### 1 Initiate Payment
 
-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);
 });
-
 ```
 
 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);
 });
 ```
 
-Refund Payment
+Please refer to Telebirr’s official documentation to correctly handle the query order json response:
+https://developer.ethiotelecom.et/docs/H5%20C2B%20Web%20Payment%20Integration%20Quick%20Guide/queryOrder
+
+---
+
+### 3 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);
-});
+    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
+Please refer to Telebirr’s official documentation to correctly handle the refund order json response:
+https://developer.ethiotelecom.et/docs/H5%20C2B%20Web%20Payment%20Integration%20Quick%20Guide/RefundOrder
+
+---
 
-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.
-
-For real testing, use Telebirr’s sandbox mode and whitelist your public IP address in the Telebirr portal.
-
-Supported Features
-Fabric token handling
-
-RSA-SHA256 request signing
+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.
 
-C2B checkout
-
-Order query
+---
 
-Refunds
+### Supported Features
 
-Simulator support
+- Fabric token handling
+- RSA-SHA256 request signing
+- C2B checkout
+- Order query
+- Refunds
+- Simulator support
+- Notify URL Handling
 
-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,
-});
+    generateKeys({
+        dir: process.cwd(),
+        privateKeyName: "telefy_private.pem",
+        publicKeyName: "telefy_public.pem",
+        overwrite: false,
+    });
 
 ```
 

package/package.json

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