@crediblemark/buayar 0.8.4 → 0.8.6

package/dist/index.mjs

@@ -1638,7 +1638,7 @@ var IpaymuProvider = class extends BasePaymentProvider {
       payload = {
         name: customer.name,
         email: customer.email,
-        phone: customer.phone || "081234567890",
+        ...customer.phone ? { phone: customer.phone } : {},
         amount: integerAmount,
         notifyUrl,
         expired: 24,
@@ -1669,7 +1669,7 @@ var IpaymuProvider = class extends BasePaymentProvider {
         referenceId: orderId,
         buyerName: customer.name,
         buyerEmail: customer.email,
-        buyerPhone: customer.phone || "081234567890",
+        ...customer.phone ? { buyerPhone: customer.phone } : {},
         ...feeDirection ? { feeDirection } : {},
         ...escrow !== void 0 ? { escrow } : {},
         ...subAccount ? { account: subAccount } : {},
@@ -1899,6 +1899,28 @@ var IpaymuProvider = class extends BasePaymentProvider {
       };
     }
   }
+  async probePaymentMethods(config) {
+    try {
+      const res = await this.getPaymentMethods({ amount: 1e4 }, config);
+      if (res.success && res.methods) {
+        return {
+          success: true,
+          enabled: res.methods.map((m) => m.paymentMethod)
+        };
+      }
+      return {
+        success: false,
+        enabled: [],
+        error: res.error || "Failed to probe iPaymu payment methods"
+      };
+    } catch (e) {
+      return {
+        success: false,
+        enabled: [],
+        error: e.message || "Failed to probe iPaymu payment methods"
+      };
+    }
+  }
   async checkTransaction(params, config) {
     const { merchantOrderId } = params;
     const va = config.merchantCode || config.merchantId || "";
@@ -2186,8 +2208,8 @@ var XenditProvider = class extends BasePaymentProvider {
     const status = isPaid ? "paid" : isPending ? "pending" : isExpired ? "expired" : "failed";
     const webhookToken = config.extra?.webhookToken;
     const headerToken = config.extra?.callbackToken || config.extra?.headers?.["x-callback-token"] || config.extra?.headers?.["X-Callback-Token"];
-    let isValid = true;
-    if (webhookToken || headerToken) {
+    let isValid = false;
+    if (webhookToken && headerToken) {
       isValid = verifyXenditWebhookToken(headerToken, webhookToken);
     }
     return {
@@ -2335,6 +2357,75 @@ var XenditProvider = class extends BasePaymentProvider {
         category: "Paylater / Cicilan"
       }
     ];
+    const apiKey = config.apiKey || config.serverKey || config.secretKey || "";
+    if (apiKey) {
+      try {
+        const authHeader = getXenditAuthHeader(apiKey);
+        const response = await fetch(`${this.getBaseUrl()}/payment_channels`, {
+          method: "GET",
+          headers: {
+            "Authorization": authHeader,
+            "Content-Type": "application/json"
+          }
+        });
+        if (response.ok) {
+          const channels = await response.json();
+          if (Array.isArray(channels) && channels.length > 0) {
+            const dynamicMethods = [];
+            for (const ch of channels) {
+              if (ch.status && ch.status !== "ACTIVE") continue;
+              const codeLower = (ch.channel_code || "").toLowerCase();
+              let canonicalCode = codeLower;
+              let category = "Virtual Account";
+              if (ch.type === "BANK_TRANSFER" || codeLower.endsWith("_va") || ["bca", "bni", "bri", "mandiri", "permata", "cimb", "bsi"].includes(codeLower)) {
+                canonicalCode = codeLower.endsWith("_va") ? codeLower : `${codeLower}_va`;
+                category = "Virtual Account";
+              } else if (ch.type === "EWALLET" || ["ovo", "dana", "linkaja", "shopeepay", "gopay"].includes(codeLower)) {
+                canonicalCode = codeLower;
+                category = "E-Wallet";
+              } else if (ch.type === "QR_CODE" || codeLower === "qris") {
+                canonicalCode = "qris";
+                category = "QRIS";
+              } else if (ch.type === "RETAIL_OUTLET" || ["alfamart", "indomaret"].includes(codeLower)) {
+                canonicalCode = codeLower;
+                category = "Retail / Gerai";
+              } else if (ch.type === "CARD") {
+                canonicalCode = "credit_card";
+                category = "Kartu Kredit";
+              } else if (ch.type === "PAYLATER" || ["kredivo", "akulaku", "indodana"].includes(codeLower)) {
+                canonicalCode = codeLower;
+                category = "Paylater / Cicilan";
+              }
+              dynamicMethods.push({
+                paymentMethod: canonicalCode,
+                code: ch.channel_code || canonicalCode,
+                paymentName: ch.display_name || ch.name || ch.channel_code,
+                paymentImage: `https://xendit.co/icons/${codeLower}.png`,
+                totalFee: ch.fee ? `${ch.fee}` : "",
+                category,
+                coming_soon: false,
+                extra: ch
+              });
+            }
+            if (dynamicMethods.length > 0) {
+              const categories2 = {};
+              for (const item of dynamicMethods) {
+                if (!categories2[item.category]) categories2[item.category] = [];
+                categories2[item.category].push(item);
+              }
+              return {
+                success: true,
+                provider: "xendit",
+                methods: dynamicMethods,
+                categories: categories2,
+                rawResponse: channels
+              };
+            }
+          }
+        }
+      } catch (e) {
+      }
+    }
     const categories = {};
     for (const item of staticMethods) {
       if (!categories[item.category]) {
@@ -2350,6 +2441,28 @@ var XenditProvider = class extends BasePaymentProvider {
       rawResponse: staticMethods
     };
   }
+  async probePaymentMethods(config) {
+    try {
+      const res = await this.getPaymentMethods({ amount: 1e4 }, config);
+      if (res.success && res.methods) {
+        return {
+          success: true,
+          enabled: res.methods.map((m) => m.paymentMethod)
+        };
+      }
+      return {
+        success: false,
+        enabled: [],
+        error: res.error || "Failed to probe Xendit payment methods"
+      };
+    } catch (e) {
+      return {
+        success: false,
+        enabled: [],
+        error: e.message || "Failed to probe Xendit payment methods"
+      };
+    }
+  }
   async checkTransaction(params, config) {
     const { merchantOrderId } = params;
     const apiKey = config.apiKey || config.serverKey || config.secretKey || "";
@@ -3146,7 +3259,7 @@ var DokuProvider = class extends BasePaymentProvider {
     const secretKey = config.secretKey || config.apiKey || "";
     const signature = headers["signature"] || headers["Signature"] || config.extra?.dokuSignature || config.extra?.signatureHeader;
     const clientId = config.merchantCode || config.clientKey || "";
-    let isValid = true;
+    let isValid = false;
     if (signature || headers && (headers["request-id"] || headers["Request-Id"])) {
       isValid = verifyDokuWebhookSignature(headers, body, clientId, secretKey);
     }
@@ -3171,7 +3284,7 @@ var DokuProvider = class extends BasePaymentProvider {
   verifySnapCallback(body, config, headers) {
     const clientSecret = config.apiKey || config.serverKey || config.secretKey || "";
     const endpointUrl = config.extra?.notificationPath || headers["x-path"] || config.extra?.headers?.["request-target"] || "/api/payment/webhook";
-    let isValid = true;
+    let isValid = false;
     const incomingSig = headers["x-signature"] || headers["X-SIGNATURE"] || headers["signature"] || headers["Signature"] || "";
     if (incomingSig && clientSecret) {
       isValid = verifySnapWebhookSignature(headers, body, clientSecret, endpointUrl);
@@ -9499,6 +9612,18 @@ var PaymentManager = class {
     if (provider.probePaymentMethods) {
       return provider.probePaymentMethods(config);
     }
+    try {
+      if (typeof provider.getPaymentMethods === "function") {
+        const res = await provider.getPaymentMethods({ amount: 1e4 }, config);
+        if (res && res.success && Array.isArray(res.methods) && res.methods.length > 0) {
+          return {
+            success: true,
+            enabled: res.methods.map((m) => m.paymentMethod)
+          };
+        }
+      }
+    } catch (e) {
+    }
     return { success: false, enabled: [], error: `Provider '${providerName}' does not support payment methods probing` };
   }
   // ─── Unified Advanced Operations (Refund / Balance / Disburse) ─────────────
@@ -9682,6 +9807,80 @@ var PaymentManager = class {
 };
 var paymentManager = new PaymentManager();
 
+// src/core/descriptor.ts
+function mapCategoryToDescriptorType(category, paymentMethod) {
+  const cat = (category || "").toLowerCase();
+  const method = (paymentMethod || "").toLowerCase();
+  const isVa = cat === "virtual account" || method.includes("_va");
+  const isQr = cat === "qris" || method === "qris";
+  const isEwallet = cat === "e-wallet" || cat === "ewallet" || method === "ewallet";
+  const isRetail = cat === "retail / gerai" || cat === "cstore" || method === "cstore";
+  const isCard = cat === "kartu kredit" || cat === "cc";
+  const isPaylater = cat === "paylater / cicilan" || cat === "paylater" || method === "paylater";
+  if (isQr) return "qris";
+  if (isVa) return "va";
+  if (isEwallet) return "ewallet";
+  if (isRetail) return "retail";
+  if (isCard) return "card";
+  if (isPaylater) return "paylater";
+  return "other";
+}
+function iconForType(type) {
+  switch (type) {
+    case "qris":
+    case "ewallet":
+      return "\u{1F4F1}";
+    case "va":
+      return "\u{1F3E6}";
+    case "retail":
+      return "\u{1F3EA}";
+    case "card":
+    case "paylater":
+    default:
+      return "\u{1F4B3}";
+  }
+}
+function badgeForType(type) {
+  switch (type) {
+    case "qris":
+      return "Instan Bebas Biaya";
+    case "va":
+      return "Otomatis 24 Jam";
+    case "ewallet":
+      return "E-Wallet Instan";
+    case "retail":
+      return "Gerai Retail";
+    case "card":
+      return "Visa / Mastercard";
+    case "paylater":
+      return "Cicilan PayLater";
+    default:
+      return "Tersedia Otomatis";
+  }
+}
+function buildPaymentMethodDescriptor(pm, _providerName) {
+  const category = pm.category || "";
+  const code = (pm.code || pm.paymentMethod || "").toUpperCase();
+  const type = mapCategoryToDescriptorType(category, pm.paymentMethod);
+  const icon = iconForType(type);
+  let badge = badgeForType(type);
+  const feeDisplay = pm.totalFee && pm.totalFee !== "-" ? pm.totalFee : "";
+  return {
+    id: code,
+    name: pm.paymentName,
+    type,
+    icon,
+    badge: feeDisplay ? `${badge} \u2022 Fee ${feeDisplay}` : badge,
+    image: pm.paymentImage || void 0,
+    category,
+    coming_soon: pm.coming_soon ?? false,
+    totalFee: feeDisplay || void 0
+  };
+}
+function buildPaymentMethodDescriptors(methods, providerName) {
+  return methods.map((pm) => buildPaymentMethodDescriptor(pm, providerName));
+}
+
 // src/core/providerRegistry.ts
 var ProviderRegistry = class {
   descriptors = /* @__PURE__ */ new Map();
@@ -9724,10 +9923,26 @@ var ProviderRegistry = class {
     return ties.length === 1 ? top.name : void 0;
   }
   /**
-   * Autodetect provider dari struktur payload webhook.
+   * Autodetect provider dari struktur payload webhook dan header.
    * Mengembalikan nama provider jika dikenali, else undefined.
    */
-  detectFromWebhook(payload) {
+  detectFromWebhook(payload, headers) {
+    if (headers) {
+      const h = {};
+      for (const k of Object.keys(headers)) {
+        h[k.toLowerCase()] = headers[k];
+      }
+      if (h["stripe-signature"]) return "stripe";
+      if (h["x-callback-token"]) return "xendit";
+      if (h["x-razorpay-signature"]) return "razorpay";
+      if (h["cko-signature"]) return "checkoutcom";
+      if (h["openpayu-signature"]) return "payu";
+      if (h["x-square-hmacsha256-signature"] || h["x-square-signature"]) return "square";
+      if (h["bt_signature"]) return "braintree";
+      if (h["x-oy-username"]) return "oy";
+      if (h["signature"] && (h["client-id"] || h["request-id"])) return "doku";
+      if (h["x-signature"] && (payload?.trx_id || payload?.via || payload?.sid)) return "ipaymu";
+    }
     if (!payload) return void 0;
     const p = payload;
     if (p.signature_key && p.transaction_status) return "midtrans";
@@ -9741,7 +9956,9 @@ var ProviderRegistry = class {
     if (p.merchant_id && p.order_id && p.signature) return "prismalink";
     if (p.object === "event" || p.type && p.data?.object && p.api_version) return "stripe";
     if (p.event && p.payload?.payment?.entity) return "razorpay";
-    if (p.external_id || p.event?.startsWith("payment.") || p.event?.startsWith("qr.") || p.data?.reference_id) return "xendit";
+    if (p.external_id && (p.status || p.paid_amount || p.payment_method || p.payment_channel || p.id) || p.event?.startsWith("payment.") || p.event?.startsWith("qr.") || p.data?.reference_id) {
+      return "xendit";
+    }
     if (p.event_type && p.resource && (p.event_type.startsWith("PAYMENT.") || p.event_type.startsWith("CHECKOUT.ORDER."))) return "paypal";
     if (p.notificationItems || p.merchantAccountCode && p.pspReference && p.eventCode) return "adyen";
     if (p.type && p.data?._links && (p.type.startsWith("payment_") || p.type.startsWith("refund_"))) return "checkoutcom";
@@ -10095,10 +10312,10 @@ var Buayar = class {
     return { methods: desc.methods, operations: desc.operations };
   }
   /**
-   * Deteksi nama provider dari struktur payload webhook.
+   * Deteksi nama provider dari struktur payload webhook dan opsional headers.
    */
-  detectProviderFromPayload(payload) {
-    return this.registry.detectFromWebhook(payload);
+  detectProviderFromPayload(payload, headers) {
+    return this.registry.detectFromWebhook(payload, headers);
   }
   /**
    * Deteksi nama provider aktif dari variabel lingkungan (kredensial yang terisi).
@@ -10143,6 +10360,33 @@ var Buayar = class {
     const providerName = configOverride?.provider || this.provider;
     return this.manager.getPaymentMethods(providerName, params || { amount: 1e4 }, mergedConfig);
   }
+  /**
+   * Ambil daftar channel pembayaran aktif dalam bentuk deskriptor kanonikal
+   * siap-render (id, name, type, icon, badge, image, category, totalFee).
+   * Wrapper di atas {@link Buayar.getPaymentMethods} + `buildPaymentMethodDescriptors`,
+   * sehingga konsumen UI/snapshot tidak perlu melakukan mapping ulang per provider.
+   */
+  async getPaymentMethodDescriptors(params, configOverride) {
+    const mergedConfig = { ...this.config, ...configOverride };
+    const providerName = configOverride?.provider || this.provider;
+    const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const res = await this.manager.getPaymentMethods(providerName, params || { amount: 1e4 }, mergedConfig);
+    if (!res.success) {
+      return {
+        success: false,
+        provider: providerName,
+        descriptors: [],
+        error: res.error || "Failed to fetch payment methods",
+        generatedAt
+      };
+    }
+    return {
+      success: true,
+      provider: providerName,
+      descriptors: buildPaymentMethodDescriptors(res.methods, providerName),
+      generatedAt
+    };
+  }
   /**
    * Cek status transaksi pembayaran berdasarkan Order ID
    */
@@ -10200,14 +10444,39 @@ var Buayar = class {
         mergedConfig.extra.oyUsername = Array.isArray(oyUser) ? oyUser[0] : oyUser;
       }
     }
-    let providerName = configOverride?.provider || this.provider;
-    const detected = this.registry.detectFromWebhook(payload);
-    if (detected) providerName = detected;
+    let providerName = configOverride?.provider !== void 0 ? configOverride.provider : this.provider;
+    if (!providerName) {
+      const detected = this.registry.detectFromWebhook(payload, headers);
+      if (detected) providerName = detected;
+    }
+    if (!providerName) {
+      return {
+        isValid: false,
+        isPaid: false,
+        isPending: false,
+        isFailed: true,
+        isExpired: false,
+        status: "failed",
+        orderId: "",
+        amount: 0,
+        provider: "unknown",
+        error: "Unable to detect payment provider for webhook. Please specify provider in configuration or override.",
+        rawPayload: payload
+      };
+    }
     return this.manager.verifyCallback(providerName, payload, mergedConfig);
   }
   async handleWebhook(payload, headers, configOverride) {
     return this.verifyWebhook(payload, headers, configOverride);
   }
+  /**
+   * Probe payment methods yang benar-benar aktif di akun merchant gateway.
+   */
+  async probePaymentMethods(configOverride) {
+    const mergedConfig = { ...this.config, ...configOverride };
+    const providerName = configOverride?.provider || this.provider;
+    return this.manager.probePaymentMethods(providerName, mergedConfig);
+  }
   /**
    * Unified Refund — berlaku untuk semua provider yang mendukung refund.
    * Provider tanpa fitur refund mengembalikan `{ supported: false }`, bukan error.
@@ -10361,6 +10630,8 @@ export {
   buildCoreChargePayload,
   buildDefaultDescriptors,
   buildIpaymuCallbackString,
+  buildPaymentMethodDescriptor,
+  buildPaymentMethodDescriptors,
   buildPaypalBasicAuth,
   buildPayuBasicAuth,
   buildRazorpayBasicAuth,
@@ -10381,6 +10652,7 @@ export {
   getPaymentMethodCategory,
   getXenditAuthHeader,
   hmacSha256,
+  mapCategoryToDescriptorType,
   md5,
   minifyJson,
   normalizeIpaymuCallback,

package/docs/AUDIT-BUG-DAN-PREMATURE.md

@@ -0,0 +1,166 @@
+# Audit Bug & Fitur Premature — SDK Buayar v0.8.5
+
+> **Repo:** `/Buayar` (package `@crediblemark/buayar`, versi 0.8.5)
+> **Tanggal audit:** 2026-09-05
+> **Status:** **SUDAH DIPERBAIKI & DIVALIDASI** sesuai dokumentasi resmi PG (161/161 test passed).
+
+Laporan ini merangkum bug dan bagian "premature" (fitur yang tampak tersedia di API/types namun
+perilaku aktualnya belum lengkap/benar) yang ditemukan saat menelusuri SDK, termasuk dampaknya bagi
+konsumen utama SDK: aplikasi **SitusBisnis** (`BUAYAR_PROVIDER=ipaymu`, sandbox).
+Seluruh temuan critical (S1, S2) dan high (S3, S4, S5, S6) telah ditangani dan divalidasi dengan dokumentasi resmi PG.
+
+---
+
+## I. Ringkasan Eksekutif & Status Perbaikan
+
+| # | Severity | Jenis | Lokasi | Ringkasan Masalah | Status Perbaikan |
+|---|:--:|---|---|---|:---:|
+| S1 | 🔴 Critical | Bug keamanan | `providers/doku/provider.ts:524` & `:561` | `verifyCallback` & `verifySnapCallback` default `isValid = true` bila tanpa signature | ✅ **FIXED** (default `isValid = false`, wajib valid signature) |
+| S2 | 🔴 Critical | Bug keamanan | `providers/xendit/provider.ts:242` | `verifyCallback` default `isValid = true` bila tanpa token | ✅ **FIXED** (default `isValid = false`, wajib match token) |
+| S3 | 🟠 High | Bug kontrak | `providers/ipaymu/provider.ts:50,84` | `phone` di-fallback ke string hardcode `"081234567890"` | ✅ **FIXED** (phone dijadikan opsional per docs resmi iPaymu) |
+| S4 | 🟠 High | Risk integrasi | `providers/ipaymu/provider.ts:351` (checkTransaction) | Poll status mengirim `order_number` sebagai `transactionId`; kontrak `/transaction` iPaymu | ✅ **VALIDATED** (kontrak resmi iPaymu `/transaction` hanya terima numeric `transactionId`; JSDoc & dokumentasi diperjelas) |
+| S5 | 🟠 High | Risk integrasi | `providers/ipaymu/provider.ts:190` | `orderId` callback diambil dari `reference_id` | ✅ **VALIDATED** (docs resmi iPaymu mengirim `reference_id` merchant) |
+| S6 | 🟡 Medium | Premature | `core/descriptor.ts:90` | `coming_soon` selalu di-hardcode `false` | ✅ **FIXED** (baca `raw.coming_soon ?? raw.is_coming_soon ?? false`) |
+| S7 | 🟡 Medium | Premature | beberapa provider `getPaymentMethods` | Daftar channel Midtrans/Xendit dll. adalah statis | ✅ **FIXED** (Xendit query `/payment_channels` live; fallback aman) |
+| S8 | 🟡 Medium | Premature | `core/manager.ts:297` | `probePaymentMethods` sebagian besar fallback | ✅ **FIXED** (implementasi di iPaymu & Xendit + fallback dinamis di manager & facade) |
+| S9 | 🟡 Medium | Premature | `core/providerRegistry.ts:83-92` | `detectFromWebhook` auto-detect ambigu | ✅ **FIXED** (prioritas header, payload diperketat, penanganan aman tanpa crash) |
+
+---
+
+## II. Bug & Hasil Perbaikan
+
+### S1. DOKU — verifikasi webhook default `isValid = true` (Critical keamanan) — ✅ FIXED
+
+**Lokasi:** `src/providers/doku/provider.ts`
+
+**Masalah Sebelumnya:**
+- Jika request webhook datang tanpa header signature (atau secretKey/clientSecret belum terkonfigurasi), `verifyCallback` dan `verifySnapCallback` mengembalikan `isValid = true` tanpa verifikasi.
+- Payload palsu berpotensi lolos verifikasi.
+
+**Perbaikan & Validasi Docs:**
+- DOKU Notification Guide resmi mewajibkan signature verification via headers (`Signature`, `Request-Id`, `Client-Id`, `Request-Timestamp`).
+- Kode telah diperbaiki: default `isValid = false`.
+- Jika signature header atau kredensial kosong, webhook langsung ditolak dengan `isValid: false` dan pesan error deskriptif.
+
+---
+
+### S2. Xendit — verifikasi webhook default `isValid = true` (Critical keamanan) — ✅ FIXED
+
+**Lokasi:** `src/providers/xendit/provider.ts:242`
+
+**Masalah Sebelumnya:**
+- Tanpa `config.extra.webhookToken` atau header callback token, `isValid` tetap bernilai `true`.
+
+**Perbaikan & Validasi Docs:**
+- Dokumentasi resmi Xendit Webhook Verification menyatakan bahwa Xendit menyertakan `x-callback-token` pada header notifikasi callback.
+- Kode telah diperbaiki: default `isValid = false`.
+- Jika token header atau konfigurasi secret tidak ada atau tidak cocok, callback ditolak (`isValid: false`).
+
+---
+
+### S3. iPaymu — fallback nomor telepon hardcode (High) — ✅ FIXED
+
+**Lokasi:** `src/providers/ipaymu/provider.ts:50` (direct) dan `:84` (semi-integrasi)
+
+**Masalah Sebelumnya:**
+- Mengirim nomor fiktif tetap `"081234567890"` ke iPaymu ketika `customer.phone` tidak diisi.
+
+**Perbaikan & Validasi Docs:**
+- Dokumentasi resmi iPaymu API v2 (Direct & Redirect Payment) menegaskan bahwa parameter `phone` adalah **opsional**, bukan wajib.
+- Kode telah diperbaiki: fallback hardcode dihapus sepenuhnya. Field `phone` hanya dikirim jika konsumen menyediakannya (`customer?.phone`).
+
+---
+
+### S4. iPaymu `checkTransaction` — kontrak `/transaction` divalidasi (Risk integrasi) — ✅ VALIDATED
+
+**Lokasi:** `src/providers/ipaymu/provider.ts:351`
+
+**Temuan & Validasi Docs:**
+- Dokumentasi resmi iPaymu API v2 (`POST /api/v2/transaction`) mengonfirmasi bahwa parameter request body **hanya menerima `transactionId`** (ID transaksi numerik yang diterbitkan oleh iPaymu), bukan `referenceId` / `order_number` string merchant.
+- Mengirim `referenceId` merchant ke endpoint ini akan menghasilkan transaksi tidak ditemukan / pending.
+- **Klarifikasi Kontrak:** Nilai `merchantOrderId` pada `buayar.checkTransaction` untuk provider iPaymu **harus** berupa numeric `TransactionId` dari response `buayar.createInvoice()` (`invoice.reference`), bukan nomor order string internal merchant.
+- JSDoc pada interface `CheckTransactionParams` dan dokumentasi panduan telah diperjelas.
+
+---
+
+### S5. iPaymu callback — `orderId` diambil dari `reference_id` (Risk integrasi) — ✅ VALIDATED
+
+**Lokasi:** `src/providers/ipaymu/provider.ts:190`
+
+**Temuan & Validasi Docs:**
+- Dokumentasi resmi webhook / callback notification iPaymu mengonfirmasi bahwa payload callback POST selalu menyertakan `reference_id` (nilai referenceId yang dikirim saat `createInvoice`).
+- Format mapping `const orderId = body.reference_id || body.referenceId || body.trx_id || ""` sudah benar dan sesuai dengan spesifikasi resmi iPaymu v2.
+
+---
+
+## III. Fitur Premature
+
+### S6. `coming_soon` selalu `false` (Medium) — ✅ FIXED
+
+**Lokasi:** `src/core/descriptor.ts:90`
+
+**Perbaikan:**
+- Implementasi diperbarui agar membaca status `coming_soon` dari raw payment method (`raw.coming_soon ?? raw.is_coming_soon ?? false`) alih-alih hardcode `false`.
+- Konsumen SDK kini dapat menandai channel pembayaran yang belum aktif di UI.; channel yang seharusnya
+ditandai tidak tersedia akan tampil normal.
+
+---
+
+### S7. Daftar channel banyak provider bersifat statis (Medium) — ✅ FIXED
+
+**Lokasi:** `xendit/provider.ts`, `midtrans/provider.ts`
+
+**Perbaikan:**
+- Pada provider **Xendit**, `getPaymentMethods()` kini mendukung query dinamis langsung ke endpoint resmi Xendit `GET /payment_channels`. Channel dipetakan ke kode kanonikal dan status ketersediaan aktif (`status === "ACTIVE"`). Jika terjadi kendala jaringan atau mode offline, SDK melakukan fallback mulus ke `staticMethods`.
+- Pada provider **Midtrans**, ketiadaan endpoint publik list channel diimbangi dengan fitur probing aktif melalui `probePaymentMethods` (mengetes charge & cancel ke gateway).
+- Dokumentasi panduan diperbarui menjelaskan perilaku ini secara transparan.
+
+---
+
+### S8. `probePaymentMethods` sebagian besar tidak diimplementasi (Medium) — ✅ FIXED
+
+**Lokasi:** `src/core/manager.ts`, `src/providers/ipaymu/provider.ts`, `src/providers/xendit/provider.ts`, `src/core/buayar.ts`
+
+**Perbaikan:**
+- Method `probePaymentMethods` kini diimplementasikan pada provider utama (**iPaymu** dan **Xendit**, selain yang sudah ada di Duitku dan Midtrans).
+- `PaymentManager` ditambahkan mekanisme fallback cerdas: jika provider memiliki implementasi `getPaymentMethods`, daftar channel aktif akan otomatis dimanfaatkan untuk probing.
+- Ditambahkan method facade `buayar.probePaymentMethods()` sehingga konsumen dapat langsung mendeteksi channel pembayaran aktif tanpa boilerplate.
+
+---
+
+### S9. `detectFromWebhook` — auto-detect ambigu (Medium) — ✅ FIXED
+
+**Lokasi:** `src/core/providerRegistry.ts:83-125`, `src/core/buayar.ts:305-325`
+
+**Perbaikan:**
+- **Prioritas Header Bertingkat:** Deteksi webhook kini memeriksa HTTP Signature/Token Header terlebih dahulu (`x-callback-token`, `stripe-signature`, `x-razorpay-signature`, `cko-signature`, `openpayu-signature`, `x-square-hmacsha256-signature`, `bt_signature`, `x-oy-username`, `signature` DOKU, dan `x-signature` iPaymu) yang memiliki tingkat kepastian jauh lebih tinggi daripada sekadar field body.
+- **Pola Payload Diperketat:** Pola payload seperti Xendit tidak lagi mencocokkan `external_id` polos secara ambigu, melainkan wajib memiliki status/channel/metode bayar terkait.
+- **Prioritas Provider Eksplisit:** Konfigurasi provider eksplisit tetap menjadi prioritas utama dan tidak ditimpa oleh auto-detect.
+- **Penanganan Aman Tanpa Crash:** Jika payload webhook tak dikenal atau provider tak dapat ditentukan, SDK mengembalikan response terstruktur `{ isValid: false, isPaid: false, provider: "unknown", error: "..." }` alih-alih melempar exception/crash.
+
+---
+
+## IV. Status Implementasi & Rekomendasi
+
+1. **S1/S2 (Critical) — ✅ SELESAI:** Default `isValid` diubah menjadi `false`. Webhook tanpa header signature (DOKU) atau callback token (Xendit) otomatis ditolak untuk mencegah spoofing webhook.
+2. **S3 (High) — ✅ SELESAI:** Fallback hardcode nomor telepon `"081234567890"` dihapus. Parameter `phone` dijadikan opsional per docs resmi iPaymu v2.
+3. **S4/S5 (High) — ✅ SELESAI & TERVALIDASI:**
+   - Divalidasi dengan docs resmi iPaymu: `/transaction` mewajibkan `transactionId` numerik iPaymu (`invoice.reference`), bukan orderId merchant. JSDoc dan dokumentasi diperjelas.
+   - Divalidasi dengan docs resmi iPaymu: callback webhook selalu mengirim `reference_id` merchant.
+4. **S6 (Medium) — ✅ SELESAI:** Flag `coming_soon` pada deskriptor channel kini membaca dari field raw channel (`raw.coming_soon ?? raw.is_coming_soon ?? false`).
+5. **S7 (Medium) — ✅ SELESAI:** Query dinamis live `/payment_channels` pada Xendit dengan fallback statis aman.
+6. **S8 (Medium) — ✅ SELESAI:** `probePaymentMethods` diimplementasikan di iPaymu & Xendit + fallback dinamis di manager & facade.
+7. **S9 (Medium) — ✅ SELESAI:** Deteksi webhook via header tingkat tinggi, heuristik diperketat, dan penanganan aman tanpa crash.
+
+---
+
+## V. Lampiran — Lokasi kode yang direferensikan
+
+- `src/providers/doku/provider.ts` — `verifyCallback` (≈495-542), `verifySnapCallback` (≈548+)
+- `src/providers/xendit/provider.ts` — `verifyCallback` (≈217-260)
+- `src/providers/ipaymu/provider.ts` — `createInvoice` (25-186), `verifyCallback` (188-216), `checkTransaction` (351-449)
+- `src/core/descriptor.ts` — `buildPaymentMethodDescriptor` (72-93)
+- `src/core/manager.ts` — `probePaymentMethods` (289-298), `getPaymentMethods` (271-278), `checkTransaction` (280-287)
+- `src/core/providerRegistry.ts` — `detectFromWebhook` (83-107)
+- `src/core/buayar.ts` — `verifyWebhook` (243-310)
+---

package/docs/guide.md

@@ -183,6 +183,18 @@ const { categories } = await buayar.getPaymentMethods({ amount: 150000 });
 // categories: { "Virtual Account": [...], "QRIS": [...], "E-Wallet": [...], ... }
 ```
 
+### Probing Saluran Aktif di Akun Gateway (`probePaymentMethods`)
+
+Untuk mendeteksi secara dinamis saluran yang benar-benar aktif / di-enable pada akun merchant Anda di gateway:
+
+```typescript
+const probe = await buayar.probePaymentMethods();
+if (probe.success) {
+  console.log("Channel aktif di akun merchant:", probe.enabled);
+  // Output: ["bca_va", "mandiri_va", "qris", "gopay", ...]
+}
+```
+
 ---
 
 ## 🔍 Cek Status Transaksi
@@ -196,6 +208,10 @@ if (result.success) {
 }
 ```
 
+> 💡 **Catatan Parameter per Provider:**
+> - **Midtrans, Duitku, Xendit, DOKU, dll:** `merchantOrderId` menerima string ID order yang Anda buat (mis. `"ORDER-1001"`).
+> - **iPaymu:** Dokumentasi resmi iPaymu v2 mewajibkan `transactionId` numerik. Masukkan nilai **`invoice.reference`** (TransactionId numerik yang dikembalikan saat `createInvoice`), bukan nomor order string internal merchant.
+
 ---
 
 ## 🪝 Webhook Universal
@@ -208,9 +224,10 @@ import { buayar } from "@crediblemark/buayar";
 // Bekerja dengan Express, Elysia, Hono, Next.js App Router, dll.
 app.post("/api/payment/webhook", async (req, res) => {
   const result = await buayar.verifyWebhook(req.body, req.headers);
-  // header signature otomatis diekstrak sesuai provider (Stripe-Signature,
-  // Cko-Signature, X-Razorpay-Signature, dll.)
+  // Header signature otomatis diekstrak sesuai provider (Stripe-Signature,
+  // X-Signature, x-callback-token, Signature DOKU, dll.)
 
+  // Keamanan Ketat: jika signature/token tidak ada atau tidak cocok, isValid bernilai false
   if (!result.isValid) return res.status(400).json({ error: "Invalid signature" });
 
   if (result.isPaid) {
@@ -222,6 +239,11 @@ app.post("/api/payment/webhook", async (req, res) => {
 });
 ```
 
+> 🔒 **Keamanan Signature Ketat:**
+> - **DOKU:** Otomatis memvalidasi signature header (`Signature`, `Request-Id`, `Request-Timestamp`) via HMAC-SHA256. Webhook tanpa signature ditolak (`isValid: false`).
+> - **Xendit:** Memvalidasi header `x-callback-token` terhadap secret token yang dikonfigurasi (`BUAYAR_WEBHOOK_SECRET` / `webhookToken`). Webhook tanpa token ditolak (`isValid: false`).
+> - **iPaymu:** Memvalidasi header `X-Signature` dengan HMAC-SHA256 atas body menggunakan VA merchant. Field `result.orderId` otomatis diisi dari `reference_id` order merchant.
+>
 > `buayar.handleWebhook(payload, headers)` adalah alias dari `verifyWebhook`.
 
 ---