blaaiz-nodejs-sdk 1.1.2 → 1.2.0

package/README.md

@@ -286,12 +286,17 @@ const payout = await blaaiz.payouts.initiate({
   to_currency_id: "NGN",
   bank_id: "bank-id", // Required for NGN
   account_number: "0123456789",
-  phone_number: "+2348012345678" // Optional
+  phone_number: "+2348012345678", // Optional
+  note: "Acme Ltd" // Optional — appears in the transaction description; defaults to business name
 });
 
 console.log('Payout Status:', payout.data.transaction.status);
 ```
 
+#### Passing additional fields
+
+`payouts.initiate()` forwards the entire payload verbatim to the API, so any field documented in the [Blaaiz API reference](https://docs.business.blaaiz.com) can be included even if it isn't listed in this README. For example, `note` sets the transaction description (defaulting to the business name when omitted). This means the SDK stays compatible with new API fields without requiring an update here.
+
 #### Bank Transfer Payout (GBP)
 
 ```javascript
@@ -691,6 +696,8 @@ The Blaaiz API has a rate limit of 100 requests per minute. The SDK automaticall
 
 The SDK provides built-in webhook signature verification to ensure webhook authenticity. The signature is computed using HMAC-SHA256 with the format `timestamp.payload`.
 
+> **Important:** `payload` must be the **raw request body string** exactly as received. Do not pass a parsed object — parsing and re-serializing (e.g. `JSON.stringify`) changes the bytes and will break signature verification. Capture the raw body with `express.raw({ type: 'application/json' })` and pass `req.body.toString()` (see the Express example below).
+
 ```javascript
 const { Blaaiz } = require('blaaiz-nodejs-sdk');
 
@@ -698,7 +705,7 @@ const blaaiz = new Blaaiz('your-api-key');
 
 // Method 1: Verify signature manually
 const isValid = blaaiz.webhooks.verifySignature(
-  payload,        // Raw webhook payload (string or object)
+  payload,        // Raw request body string (do not pass a parsed object)
   signature,      // Signature from webhook headers (x-blaaiz-signature)
   timestamp,      // Timestamp from webhook headers (x-blaaiz-timestamp)
   webhookSecret   // Your webhook secret key
@@ -713,7 +720,7 @@ if (isValid) {
 // Method 2: Construct verified event (recommended)
 try {
   const event = blaaiz.webhooks.constructEvent(
-    payload,        // Raw webhook payload
+    payload,        // Raw request body string (do not pass a parsed object)
     signature,      // Signature from webhook headers
     timestamp,      // Timestamp from webhook headers
     webhookSecret   // Your webhook secret key

package/index.d.ts

@@ -139,6 +139,7 @@ export interface PayoutData {
   wallet_address?: string;
   wallet_network?: string;
   wallet_token?: string;
+  note?: string;
 }
 
 export interface PayoutResponse {
@@ -347,8 +348,8 @@ export declare class WebhookService {
   get(): Promise<BlaaizResponse<WebhookData>>;
   update(webhookData: Partial<WebhookData>): Promise<BlaaizResponse<any>>;
   replay(replayData: WebhookReplayData): Promise<BlaaizResponse<any>>;
-  verifySignature(payload: string | object, signature: string, secret: string): boolean;
-  constructEvent(payload: string | object, signature: string, secret: string): WebhookEvent;
+  verifySignature(payload: string, signature: string, timestamp: string, secret: string): boolean;
+  constructEvent(payload: string, signature: string, timestamp: string, secret: string): WebhookEvent;
 }
 
 // Main SDK Class

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blaaiz-nodejs-sdk",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Official Node.js SDK for Blaaiz RaaS (Remittance as a Service) API",
   "main": "index.js",
   "types": "index.d.ts",

package/src/services/WebhookService.js

@@ -54,13 +54,16 @@ class WebhookService {
       throw new Error('Webhook secret is required for signature verification')
     }
 
-    const crypto = require('crypto')
+    // The payload must be the raw request body string. Parsing and
+    // re-serializing an object changes the bytes and breaks verification.
+    if (typeof payload !== 'string') {
+      throw new Error('Webhook payload must be the raw request body string. Do not pass a parsed object — parsing and re-serializing changes the bytes and breaks signature verification. Use the raw body (e.g. express.raw({ type: "application/json" }) then req.body.toString()).')
+    }
 
-    // Convert payload to string if it's an object
-    const payloadString = typeof payload === 'string' ? payload : JSON.stringify(payload)
+    const crypto = require('crypto')
 
     // Create signed payload with timestamp
-    const signedPayload = `${timestamp}.${payloadString}`
+    const signedPayload = `${timestamp}.${payload}`
 
     // Create HMAC signature
     const expectedSignature = crypto