telebirr-nodejs 1.0.5 → 1.0.7

package/README.md

@@ -10,20 +10,26 @@ A simple, opinionated Node.js SDK for integrating **Telebirr C2B payments** with
 npm install telebirr-nodejs
 ```
 
+---
+
 ## Required Configuration
 
 Telebirr requires credentials and callback URLs.
 You should never hard-code secrets. Always load them from process.env.
 
+---
+
 ### 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                |
-| `MERCHANT_PRIVATE_KEY` | RSA private key (PEM string) |
+| Name                   | Description                                                                            |
+| ---------------------- | -------------------------------------------------------------------------------------- |
+| `FABRIC_APP_ID`        | Fabric application ID (c4182ef8-9249-458a-985e-06d191f4d505 uuid-v4 string)            |
+| `FABRIC_APP_SECRET`    | Fabric application secret ("fad0f06383c6297f54rr78694b974599" 32 hex character string) |
+| `MERCHANT_APP_ID`      | Merchant application ID (7606201678956824 16 integer character string)                 |
+| `MERCHANT_CODE`        | Merchant code ("000000" 6 integer character string)                                    |
+| `MERCHANT_PRIVATE_KEY` | RSA private key (PEM string)                                                           |
+
+---
 
 ### Required URLs
 
@@ -32,8 +38,12 @@ You should never hard-code secrets. Always load them from process.env.
 | `TELEBIRR_NOTIFY_URL`   | Server-to-server callback URL   |
 | `TELEBIRR_REDIRECT_URL` | User redirect URL after payment |
 
+---
+
 ### Basic Setup
 
+---
+
 ```bash
 import { TelebirrClient } from "telebirr-nodejs";
 
@@ -43,7 +53,7 @@ const client = new TelebirrClient({
   appSecret: process.env.FABRIC_APP_SECRET!,
   merchantAppId: process.env.MERCHANT_APP_ID!,
   merchantCode: process.env.MERCHANT_CODE!,
-  privateKey: process.env.MERCHANT_PRIVATE_KEY!,
+  merchantPrivateKey: process.env.MERCHANT_PRIVATE_KEY!,
   notifyUrl: process.env.TELEBIRR_NOTIFY_URL!,
   redirectUrl: process.env.TELEBIRR_REDIRECT_URL!,
   http: true, // allow HTTP in simulator mode
@@ -51,6 +61,8 @@ const client = new TelebirrClient({
 });
 ```
 
+---
+
 ### Important
 
 MERCHANT_PRIVATE_KEY must be the full PEM string, including:
@@ -61,26 +73,28 @@ MERCHANT_PRIVATE_KEY must be the full PEM string, including:
 -----END RSA PRIVATE KEY-----
 ```
 
+---
+
 ### Example API Routes
 
-Below is a complete demo using three routes:
+1. POST /payment/initiate
+2. GET /payment/status
+3. POST /payment/refund
 
-POST /payment/initiate
-GET /payment/status/:merchOrderId
-POST /payment/refund
+---
 
-### 1 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",
-        });
+        merchOrderId: "order123",
+        title: "Phone",
+        amount: "12",
+        callbackInfo: "from web checkout",
+    });
 
     res.redirect(checkoutUrl);
 });
@@ -88,7 +102,9 @@ app.post("/payment/initiate", async (req, res) => {
 
 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.
 
-### 2 Query Payment Status
+---
+
+### 2. Query Payment Status
 
 Used to check the payment result using the merchant order ID.
 
@@ -102,7 +118,12 @@ app.get("/payment/status/:merchOrderId", async (req, res) => {
 });
 ```
 
-### 3 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.
 
@@ -117,10 +138,14 @@ app.post("/payment/refund", async (req, res) => {
     });
 
     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
 
@@ -129,32 +154,37 @@ 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
-C2B checkout
-Order query
-Refunds
-Simulator support
-Notify URL Handling
+- 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
 
 You can generate private and public keys instantly.
@@ -168,6 +198,7 @@ generateKeys({
     publicKeyName: "telefy_public.pem",
     overwrite: false,
 });
+
 ```
 
 This will generate two .pem files in your root directory.

package/package.json

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