@crediblemark/buayar 0.8.5 → 0.8.6

package/dist/cli/index.js

@@ -484,7 +484,7 @@ function printScaffoldSummary(result) {
 }
 
 // src/cli/index.ts
-var VERSION = "0.8.5";
+var VERSION = "0.8.6";
 function parseArgs(argv) {
   const flags = [];
   const rest = [];

package/dist/index.d.mts

@@ -139,8 +139,12 @@ interface VerifyCallbackResult {
     transactionTime?: Date | string;
     /** Raw payload callback asli dari webhook */
     rawPayload: any;
+    /** Pesan error jika verifikasi callback gagal */
+    error?: string;
 }
 interface ProviderConfig {
+    /** Nama provider target (opsional, jika ingin override per panggilan fungsi) */
+    provider?: string;
     merchantCode?: string;
     apiKey?: string;
     sandbox?: boolean;
@@ -200,6 +204,8 @@ interface PaymentMethod {
     category: "Virtual Account" | "QRIS" | "E-Wallet" | "Retail / Gerai" | "Kartu Kredit" | "Paylater / Cicilan" | "Lainnya" | string;
     code?: string;
     extra?: any;
+    /** Tandai channel sebagai coming soon / belum tersedia */
+    coming_soon?: boolean;
     feeDetail?: {
         flat: number;
         percent: number;
@@ -250,7 +256,13 @@ interface GetPaymentMethodDescriptorsResult {
     generatedAt: string;
 }
 interface CheckTransactionParams {
-    /** Merchant order ID saat pembuatan transaksi */
+    /**
+     * ID transaksi untuk pengecekan status.
+     *
+     * **iPaymu:** Harus berisi `TransactionId` numerik dari response `createInvoice`
+     * (`invoice.reference`), BUKAN `orderId`/`order_number` merchant.
+     * Endpoint iPaymu `/api/v2/transaction` hanya menerima ID numerik milik iPaymu.
+     */
     merchantOrderId: string;
 }
 interface CheckTransactionResult {
@@ -419,6 +431,11 @@ declare class IpaymuProvider extends BasePaymentProvider {
     createInvoice(params: CreateInvoiceParams, config: ProviderConfig): Promise<InvoiceResponse>;
     verifyCallback(body: any, config: ProviderConfig): Promise<VerifyCallbackResult>;
     getPaymentMethods(params: GetPaymentMethodsParams, config: ProviderConfig): Promise<GetPaymentMethodsResult>;
+    probePaymentMethods(config: ProviderConfig): Promise<{
+        success: boolean;
+        enabled: string[];
+        error?: string;
+    }>;
     checkTransaction(params: CheckTransactionParams, config: ProviderConfig): Promise<CheckTransactionResult>;
 }
 
@@ -428,6 +445,11 @@ declare class XenditProvider extends BasePaymentProvider {
     createInvoice(params: CreateInvoiceParams, config: ProviderConfig): Promise<InvoiceResponse>;
     verifyCallback(body: any, config: ProviderConfig): Promise<VerifyCallbackResult>;
     getPaymentMethods(params: GetPaymentMethodsParams, config: ProviderConfig): Promise<GetPaymentMethodsResult>;
+    probePaymentMethods(config: ProviderConfig): Promise<{
+        success: boolean;
+        enabled: string[];
+        error?: string;
+    }>;
     checkTransaction(params: CheckTransactionParams, config: ProviderConfig): Promise<CheckTransactionResult>;
 }
 
@@ -1255,10 +1277,10 @@ declare class ProviderRegistry {
      */
     detectFromEnv(env: Record<string, string | undefined>): string | undefined;
     /**
-     * Autodetect provider dari struktur payload webhook.
+     * Autodetect provider dari struktur payload webhook dan header.
      * Mengembalikan nama provider jika dikenali, else undefined.
      */
-    detectFromWebhook(payload: any): string | undefined;
+    detectFromWebhook(payload: any, headers?: Record<string, any>): string | undefined;
 }
 declare function buildDefaultDescriptors(): ProviderDescriptor[];
 declare const providerRegistry: ProviderRegistry;
@@ -1315,9 +1337,9 @@ declare class Buayar {
      */
     getCapabilities(name?: string): ProviderCapability | undefined;
     /**
-     * Deteksi nama provider dari struktur payload webhook.
+     * Deteksi nama provider dari struktur payload webhook dan opsional headers.
      */
-    detectProviderFromPayload(payload: any): string | undefined;
+    detectProviderFromPayload(payload: any, headers?: Record<string, string | string[] | undefined>): string | undefined;
     /**
      * Deteksi nama provider aktif dari variabel lingkungan (kredensial yang terisi).
      */
@@ -1360,6 +1382,14 @@ declare class Buayar {
      */
     verifyWebhook(payload: any, headers?: Record<string, string | string[] | undefined>, configOverride?: Partial<ProviderConfig>): Promise<VerifyCallbackResult>;
     handleWebhook(payload: any, headers?: Record<string, string | string[] | undefined>, configOverride?: Partial<ProviderConfig>): Promise<VerifyCallbackResult>;
+    /**
+     * Probe payment methods yang benar-benar aktif di akun merchant gateway.
+     */
+    probePaymentMethods(configOverride?: Partial<ProviderConfig>): Promise<{
+        success: boolean;
+        enabled: string[];
+        error?: string;
+    }>;
     /**
      * Unified Refund — berlaku untuk semua provider yang mendukung refund.
      * Provider tanpa fitur refund mengembalikan `{ supported: false }`, bukan error.

package/dist/index.d.ts

@@ -139,8 +139,12 @@ interface VerifyCallbackResult {
     transactionTime?: Date | string;
     /** Raw payload callback asli dari webhook */
     rawPayload: any;
+    /** Pesan error jika verifikasi callback gagal */
+    error?: string;
 }
 interface ProviderConfig {
+    /** Nama provider target (opsional, jika ingin override per panggilan fungsi) */
+    provider?: string;
     merchantCode?: string;
     apiKey?: string;
     sandbox?: boolean;
@@ -200,6 +204,8 @@ interface PaymentMethod {
     category: "Virtual Account" | "QRIS" | "E-Wallet" | "Retail / Gerai" | "Kartu Kredit" | "Paylater / Cicilan" | "Lainnya" | string;
     code?: string;
     extra?: any;
+    /** Tandai channel sebagai coming soon / belum tersedia */
+    coming_soon?: boolean;
     feeDetail?: {
         flat: number;
         percent: number;
@@ -250,7 +256,13 @@ interface GetPaymentMethodDescriptorsResult {
     generatedAt: string;
 }
 interface CheckTransactionParams {
-    /** Merchant order ID saat pembuatan transaksi */
+    /**
+     * ID transaksi untuk pengecekan status.
+     *
+     * **iPaymu:** Harus berisi `TransactionId` numerik dari response `createInvoice`
+     * (`invoice.reference`), BUKAN `orderId`/`order_number` merchant.
+     * Endpoint iPaymu `/api/v2/transaction` hanya menerima ID numerik milik iPaymu.
+     */
     merchantOrderId: string;
 }
 interface CheckTransactionResult {
@@ -419,6 +431,11 @@ declare class IpaymuProvider extends BasePaymentProvider {
     createInvoice(params: CreateInvoiceParams, config: ProviderConfig): Promise<InvoiceResponse>;
     verifyCallback(body: any, config: ProviderConfig): Promise<VerifyCallbackResult>;
     getPaymentMethods(params: GetPaymentMethodsParams, config: ProviderConfig): Promise<GetPaymentMethodsResult>;
+    probePaymentMethods(config: ProviderConfig): Promise<{
+        success: boolean;
+        enabled: string[];
+        error?: string;
+    }>;
     checkTransaction(params: CheckTransactionParams, config: ProviderConfig): Promise<CheckTransactionResult>;
 }
 
@@ -428,6 +445,11 @@ declare class XenditProvider extends BasePaymentProvider {
     createInvoice(params: CreateInvoiceParams, config: ProviderConfig): Promise<InvoiceResponse>;
     verifyCallback(body: any, config: ProviderConfig): Promise<VerifyCallbackResult>;
     getPaymentMethods(params: GetPaymentMethodsParams, config: ProviderConfig): Promise<GetPaymentMethodsResult>;
+    probePaymentMethods(config: ProviderConfig): Promise<{
+        success: boolean;
+        enabled: string[];
+        error?: string;
+    }>;
     checkTransaction(params: CheckTransactionParams, config: ProviderConfig): Promise<CheckTransactionResult>;
 }
 
@@ -1255,10 +1277,10 @@ declare class ProviderRegistry {
      */
     detectFromEnv(env: Record<string, string | undefined>): string | undefined;
     /**
-     * Autodetect provider dari struktur payload webhook.
+     * Autodetect provider dari struktur payload webhook dan header.
      * Mengembalikan nama provider jika dikenali, else undefined.
      */
-    detectFromWebhook(payload: any): string | undefined;
+    detectFromWebhook(payload: any, headers?: Record<string, any>): string | undefined;
 }
 declare function buildDefaultDescriptors(): ProviderDescriptor[];
 declare const providerRegistry: ProviderRegistry;
@@ -1315,9 +1337,9 @@ declare class Buayar {
      */
     getCapabilities(name?: string): ProviderCapability | undefined;
     /**
-     * Deteksi nama provider dari struktur payload webhook.
+     * Deteksi nama provider dari struktur payload webhook dan opsional headers.
      */
-    detectProviderFromPayload(payload: any): string | undefined;
+    detectProviderFromPayload(payload: any, headers?: Record<string, string | string[] | undefined>): string | undefined;
     /**
      * Deteksi nama provider aktif dari variabel lingkungan (kredensial yang terisi).
      */
@@ -1360,6 +1382,14 @@ declare class Buayar {
      */
     verifyWebhook(payload: any, headers?: Record<string, string | string[] | undefined>, configOverride?: Partial<ProviderConfig>): Promise<VerifyCallbackResult>;
     handleWebhook(payload: any, headers?: Record<string, string | string[] | undefined>, configOverride?: Partial<ProviderConfig>): Promise<VerifyCallbackResult>;
+    /**
+     * Probe payment methods yang benar-benar aktif di akun merchant gateway.
+     */
+    probePaymentMethods(configOverride?: Partial<ProviderConfig>): Promise<{
+        success: boolean;
+        enabled: string[];
+        error?: string;
+    }>;
     /**
      * Unified Refund — berlaku untuk semua provider yang mendukung refund.
      * Provider tanpa fitur refund mengembalikan `{ supported: false }`, bukan error.

package/dist/index.js

@@ -1808,7 +1808,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,
@@ -1839,7 +1839,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 } : {},
@@ -2069,6 +2069,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 || "";
@@ -2356,8 +2378,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 {
@@ -2505,6 +2527,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]) {
@@ -2520,6 +2611,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 || "";
@@ -3316,7 +3429,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);
     }
@@ -3341,7 +3454,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);
@@ -9669,6 +9782,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) ─────────────
@@ -9918,7 +10043,7 @@ function buildPaymentMethodDescriptor(pm, _providerName) {
     badge: feeDisplay ? `${badge} \u2022 Fee ${feeDisplay}` : badge,
     image: pm.paymentImage || void 0,
     category,
-    coming_soon: false,
+    coming_soon: pm.coming_soon ?? false,
     totalFee: feeDisplay || void 0
   };
 }
@@ -9968,10 +10093,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";
@@ -9985,7 +10126,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";
@@ -10339,10 +10482,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).
@@ -10471,14 +10614,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.

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) ─────────────
@@ -9748,7 +9873,7 @@ function buildPaymentMethodDescriptor(pm, _providerName) {
     badge: feeDisplay ? `${badge} \u2022 Fee ${feeDisplay}` : badge,
     image: pm.paymentImage || void 0,
     category,
-    coming_soon: false,
+    coming_soon: pm.coming_soon ?? false,
     totalFee: feeDisplay || void 0
   };
 }
@@ -9798,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";
@@ -9815,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";
@@ -10169,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).
@@ -10301,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.

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`.
 
 ---

package/docs/ipaymu.md

@@ -133,7 +133,7 @@ const invoice = await buayar.createInvoice({
   customer: {
     name: "Budi Santoso",
     email: "budi@mail.com",
-    phone: "081234567890",
+    phone: "081234567890", // Opsional per dokumentasi resmi iPaymu v2 (hanya dikirim jika ada)
   },
   // Opsi Tambahan iPaymu:
   feeDirection: "BUYER", // "BUYER" (bebankan fee ke pembeli) atau "MERCHANT" (potong omset)
@@ -141,12 +141,14 @@ const invoice = await buayar.createInvoice({
 });
 
 if (invoice.success) {
-  console.log("Transaction ID (Trx ID):", invoice.reference); // Contoh: "229432"
+  console.log("Transaction ID (Trx ID):", invoice.reference); // Contoh: "229432" (simpan ini untuk checkTransaction)
   console.log("Nomor Virtual Account:", invoice.vaNumber);     // Contoh: "3811800034705407"
   console.log("Expired:", invoice.expiresAt);
 }
 ```
 
+> 💡 **Parameter `customer.phone` Opsional:** Sesuai dokumentasi resmi iPaymu v2, parameter `phone` bersifat opsional. Buayar tidak lagi menyisipkan nomor fallback buatan — field `phone` hanya disertakan jika memang diisi oleh pembeli/merchant.
+
 ### B. Redirect Payment (Hosted Payment Page)
 Cukup kosongkan `paymentMethod` untuk menggunakan halaman checkout bawaan iPaymu:
 
@@ -158,7 +160,7 @@ const invoice = await buayar.createInvoice({
   customer: {
     name: "Siti Rahma",
     email: "siti@mail.com",
-    phone: "081999888777",
+    phone: "081999888777", // Opsional
   },
   returnUrl: "https://toko-anda.com/checkout/success",
 });
@@ -292,6 +294,8 @@ Callback **harus** membawa header `X-Signature`; Buayar memverifikasinya dengan
 menggunakan **Merchant VA** sebagai secret key. Callback tanpa `X-Signature` yang sah
 akan selalu ditolak (`isValid === false`).
 
+Sesuai dokumentasi resmi iPaymu, payload notifikasi membawa field `reference_id` (berisi nomor order merchant yang dikirim saat `createInvoice`). Buayar otomatis memetakannya ke **`result.orderId`**.
+
 ```typescript
 // Di handler Express.js / Next.js API route + REST framework apapun (Elysia/Hono/...):
 app.post("/api/payment/webhook", (req, res) => {
@@ -299,6 +303,7 @@ app.post("/api/payment/webhook", (req, res) => {
   const result = buayar.verifyWebhook(req.body, req.headers);
 
   if (result.isValid && result.isPaid) {
+    // result.orderId otomatis diambil dari `reference_id` iPaymu (order ID merchant Anda)
     console.log("Pembayaran Berhasil untuk Order ID:", result.orderId);
     console.log("Nominal Diterima:", result.amount);
     // Jalankan logika bisnis: update database status pesanan menjadi PAID
@@ -326,12 +331,22 @@ console.log(invoice.reference); // Contoh: "229432"
 4. Klik tombol **"Kirim" / "Test"**.
 5. Server iPaymu Sandbox akan mengubah status transaksi menjadi **Berhasil** dan otomatis mengirimkan webhook notifikasi ke `notifyUrl` Anda.
 
-### Mengecek Status Transaksi via Kode
+### Mengecek Status Transaksi via Kode (`checkTransaction`)
+
+> ⚠️ **PENTING — Kontrak Resmi Endpoint `/transaction`:**
+> Dokumentasi resmi iPaymu API v2 menegaskan bahwa endpoint `/api/v2/transaction` **hanya menerima `transactionId` numerik** yang diterbitkan iPaymu (`invoice.reference`), **BUKAN** `order_number` atau string `orderId` merchant.
+>
+> Jika aplikasi Anda melakukan polling status, pastikan selalu menyimpan `invoice.reference` di database dan operasikan nilai tersebut ke parameter `merchantOrderId`:
+
 ```typescript
 const check = await buayar.checkTransaction({
-  merchantOrderId: invoice.reference, // Transaction ID iPaymu
+  // WAJIB: Gunakan invoice.reference (TransactionId numerik dari iPaymu),
+  // BUKAN nomor invoice/order_number string toko Anda!
+  merchantOrderId: invoice.reference, // misal "229432"
 });
 
-console.log("Status:", check.rawResponse.Data.StatusDesc);
-// Output: "Berhasil"
+if (check.success) {
+  console.log("Status Transaksi:", check.status); // "paid" | "pending" | "failed"
+  console.log("Status Desc:", check.rawResponse.Data.StatusDesc); // "Berhasil"
+}
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediblemark/buayar",
-  "version": "0.8.5",
+  "version": "0.8.6",
   "description": "Unified Payment Gateway SDK for Node.js & TypeScript — 19 providers (Midtrans, Xendit, Duitku, Stripe, PayPal, Adyen, Razorpay, Square, Checkout.com, PayU, Braintree, 2Checkout, DOKU, iPaymu, PrismaLink, Faspay, Finpay, Nicepay, OY!) with zero-code switching via .env",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",