@crediblemark/buayar 0.3.1 → 0.4.0

package/dist/index.d.mts

@@ -184,6 +184,63 @@ interface CheckTransactionResult {
     error?: string;
     rawResponse: any;
 }
+interface RefundParams {
+    /** ID transaksi / capture / payment sebagai target refund (per provider) */
+    transactionId: string;
+    /** Nominal refund (opsional; default = full refund) */
+    amount?: number;
+    /** Alasan refund (opsional bila didukung provider) */
+    reason?: string;
+    /** Kode mata uang (opsional, untuk provider internasional) */
+    currency?: string;
+}
+interface RefundResult {
+    success: boolean;
+    /** Provider yang menyatakan operasi ini tidak tersedia */
+    supported: boolean;
+    provider?: string;
+    /** Reference / ID refund dari provider */
+    reference?: string;
+    /** Status refund dari provider (raw) */
+    status?: string;
+    error?: string;
+    rawResponse: any;
+}
+interface CheckBalanceResult {
+    success: boolean;
+    supported: boolean;
+    provider?: string;
+    /** Saldo merchant dalam satuan terkecil (minor unit) */
+    balance?: number;
+    /** Kode mata uang saldo (bila tersedia) */
+    currency?: string;
+    error?: string;
+    rawResponse: any;
+}
+interface DisburseParams {
+    /** ID unik merchant untuk mengidentifikasi transfer (merchantOrderId / externalId / partnerTrxId) */
+    externalId: string;
+    /** Kode bank tujuan (mis. 'bca', '014', 'BCA' — ikuti aturan provider) */
+    bankCode: string;
+    /** Nama pemilik rekening tujuan (wajib untuk beberapa provider) */
+    accountHolderName?: string;
+    /** Nomor rekening tujuan */
+    accountNumber: string;
+    /** Nominal transfer */
+    amount: number;
+    /** Deskripsi / tujuan transfer */
+    description?: string;
+}
+interface DisburseResult {
+    success: boolean;
+    supported: boolean;
+    provider?: string;
+    /** Reference / status transfer dari provider */
+    reference?: string;
+    status?: string;
+    error?: string;
+    rawResponse: any;
+}
 
 declare abstract class BasePaymentProvider {
     abstract readonly name: string;
@@ -934,6 +991,10 @@ declare class PaymentManager {
         enabled: string[];
         error?: string;
     }>;
+    private unsupported;
+    refund(providerName: string, params: RefundParams, config: ProviderConfig): Promise<RefundResult>;
+    checkBalance(providerName: string, config: ProviderConfig): Promise<CheckBalanceResult>;
+    disburse(providerName: string, params: DisburseParams, config: ProviderConfig): Promise<DisburseResult>;
 }
 declare const paymentManager: PaymentManager;
 
@@ -996,6 +1057,21 @@ 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>;
+    /**
+     * Unified Refund — berlaku untuk semua provider yang mendukung refund.
+     * Provider tanpa fitur refund mengembalikan `{ supported: false }`, bukan error.
+     */
+    refund(params: RefundParams, configOverride?: Partial<ProviderConfig>): Promise<RefundResult>;
+    /**
+     * Unified Check Balance — ambil saldo merchant dari provider aktif.
+     * Provider tanpa fitur balance mengembalikan `{ supported: false }`.
+     */
+    checkBalance(configOverride?: Partial<ProviderConfig>): Promise<CheckBalanceResult>;
+    /**
+     * Unified Disburse / Payout — transfer dana ke rekening bank tujuan.
+     * Provider tanpa fitur disbursement mengembalikan `{ supported: false }`.
+     */
+    disburse(params: DisburseParams, configOverride?: Partial<ProviderConfig>): Promise<DisburseResult>;
     getMidtransClient(configOverride?: Partial<ProviderConfig>): MidtransClient;
     getDuitkuClient(configOverride?: Partial<ProviderConfig>): DuitkuClient;
     getIpaymuClient(configOverride?: Partial<ProviderConfig>): IpaymuClient;
@@ -1403,4 +1479,4 @@ declare function safeCompare(a: string, b: string): boolean;
  */
 declare function getPaymentMethodCategory(code: string, name?: string): "Virtual Account" | "QRIS" | "E-Wallet" | "Retail / Gerai" | "Kartu Kredit" | "Paylater / Cicilan" | "Lainnya";
 
-export { AdyenClient, AdyenProvider, BasePaymentProvider, BraintreeClient, BraintreeProvider, Buayar, type BuayarConfig, CANONICAL_TO_DOKU, CANONICAL_TO_DUITKU, CANONICAL_TO_FASPAY, CANONICAL_TO_FINPAY, CANONICAL_TO_IPAYMU, CANONICAL_TO_MIDTRANS, CANONICAL_TO_NICEPAY, CANONICAL_TO_OY, CANONICAL_TO_PRISMALINK, CANONICAL_TO_STRIPE, CANONICAL_TO_XENDIT, CORE_API_METHODS, type CanonicalPaymentMethod, type CheckTransactionParams, type CheckTransactionResult, CheckoutComClient, CheckoutComProvider, type CreateInvoiceParams, type CustomerDetails, DUITKU_TO_CANONICAL, DokuClient, DokuProvider, DuitkuClient, type DuitkuDisbursementParams, DuitkuProvider, FaspayClient, FaspayProvider, FinpayClient, FinpayProvider, type GetPaymentMethodsParams, type GetPaymentMethodsResult, type InvoiceResponse, IpaymuClient, IpaymuProvider, MIDTRANS_PROBE_PAYLOADS, MIDTRANS_STATIC_METHODS, type MandiriBillInfo, MidtransClient, MidtransProvider, NicepayClient, NicepayProvider, OyClient, OyProvider, PaymentManager, type PaymentMethod, type PaymentMethodItem, PaypalClient, PaypalProvider, PayuClient, PayuProvider, PrismalinkClient, PrismalinkProvider, type ProviderConfig, RazorpayClient, RazorpayProvider, SquareClient, SquareProvider, StripeClient, StripeProvider, TwoCheckoutClient, TwoCheckoutProvider, type VerifyCallbackResult, XenditClient, type XenditDisbursementParams, XenditProvider, buayar, buildBraintreeBasicAuth, buildCoreChargePayload, buildPaypalBasicAuth, buildPayuBasicAuth, buildRazorpayBasicAuth, buildTwoCheckoutAuth, formatNicepayTimestamp, generateDokuHeaders, generateFaspaySignature, generateFinpaySignature, generateIpaymuSignature, generateNicepayToken, generateOyHeaders, generatePrismalinkSignature, getDuitkuInquirySignatures, getDuitkuPaymentMethodsSignature, getDuitkuStatusSignatures, getPaymentMethodCategory, getXenditAuthHeader, hmacSha256, md5, parseCoreChargeResponse, paymentManager, resolveConfigFromEnv, safeCompare, serializePaypalParams, serializeStripeParams, sha256, sha512, toCanonicalPaymentMethod, toDokuPaymentMethod, toDuitkuPaymentMethod, toFaspayPaymentMethod, toFinpayPaymentMethod, toIpaymuPaymentMethod, toNicepayPaymentMethod, toOyPaymentMethod, toPrismalinkPaymentMethod, toStripePaymentMethod, toXenditPaymentMethod, verifyAdyenWebhook, verifyBraintreeWebhook, verifyCheckoutComWebhook, verifyDokuWebhookSignature, verifyDuitkuCallbackSignature, verifyFaspaySignature, verifyFinpaySignature, verifyIpaymuCallback, verifyNicepayWebhook, verifyOyWebhook, verifyPaypalWebhookSimple, verifyPayuWebhook, verifyPrismalinkSignature, verifyRazorpayWebhook, verifySquareWebhook, verifyStripeWebhook, verifyTwoCheckoutWebhook, verifyXenditWebhookToken };
+export { AdyenClient, AdyenProvider, BasePaymentProvider, BraintreeClient, BraintreeProvider, Buayar, type BuayarConfig, CANONICAL_TO_DOKU, CANONICAL_TO_DUITKU, CANONICAL_TO_FASPAY, CANONICAL_TO_FINPAY, CANONICAL_TO_IPAYMU, CANONICAL_TO_MIDTRANS, CANONICAL_TO_NICEPAY, CANONICAL_TO_OY, CANONICAL_TO_PRISMALINK, CANONICAL_TO_STRIPE, CANONICAL_TO_XENDIT, CORE_API_METHODS, type CanonicalPaymentMethod, type CheckBalanceResult, type CheckTransactionParams, type CheckTransactionResult, CheckoutComClient, CheckoutComProvider, type CreateInvoiceParams, type CustomerDetails, DUITKU_TO_CANONICAL, type DisburseParams, type DisburseResult, DokuClient, DokuProvider, DuitkuClient, type DuitkuDisbursementParams, DuitkuProvider, FaspayClient, FaspayProvider, FinpayClient, FinpayProvider, type GetPaymentMethodsParams, type GetPaymentMethodsResult, type InvoiceResponse, IpaymuClient, IpaymuProvider, MIDTRANS_PROBE_PAYLOADS, MIDTRANS_STATIC_METHODS, type MandiriBillInfo, MidtransClient, MidtransProvider, NicepayClient, NicepayProvider, OyClient, OyProvider, PaymentManager, type PaymentMethod, type PaymentMethodItem, PaypalClient, PaypalProvider, PayuClient, PayuProvider, PrismalinkClient, PrismalinkProvider, type ProviderConfig, RazorpayClient, RazorpayProvider, type RefundParams, type RefundResult, SquareClient, SquareProvider, StripeClient, StripeProvider, TwoCheckoutClient, TwoCheckoutProvider, type VerifyCallbackResult, XenditClient, type XenditDisbursementParams, XenditProvider, buayar, buildBraintreeBasicAuth, buildCoreChargePayload, buildPaypalBasicAuth, buildPayuBasicAuth, buildRazorpayBasicAuth, buildTwoCheckoutAuth, formatNicepayTimestamp, generateDokuHeaders, generateFaspaySignature, generateFinpaySignature, generateIpaymuSignature, generateNicepayToken, generateOyHeaders, generatePrismalinkSignature, getDuitkuInquirySignatures, getDuitkuPaymentMethodsSignature, getDuitkuStatusSignatures, getPaymentMethodCategory, getXenditAuthHeader, hmacSha256, md5, parseCoreChargeResponse, paymentManager, resolveConfigFromEnv, safeCompare, serializePaypalParams, serializeStripeParams, sha256, sha512, toCanonicalPaymentMethod, toDokuPaymentMethod, toDuitkuPaymentMethod, toFaspayPaymentMethod, toFinpayPaymentMethod, toIpaymuPaymentMethod, toNicepayPaymentMethod, toOyPaymentMethod, toPrismalinkPaymentMethod, toStripePaymentMethod, toXenditPaymentMethod, verifyAdyenWebhook, verifyBraintreeWebhook, verifyCheckoutComWebhook, verifyDokuWebhookSignature, verifyDuitkuCallbackSignature, verifyFaspaySignature, verifyFinpaySignature, verifyIpaymuCallback, verifyNicepayWebhook, verifyOyWebhook, verifyPaypalWebhookSimple, verifyPayuWebhook, verifyPrismalinkSignature, verifyRazorpayWebhook, verifySquareWebhook, verifyStripeWebhook, verifyTwoCheckoutWebhook, verifyXenditWebhookToken };

package/dist/index.d.ts

@@ -184,6 +184,63 @@ interface CheckTransactionResult {
     error?: string;
     rawResponse: any;
 }
+interface RefundParams {
+    /** ID transaksi / capture / payment sebagai target refund (per provider) */
+    transactionId: string;
+    /** Nominal refund (opsional; default = full refund) */
+    amount?: number;
+    /** Alasan refund (opsional bila didukung provider) */
+    reason?: string;
+    /** Kode mata uang (opsional, untuk provider internasional) */
+    currency?: string;
+}
+interface RefundResult {
+    success: boolean;
+    /** Provider yang menyatakan operasi ini tidak tersedia */
+    supported: boolean;
+    provider?: string;
+    /** Reference / ID refund dari provider */
+    reference?: string;
+    /** Status refund dari provider (raw) */
+    status?: string;
+    error?: string;
+    rawResponse: any;
+}
+interface CheckBalanceResult {
+    success: boolean;
+    supported: boolean;
+    provider?: string;
+    /** Saldo merchant dalam satuan terkecil (minor unit) */
+    balance?: number;
+    /** Kode mata uang saldo (bila tersedia) */
+    currency?: string;
+    error?: string;
+    rawResponse: any;
+}
+interface DisburseParams {
+    /** ID unik merchant untuk mengidentifikasi transfer (merchantOrderId / externalId / partnerTrxId) */
+    externalId: string;
+    /** Kode bank tujuan (mis. 'bca', '014', 'BCA' — ikuti aturan provider) */
+    bankCode: string;
+    /** Nama pemilik rekening tujuan (wajib untuk beberapa provider) */
+    accountHolderName?: string;
+    /** Nomor rekening tujuan */
+    accountNumber: string;
+    /** Nominal transfer */
+    amount: number;
+    /** Deskripsi / tujuan transfer */
+    description?: string;
+}
+interface DisburseResult {
+    success: boolean;
+    supported: boolean;
+    provider?: string;
+    /** Reference / status transfer dari provider */
+    reference?: string;
+    status?: string;
+    error?: string;
+    rawResponse: any;
+}
 
 declare abstract class BasePaymentProvider {
     abstract readonly name: string;
@@ -934,6 +991,10 @@ declare class PaymentManager {
         enabled: string[];
         error?: string;
     }>;
+    private unsupported;
+    refund(providerName: string, params: RefundParams, config: ProviderConfig): Promise<RefundResult>;
+    checkBalance(providerName: string, config: ProviderConfig): Promise<CheckBalanceResult>;
+    disburse(providerName: string, params: DisburseParams, config: ProviderConfig): Promise<DisburseResult>;
 }
 declare const paymentManager: PaymentManager;
 
@@ -996,6 +1057,21 @@ 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>;
+    /**
+     * Unified Refund — berlaku untuk semua provider yang mendukung refund.
+     * Provider tanpa fitur refund mengembalikan `{ supported: false }`, bukan error.
+     */
+    refund(params: RefundParams, configOverride?: Partial<ProviderConfig>): Promise<RefundResult>;
+    /**
+     * Unified Check Balance — ambil saldo merchant dari provider aktif.
+     * Provider tanpa fitur balance mengembalikan `{ supported: false }`.
+     */
+    checkBalance(configOverride?: Partial<ProviderConfig>): Promise<CheckBalanceResult>;
+    /**
+     * Unified Disburse / Payout — transfer dana ke rekening bank tujuan.
+     * Provider tanpa fitur disbursement mengembalikan `{ supported: false }`.
+     */
+    disburse(params: DisburseParams, configOverride?: Partial<ProviderConfig>): Promise<DisburseResult>;
     getMidtransClient(configOverride?: Partial<ProviderConfig>): MidtransClient;
     getDuitkuClient(configOverride?: Partial<ProviderConfig>): DuitkuClient;
     getIpaymuClient(configOverride?: Partial<ProviderConfig>): IpaymuClient;
@@ -1403,4 +1479,4 @@ declare function safeCompare(a: string, b: string): boolean;
  */
 declare function getPaymentMethodCategory(code: string, name?: string): "Virtual Account" | "QRIS" | "E-Wallet" | "Retail / Gerai" | "Kartu Kredit" | "Paylater / Cicilan" | "Lainnya";
 
-export { AdyenClient, AdyenProvider, BasePaymentProvider, BraintreeClient, BraintreeProvider, Buayar, type BuayarConfig, CANONICAL_TO_DOKU, CANONICAL_TO_DUITKU, CANONICAL_TO_FASPAY, CANONICAL_TO_FINPAY, CANONICAL_TO_IPAYMU, CANONICAL_TO_MIDTRANS, CANONICAL_TO_NICEPAY, CANONICAL_TO_OY, CANONICAL_TO_PRISMALINK, CANONICAL_TO_STRIPE, CANONICAL_TO_XENDIT, CORE_API_METHODS, type CanonicalPaymentMethod, type CheckTransactionParams, type CheckTransactionResult, CheckoutComClient, CheckoutComProvider, type CreateInvoiceParams, type CustomerDetails, DUITKU_TO_CANONICAL, DokuClient, DokuProvider, DuitkuClient, type DuitkuDisbursementParams, DuitkuProvider, FaspayClient, FaspayProvider, FinpayClient, FinpayProvider, type GetPaymentMethodsParams, type GetPaymentMethodsResult, type InvoiceResponse, IpaymuClient, IpaymuProvider, MIDTRANS_PROBE_PAYLOADS, MIDTRANS_STATIC_METHODS, type MandiriBillInfo, MidtransClient, MidtransProvider, NicepayClient, NicepayProvider, OyClient, OyProvider, PaymentManager, type PaymentMethod, type PaymentMethodItem, PaypalClient, PaypalProvider, PayuClient, PayuProvider, PrismalinkClient, PrismalinkProvider, type ProviderConfig, RazorpayClient, RazorpayProvider, SquareClient, SquareProvider, StripeClient, StripeProvider, TwoCheckoutClient, TwoCheckoutProvider, type VerifyCallbackResult, XenditClient, type XenditDisbursementParams, XenditProvider, buayar, buildBraintreeBasicAuth, buildCoreChargePayload, buildPaypalBasicAuth, buildPayuBasicAuth, buildRazorpayBasicAuth, buildTwoCheckoutAuth, formatNicepayTimestamp, generateDokuHeaders, generateFaspaySignature, generateFinpaySignature, generateIpaymuSignature, generateNicepayToken, generateOyHeaders, generatePrismalinkSignature, getDuitkuInquirySignatures, getDuitkuPaymentMethodsSignature, getDuitkuStatusSignatures, getPaymentMethodCategory, getXenditAuthHeader, hmacSha256, md5, parseCoreChargeResponse, paymentManager, resolveConfigFromEnv, safeCompare, serializePaypalParams, serializeStripeParams, sha256, sha512, toCanonicalPaymentMethod, toDokuPaymentMethod, toDuitkuPaymentMethod, toFaspayPaymentMethod, toFinpayPaymentMethod, toIpaymuPaymentMethod, toNicepayPaymentMethod, toOyPaymentMethod, toPrismalinkPaymentMethod, toStripePaymentMethod, toXenditPaymentMethod, verifyAdyenWebhook, verifyBraintreeWebhook, verifyCheckoutComWebhook, verifyDokuWebhookSignature, verifyDuitkuCallbackSignature, verifyFaspaySignature, verifyFinpaySignature, verifyIpaymuCallback, verifyNicepayWebhook, verifyOyWebhook, verifyPaypalWebhookSimple, verifyPayuWebhook, verifyPrismalinkSignature, verifyRazorpayWebhook, verifySquareWebhook, verifyStripeWebhook, verifyTwoCheckoutWebhook, verifyXenditWebhookToken };
+export { AdyenClient, AdyenProvider, BasePaymentProvider, BraintreeClient, BraintreeProvider, Buayar, type BuayarConfig, CANONICAL_TO_DOKU, CANONICAL_TO_DUITKU, CANONICAL_TO_FASPAY, CANONICAL_TO_FINPAY, CANONICAL_TO_IPAYMU, CANONICAL_TO_MIDTRANS, CANONICAL_TO_NICEPAY, CANONICAL_TO_OY, CANONICAL_TO_PRISMALINK, CANONICAL_TO_STRIPE, CANONICAL_TO_XENDIT, CORE_API_METHODS, type CanonicalPaymentMethod, type CheckBalanceResult, type CheckTransactionParams, type CheckTransactionResult, CheckoutComClient, CheckoutComProvider, type CreateInvoiceParams, type CustomerDetails, DUITKU_TO_CANONICAL, type DisburseParams, type DisburseResult, DokuClient, DokuProvider, DuitkuClient, type DuitkuDisbursementParams, DuitkuProvider, FaspayClient, FaspayProvider, FinpayClient, FinpayProvider, type GetPaymentMethodsParams, type GetPaymentMethodsResult, type InvoiceResponse, IpaymuClient, IpaymuProvider, MIDTRANS_PROBE_PAYLOADS, MIDTRANS_STATIC_METHODS, type MandiriBillInfo, MidtransClient, MidtransProvider, NicepayClient, NicepayProvider, OyClient, OyProvider, PaymentManager, type PaymentMethod, type PaymentMethodItem, PaypalClient, PaypalProvider, PayuClient, PayuProvider, PrismalinkClient, PrismalinkProvider, type ProviderConfig, RazorpayClient, RazorpayProvider, type RefundParams, type RefundResult, SquareClient, SquareProvider, StripeClient, StripeProvider, TwoCheckoutClient, TwoCheckoutProvider, type VerifyCallbackResult, XenditClient, type XenditDisbursementParams, XenditProvider, buayar, buildBraintreeBasicAuth, buildCoreChargePayload, buildPaypalBasicAuth, buildPayuBasicAuth, buildRazorpayBasicAuth, buildTwoCheckoutAuth, formatNicepayTimestamp, generateDokuHeaders, generateFaspaySignature, generateFinpaySignature, generateIpaymuSignature, generateNicepayToken, generateOyHeaders, generatePrismalinkSignature, getDuitkuInquirySignatures, getDuitkuPaymentMethodsSignature, getDuitkuStatusSignatures, getPaymentMethodCategory, getXenditAuthHeader, hmacSha256, md5, parseCoreChargeResponse, paymentManager, resolveConfigFromEnv, safeCompare, serializePaypalParams, serializeStripeParams, sha256, sha512, toCanonicalPaymentMethod, toDokuPaymentMethod, toDuitkuPaymentMethod, toFaspayPaymentMethod, toFinpayPaymentMethod, toIpaymuPaymentMethod, toNicepayPaymentMethod, toOyPaymentMethod, toPrismalinkPaymentMethod, toStripePaymentMethod, toXenditPaymentMethod, verifyAdyenWebhook, verifyBraintreeWebhook, verifyCheckoutComWebhook, verifyDokuWebhookSignature, verifyDuitkuCallbackSignature, verifyFaspaySignature, verifyFinpaySignature, verifyIpaymuCallback, verifyNicepayWebhook, verifyOyWebhook, verifyPaypalWebhookSimple, verifyPayuWebhook, verifyPrismalinkSignature, verifyRazorpayWebhook, verifySquareWebhook, verifyStripeWebhook, verifyTwoCheckoutWebhook, verifyXenditWebhookToken };

package/dist/index.js

@@ -8914,6 +8914,184 @@ var PaymentManager = class {
     }
     return { success: false, enabled: [], error: `Provider '${providerName}' does not support payment methods probing` };
   }
+  // ─── Unified Advanced Operations (Refund / Balance / Disburse) ─────────────
+  // "Mata tertutup": satu API untuk semua provider yang mendukung fitur.
+  // Provider yang tidak mendukung mengembalikan `supported: false` (bukan throw).
+  unsupported(supported, provider, operation, rawResponse = null) {
+    return { success: false, supported, provider, rawResponse, error: `Provider '${provider}' does not support ${operation}` };
+  }
+  async refund(providerName, params, config) {
+    const name = providerName.toLowerCase();
+    try {
+      switch (name) {
+        case "midtrans": {
+          const data = await this.getMidtransClient(config).refundTransaction(params.transactionId, {
+            amount: params.amount,
+            reason: params.reason
+          });
+          return { success: true, supported: true, provider: "midtrans", reference: data.transaction_id || data.order_id, status: data.status_message, rawResponse: data };
+        }
+        case "stripe": {
+          const data = await this.getStripeClient(config).createRefund(params.transactionId, params.amount);
+          return { success: true, supported: true, provider: "stripe", reference: data.id, status: data.status, rawResponse: data };
+        }
+        case "paypal": {
+          const data = await this.getPaypalClient(config).refundCapture(params.transactionId, params.amount, params.currency);
+          return { success: true, supported: true, provider: "paypal", reference: data.id, status: data.status, rawResponse: data };
+        }
+        case "adyen": {
+          const client = this.getAdyenClient(config);
+          const merchantAccount = config.extra?.merchantAccount || config.merchantCode || config.merchantId || "";
+          const data = await client.refundPayment(params.transactionId, params.amount || 0, params.currency || "IDR", merchantAccount);
+          return { success: true, supported: true, provider: "adyen", reference: data.pspReference, status: data.response, rawResponse: data };
+        }
+        case "checkoutcom": {
+          const data = await this.getCheckoutComClient(config).refundPayment(params.transactionId, params.amount);
+          return { success: true, supported: true, provider: "checkoutcom", reference: data.reference, status: data.status, rawResponse: data };
+        }
+        case "razorpay": {
+          const data = await this.getRazorpayClient(config).createRefund(params.transactionId, params.amount);
+          return { success: true, supported: true, provider: "razorpay", reference: data.id, status: data.status, rawResponse: data };
+        }
+        case "square": {
+          const client = this.getSquareClient(config);
+          const currency = (params.currency || "IDR").toUpperCase();
+          const idempotencyKey = config.extra?.idempotencyKey || `refund-${params.transactionId}-${Date.now()}`;
+          const data = await client.refundPayment(params.transactionId, Math.round(params.amount || 0), currency, idempotencyKey, params.reason);
+          const refund = data.refund;
+          return { success: !data.errors, supported: true, provider: "square", reference: refund?.id, status: refund?.status, rawResponse: data };
+        }
+        case "payu": {
+          const data = await this.getPayuClient(config).refundOrder(params.transactionId, params.amount, params.reason);
+          return { success: true, supported: true, provider: "payu", reference: data.orderId, status: data.status, rawResponse: data };
+        }
+        case "braintree": {
+          const data = await this.getBraintreeClient(config).refundTransaction(params.transactionId, params.amount);
+          return { success: true, supported: true, provider: "braintree", reference: data?.transaction?.id, status: data?.transaction?.status, rawResponse: data };
+        }
+        case "twocheckout": {
+          const data = await this.getTwoCheckoutClient(config).refundOrder(params.transactionId, params.amount || 0, params.reason);
+          return { success: true, supported: true, provider: "twocheckout", reference: data.refno, status: data.response_code, rawResponse: data };
+        }
+        default:
+          return this.unsupported(false, name, "refund");
+      }
+    } catch (e) {
+      return { success: false, supported: true, provider: name, rawResponse: null, error: e.message || "Refund failed" };
+    }
+  }
+  async checkBalance(providerName, config) {
+    const name = providerName.toLowerCase();
+    try {
+      let balance;
+      let currency;
+      let raw;
+      switch (name) {
+        case "midtrans": {
+          raw = await this.getMidtransClient(config).getBalance();
+          balance = raw?.balance ?? raw?.balance_amount ?? raw?.amount;
+          break;
+        }
+        case "duitku": {
+          const result = await this.getDuitkuClient(config).checkBalance();
+          return { success: result.success, supported: true, provider: "duitku", balance: result.balance, rawResponse: result.rawResponse, error: result.error };
+        }
+        case "ipaymu": {
+          const result = await this.getIpaymuClient(config).checkBalance();
+          return { success: result.success, supported: true, provider: "ipaymu", balance: result.balance, rawResponse: result.rawResponse, error: result.error };
+        }
+        case "xendit": {
+          const result = await this.getXenditClient(config).checkBalance("CASH");
+          return { success: result.success, supported: true, provider: "xendit", balance: result.balance, rawResponse: result.rawResponse, error: result.error };
+        }
+        case "oy": {
+          raw = await this.getOyClient(config).checkBalance();
+          balance = raw?.balance ?? raw?.data?.balance;
+          break;
+        }
+        case "stripe": {
+          raw = await this.getStripeClient(config).checkBalance();
+          const available = raw?.available?.[0];
+          balance = available?.amount;
+          currency = available?.currency;
+          break;
+        }
+        case "paypal": {
+          raw = await this.getPaypalClient(config).checkBalance();
+          const first = raw?.balances?.[0];
+          balance = first?.total_balance?.value !== void 0 ? Number(first.total_balance.value) * 100 : void 0;
+          currency = first?.currency_code;
+          break;
+        }
+        case "checkoutcom": {
+          raw = await this.getCheckoutComClient(config).checkBalance();
+          const first = raw?.data?.[0]?.available;
+          balance = first?.[0]?.value;
+          currency = first?.[0]?.currency;
+          break;
+        }
+        case "razorpay": {
+          raw = await this.getRazorpayClient(config).checkBalance();
+          balance = raw?.balance ?? raw?.amount;
+          currency = raw?.currency;
+          break;
+        }
+        case "square": {
+          raw = await this.getSquareClient(config).retrieveBalance();
+          balance = raw?.balance_money?.amount;
+          currency = raw?.balance_money?.currency;
+          break;
+        }
+        default:
+          return this.unsupported(false, name, "checkBalance");
+      }
+      return { success: true, supported: true, provider: name, balance, currency, rawResponse: raw };
+    } catch (e) {
+      return { success: false, supported: true, provider: name, rawResponse: null, error: e.message || "Balance check failed" };
+    }
+  }
+  async disburse(providerName, params, config) {
+    const name = providerName.toLowerCase();
+    try {
+      switch (name) {
+        case "duitku": {
+          const data = await this.getDuitkuClient(config).disburse({
+            bankCode: params.bankCode,
+            bankAccount: params.accountNumber,
+            amount: params.amount,
+            purpose: params.description || "Disbursement",
+            merchantOrderId: params.externalId
+          });
+          return { success: data?.statusCode === "00", supported: true, provider: "duitku", reference: params.externalId, status: data?.statusMessage, rawResponse: data };
+        }
+        case "xendit": {
+          const data = await this.getXenditClient(config).createDisbursement({
+            externalId: params.externalId,
+            bankCode: params.bankCode,
+            accountHolderName: params.accountHolderName || "",
+            accountNumber: params.accountNumber,
+            description: params.description || "Disbursement",
+            amount: params.amount
+          });
+          return { success: true, supported: true, provider: "xendit", reference: data.id, status: data.status, rawResponse: data };
+        }
+        case "oy": {
+          const data = await this.getOyClient(config).remit({
+            recipientBank: params.bankCode,
+            recipientAccount: params.accountNumber,
+            amount: params.amount,
+            note: params.description,
+            partnerTrxId: params.externalId
+          });
+          return { success: true, supported: true, provider: "oy", reference: params.externalId, status: data?.status, rawResponse: data };
+        }
+        default:
+          return this.unsupported(false, name, "disburse");
+      }
+    } catch (e) {
+      return { success: false, supported: true, provider: name, rawResponse: null, error: e.message || "Disbursement failed" };
+    }
+  }
 };
 var paymentManager = new PaymentManager();
 
@@ -9277,6 +9455,33 @@ var Buayar = class {
   async handleWebhook(payload, headers, configOverride) {
     return this.verifyWebhook(payload, headers, configOverride);
   }
+  /**
+   * Unified Refund — berlaku untuk semua provider yang mendukung refund.
+   * Provider tanpa fitur refund mengembalikan `{ supported: false }`, bukan error.
+   */
+  async refund(params, configOverride) {
+    const mergedConfig = { ...this.config, ...configOverride };
+    const providerName = configOverride?.provider || this.provider;
+    return this.manager.refund(providerName, params, mergedConfig);
+  }
+  /**
+   * Unified Check Balance — ambil saldo merchant dari provider aktif.
+   * Provider tanpa fitur balance mengembalikan `{ supported: false }`.
+   */
+  async checkBalance(configOverride) {
+    const mergedConfig = { ...this.config, ...configOverride };
+    const providerName = configOverride?.provider || this.provider;
+    return this.manager.checkBalance(providerName, mergedConfig);
+  }
+  /**
+   * Unified Disburse / Payout — transfer dana ke rekening bank tujuan.
+   * Provider tanpa fitur disbursement mengembalikan `{ supported: false }`.
+   */
+  async disburse(params, configOverride) {
+    const mergedConfig = { ...this.config, ...configOverride };
+    const providerName = configOverride?.provider || this.provider;
+    return this.manager.disburse(providerName, params, mergedConfig);
+  }
   // ─── Indonesian Provider Client Getters ───────────────────────────────────
   getMidtransClient(configOverride) {
     return new MidtransClient({ ...this.config, ...configOverride });

package/dist/index.mjs

@@ -8764,6 +8764,184 @@ var PaymentManager = class {
     }
     return { success: false, enabled: [], error: `Provider '${providerName}' does not support payment methods probing` };
   }
+  // ─── Unified Advanced Operations (Refund / Balance / Disburse) ─────────────
+  // "Mata tertutup": satu API untuk semua provider yang mendukung fitur.
+  // Provider yang tidak mendukung mengembalikan `supported: false` (bukan throw).
+  unsupported(supported, provider, operation, rawResponse = null) {
+    return { success: false, supported, provider, rawResponse, error: `Provider '${provider}' does not support ${operation}` };
+  }
+  async refund(providerName, params, config) {
+    const name = providerName.toLowerCase();
+    try {
+      switch (name) {
+        case "midtrans": {
+          const data = await this.getMidtransClient(config).refundTransaction(params.transactionId, {
+            amount: params.amount,
+            reason: params.reason
+          });
+          return { success: true, supported: true, provider: "midtrans", reference: data.transaction_id || data.order_id, status: data.status_message, rawResponse: data };
+        }
+        case "stripe": {
+          const data = await this.getStripeClient(config).createRefund(params.transactionId, params.amount);
+          return { success: true, supported: true, provider: "stripe", reference: data.id, status: data.status, rawResponse: data };
+        }
+        case "paypal": {
+          const data = await this.getPaypalClient(config).refundCapture(params.transactionId, params.amount, params.currency);
+          return { success: true, supported: true, provider: "paypal", reference: data.id, status: data.status, rawResponse: data };
+        }
+        case "adyen": {
+          const client = this.getAdyenClient(config);
+          const merchantAccount = config.extra?.merchantAccount || config.merchantCode || config.merchantId || "";
+          const data = await client.refundPayment(params.transactionId, params.amount || 0, params.currency || "IDR", merchantAccount);
+          return { success: true, supported: true, provider: "adyen", reference: data.pspReference, status: data.response, rawResponse: data };
+        }
+        case "checkoutcom": {
+          const data = await this.getCheckoutComClient(config).refundPayment(params.transactionId, params.amount);
+          return { success: true, supported: true, provider: "checkoutcom", reference: data.reference, status: data.status, rawResponse: data };
+        }
+        case "razorpay": {
+          const data = await this.getRazorpayClient(config).createRefund(params.transactionId, params.amount);
+          return { success: true, supported: true, provider: "razorpay", reference: data.id, status: data.status, rawResponse: data };
+        }
+        case "square": {
+          const client = this.getSquareClient(config);
+          const currency = (params.currency || "IDR").toUpperCase();
+          const idempotencyKey = config.extra?.idempotencyKey || `refund-${params.transactionId}-${Date.now()}`;
+          const data = await client.refundPayment(params.transactionId, Math.round(params.amount || 0), currency, idempotencyKey, params.reason);
+          const refund = data.refund;
+          return { success: !data.errors, supported: true, provider: "square", reference: refund?.id, status: refund?.status, rawResponse: data };
+        }
+        case "payu": {
+          const data = await this.getPayuClient(config).refundOrder(params.transactionId, params.amount, params.reason);
+          return { success: true, supported: true, provider: "payu", reference: data.orderId, status: data.status, rawResponse: data };
+        }
+        case "braintree": {
+          const data = await this.getBraintreeClient(config).refundTransaction(params.transactionId, params.amount);
+          return { success: true, supported: true, provider: "braintree", reference: data?.transaction?.id, status: data?.transaction?.status, rawResponse: data };
+        }
+        case "twocheckout": {
+          const data = await this.getTwoCheckoutClient(config).refundOrder(params.transactionId, params.amount || 0, params.reason);
+          return { success: true, supported: true, provider: "twocheckout", reference: data.refno, status: data.response_code, rawResponse: data };
+        }
+        default:
+          return this.unsupported(false, name, "refund");
+      }
+    } catch (e) {
+      return { success: false, supported: true, provider: name, rawResponse: null, error: e.message || "Refund failed" };
+    }
+  }
+  async checkBalance(providerName, config) {
+    const name = providerName.toLowerCase();
+    try {
+      let balance;
+      let currency;
+      let raw;
+      switch (name) {
+        case "midtrans": {
+          raw = await this.getMidtransClient(config).getBalance();
+          balance = raw?.balance ?? raw?.balance_amount ?? raw?.amount;
+          break;
+        }
+        case "duitku": {
+          const result = await this.getDuitkuClient(config).checkBalance();
+          return { success: result.success, supported: true, provider: "duitku", balance: result.balance, rawResponse: result.rawResponse, error: result.error };
+        }
+        case "ipaymu": {
+          const result = await this.getIpaymuClient(config).checkBalance();
+          return { success: result.success, supported: true, provider: "ipaymu", balance: result.balance, rawResponse: result.rawResponse, error: result.error };
+        }
+        case "xendit": {
+          const result = await this.getXenditClient(config).checkBalance("CASH");
+          return { success: result.success, supported: true, provider: "xendit", balance: result.balance, rawResponse: result.rawResponse, error: result.error };
+        }
+        case "oy": {
+          raw = await this.getOyClient(config).checkBalance();
+          balance = raw?.balance ?? raw?.data?.balance;
+          break;
+        }
+        case "stripe": {
+          raw = await this.getStripeClient(config).checkBalance();
+          const available = raw?.available?.[0];
+          balance = available?.amount;
+          currency = available?.currency;
+          break;
+        }
+        case "paypal": {
+          raw = await this.getPaypalClient(config).checkBalance();
+          const first = raw?.balances?.[0];
+          balance = first?.total_balance?.value !== void 0 ? Number(first.total_balance.value) * 100 : void 0;
+          currency = first?.currency_code;
+          break;
+        }
+        case "checkoutcom": {
+          raw = await this.getCheckoutComClient(config).checkBalance();
+          const first = raw?.data?.[0]?.available;
+          balance = first?.[0]?.value;
+          currency = first?.[0]?.currency;
+          break;
+        }
+        case "razorpay": {
+          raw = await this.getRazorpayClient(config).checkBalance();
+          balance = raw?.balance ?? raw?.amount;
+          currency = raw?.currency;
+          break;
+        }
+        case "square": {
+          raw = await this.getSquareClient(config).retrieveBalance();
+          balance = raw?.balance_money?.amount;
+          currency = raw?.balance_money?.currency;
+          break;
+        }
+        default:
+          return this.unsupported(false, name, "checkBalance");
+      }
+      return { success: true, supported: true, provider: name, balance, currency, rawResponse: raw };
+    } catch (e) {
+      return { success: false, supported: true, provider: name, rawResponse: null, error: e.message || "Balance check failed" };
+    }
+  }
+  async disburse(providerName, params, config) {
+    const name = providerName.toLowerCase();
+    try {
+      switch (name) {
+        case "duitku": {
+          const data = await this.getDuitkuClient(config).disburse({
+            bankCode: params.bankCode,
+            bankAccount: params.accountNumber,
+            amount: params.amount,
+            purpose: params.description || "Disbursement",
+            merchantOrderId: params.externalId
+          });
+          return { success: data?.statusCode === "00", supported: true, provider: "duitku", reference: params.externalId, status: data?.statusMessage, rawResponse: data };
+        }
+        case "xendit": {
+          const data = await this.getXenditClient(config).createDisbursement({
+            externalId: params.externalId,
+            bankCode: params.bankCode,
+            accountHolderName: params.accountHolderName || "",
+            accountNumber: params.accountNumber,
+            description: params.description || "Disbursement",
+            amount: params.amount
+          });
+          return { success: true, supported: true, provider: "xendit", reference: data.id, status: data.status, rawResponse: data };
+        }
+        case "oy": {
+          const data = await this.getOyClient(config).remit({
+            recipientBank: params.bankCode,
+            recipientAccount: params.accountNumber,
+            amount: params.amount,
+            note: params.description,
+            partnerTrxId: params.externalId
+          });
+          return { success: true, supported: true, provider: "oy", reference: params.externalId, status: data?.status, rawResponse: data };
+        }
+        default:
+          return this.unsupported(false, name, "disburse");
+      }
+    } catch (e) {
+      return { success: false, supported: true, provider: name, rawResponse: null, error: e.message || "Disbursement failed" };
+    }
+  }
 };
 var paymentManager = new PaymentManager();
 
@@ -9127,6 +9305,33 @@ var Buayar = class {
   async handleWebhook(payload, headers, configOverride) {
     return this.verifyWebhook(payload, headers, configOverride);
   }
+  /**
+   * Unified Refund — berlaku untuk semua provider yang mendukung refund.
+   * Provider tanpa fitur refund mengembalikan `{ supported: false }`, bukan error.
+   */
+  async refund(params, configOverride) {
+    const mergedConfig = { ...this.config, ...configOverride };
+    const providerName = configOverride?.provider || this.provider;
+    return this.manager.refund(providerName, params, mergedConfig);
+  }
+  /**
+   * Unified Check Balance — ambil saldo merchant dari provider aktif.
+   * Provider tanpa fitur balance mengembalikan `{ supported: false }`.
+   */
+  async checkBalance(configOverride) {
+    const mergedConfig = { ...this.config, ...configOverride };
+    const providerName = configOverride?.provider || this.provider;
+    return this.manager.checkBalance(providerName, mergedConfig);
+  }
+  /**
+   * Unified Disburse / Payout — transfer dana ke rekening bank tujuan.
+   * Provider tanpa fitur disbursement mengembalikan `{ supported: false }`.
+   */
+  async disburse(params, configOverride) {
+    const mergedConfig = { ...this.config, ...configOverride };
+    const providerName = configOverride?.provider || this.provider;
+    return this.manager.disburse(providerName, params, mergedConfig);
+  }
   // ─── Indonesian Provider Client Getters ───────────────────────────────────
   getMidtransClient(configOverride) {
     return new MidtransClient({ ...this.config, ...configOverride });

package/docs/guide.md

@@ -0,0 +1,356 @@
+# 💳 Panduan Unified `@crediblemark/buayar`
+
+Panduan ini adalah **satu-satunya** panduan yang Anda butuhkan untuk mengintegrasikan **semua** payment gateway yang didukung Buayar (19 provider: 10 Indonesia + 9 Internasional). Anda **tidak perlu** membaca dokumentasi masing-masing PG — kode yang Anda tulis **identik** untuk semua provider.
+
+> 🎯 **Prinsip "mata tertutup":** Anda 100% tidak tahu (dan tidak perlu tahu) provider mana yang sedang aktif. Yang Anda tahu hanya: "Buaya mendukung PG A, PG B, PG C". Cukup ubah kredensial di `.env`, semuanya jalan.
+
+---
+
+## 📑 Daftar Isi
+
+1. [Filosofi Unified](#-filosofi-unified)
+2. [Inisialisasi & Konfigurasi](#-inisialisasi--konfigurasi)
+3. [Membuat Transaksi (Semi & Full)](#-membuat-transaksi)
+4. [Ambil Metode Pembayaran (Accordion-Ready)](#-ambil-metode-pembayaran)
+5. [Cek Status Transaksi](#-cek-status-transaksi)
+6. [Webhook Universal](#-webhook-universal)
+7. [Refund / Saldo / Payout Unified](#-refund--saldo--payout-unified)
+8. [Zero-Code PG Switch](#-zero-code-pg-switch)
+9. [Fitur Khusus Provider (`<X>Client`)](#-fitur-khusus-provider-xclient)
+10. [Kamus Variabel `.env` per Provider](#-kamus-variabel-env-per-provider)
+
+---
+
+## 🧠 Filosofi Unified
+
+Seluruh provider mengimplementasikan **satu kontrak API** yang sama. Artinya:
+
+| Kebutuhan Anda | API yang Anda gunakan |
+| :--- | :--- |
+| Checkout (redirect / direct) | `buayar.createInvoice()` |
+| Daftar channel pembayaran | `buayar.getPaymentMethods()` |
+| Cek status transaksi | `buayar.checkTransaction()` |
+| Verifikasi callback | `buayar.verifyWebhook()` |
+| Refund | `buayar.refund()` |
+| Cek saldo merchant | `buayar.checkBalance()` |
+| Transfer dana / payout | `buayar.disburse()` |
+| Fitur benar-benar eksklusif per PG | `buayar.get<X>Client()` |
+
+Semua metode pembayaran memakai **kode canonical universal** (`bca_va`, `qris`, `gopay`, `alfamart`, dst.) yang dipetakan otomatis ke format internal provider aktif. Anda tidak pernah menyentuh format internal siapa pun.
+
+---
+
+## ⚙️ Inisialisasi & Konfigurasi
+
+### 1. Zero-Config (baca dari `.env`) — **Direkomendasikan**
+
+```env
+# Pilih provider aktif: midtrans, duitku, ipaymu, xendit, doku, prismalink,
+# faspay, finpay, nicepay, oy, stripe, paypal, adyen, checkoutcom,
+# razorpay, square, payu, braintree, twocheckout
+PROVIDER_PG=midtrans
+
+# Kredensial Universal (dipetakan otomatis per provider)
+BUAYAR_API_KEY=your-server-key-atau-secret
+BUAYAR_MERCHANT_CODE=merchant-id-atau-username
+BUAYAR_SANDBOX=true
+
+# Callback & Return URL
+BUAYAR_CALLBACK_URL=https://myapp.com/api/payment/webhook
+BUAYAR_RETURN_URL=https://myapp.com/payment/finish
+```
+
+```typescript
+import { buayar } from "@crediblemark/buayar";
+// Konfigurasi ter-baca otomatis dari process.env. Selesai.
+```
+
+### 2. Inisialisasi Manual (programatik)
+
+```typescript
+import { Buayar } from "@crediblemark/buayar";
+
+const buayar = new Buayar({
+  provider: "xendit",
+  apiKey: "xnd_development_xxxx",
+  merchantCode: "",              // jika dibutuhkan (mis. Midtrans boleh kosong)
+  sandbox: true,
+  extra: { webhookSecret: "whsec_..." }, // untuk provider yang butuh secret tambahan
+});
+```
+
+> 💡 Banyak `get<X>Client()` juga bisa dipakai dengan meneruskan `provider` di `configOverride` agar menargetkan provider tertentu dari satu instance `buayar`.
+
+---
+
+## 🛠️ Membuat Transaksi
+
+### Semi Integrasi (Redirect / Hosted Checkout)
+
+Tanpa `paymentMethod`, SDK mengembalikan `paymentUrl` untuk mengarahkan pelanggan ke halaman checkout PG.
+
+```typescript
+import { buayar } from "@crediblemark/buayar";
+
+const invoice = await buayar.createInvoice({
+  orderId: "ORDER-1001",
+  amount: 250000,
+  currency: "IDR",               // wajib untuk PG internasional (USD, EUR, dll)
+  productDetails: "Pembelian Lisensi Software Premium",
+  customer: { name: "Budi", email: "budi@example.com", phone: "081234567890" },
+  returnUrl: "https://myapp.com/payment/success",
+});
+
+if (invoice.success) {
+  redirect(invoice.paymentUrl!);  // redirect pelanggan ke sini
+}
+```
+
+### Full Integrasi (Custom Native UI)
+
+Sertakan `paymentMethod` dengan **kode canonical**. SDK mengembalikan data mentah (`vaNumber`, `qrString` EMVCo, `paymentCode`, `deeplink`) untuk dirender di UI Anda sendiri.
+
+```typescript
+// Virtual Account
+const va = await buayar.createInvoice({
+  orderId: "ORDER-1002",
+  amount: 150000,
+  paymentMethod: "bca_va",   // canonical — berlaku di semua provider
+  productDetails: "Top Up Saldo",
+  customer: { name: "Budi", email: "budi@example.com" },
+});
+console.log("Nomor VA:", va.vaNumber);   // "123456789012"
+console.log("Bank:", va.vaBank);         // "bca"
+
+// QRIS
+const qris = await buayar.createInvoice({
+  orderId: "ORDER-1003",
+  amount: 50000,
+  paymentMethod: "qris",
+  productDetails: "Kopi",
+  customer: { name: "Budi", email: "budi@example.com" },
+});
+console.log("Raw QRIS (EMVCo):", qris.qrString);   // untuk dirender
+console.log("QR Image URL:", qris.qrCodeUrl);
+```
+
+### Menargetkan Provider Tertentu (opsional)
+
+Jika satu instance `buayar` dipakai untuk beberapa provider sekaligus, lewatkan `provider` pada `configOverride`:
+
+```typescript
+const stripeInvoice = await buayar.createInvoice(
+  { orderId: "ORDER-2001", amount: 50000, paymentMethod: "credit_card" },
+  { provider: "stripe", apiKey: "sk_test_..." }   // override provider & kredensial
+);
+```
+
+---
+
+## 📋 Ambil Metode Pembayaran
+
+Dapatkan daftar channel aktif yang sudah dikelompokkan per kategori (accordion-ready), lengkap dengan fee dan icon URL.
+
+```typescript
+const { categories } = await buayar.getPaymentMethods({ amount: 150000 });
+// categories: { "Virtual Account": [...], "QRIS": [...], "E-Wallet": [...], ... }
+```
+
+---
+
+## 🔍 Cek Status Transaksi
+
+```typescript
+const result = await buayar.checkTransaction({ merchantOrderId: "ORDER-1001" });
+
+if (result.success) {
+  console.log("Status:", result.status);          // "paid" | "pending" | "failed"
+  console.log("Pesan:", result.statusMessage);
+}
+```
+
+---
+
+## 🪝 Webhook Universal
+
+Satu endpoint untuk semua provider. Provider **terdeteksi otomatis** dari struktur payload — tidak ada routing manual.
+
+```typescript
+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.)
+
+  if (!result.isValid) return res.status(400).json({ error: "Invalid signature" });
+
+  if (result.isPaid) {
+    console.log(`✅ Order ${result.orderId} senilai ${result.amount} LUNAS!`);
+    // Aktifkan langganan / kirim produk
+  }
+
+  return res.status(200).json({ status: "OK" });
+});
+```
+
+> `buayar.handleWebhook(payload, headers)` adalah alias dari `verifyWebhook`.
+
+---
+
+## 💸 Refund / Saldo / Payout Unified
+
+Selain alur transaksi inti, Buayar menyediakan **operasi lanjutan unified** untuk hal-hal yang paling sering dipakai: **refund**, **cek saldo**, dan **payout** (disbursement).
+
+Sama seperti operasi lainnya — kode Anda **tidak bergantung provider**. Setiap operasi otomatis diarahkan ke provider aktif.
+
+> 🧊 **Provider tanpa fitur** mengembalikan `{ supported: false }` — bukan error. Anda bisa cek `result.supported` untuk menangani fallback.
+
+### 1. Refund
+
+```typescript
+const refund = await buayar.refund({
+  transactionId: "pi_3MtwBwLkdIwHu7ix28a3tqPa", // ID transaksi/capture/payment
+  amount: 50000,       // opsional — default full refund
+  reason: "Produk cacat", // opsional, bila didukung provider
+  currency: "IDR",     // opsional, untuk provider internasional
+});
+
+if (refund.success) {
+  console.log("Refund diproses:", refund.reference);
+} else if (!refund.supported) {
+  console.log("Provider aktif tidak mendukung refund!");
+}
+```
+
+Mendukung: **Midtrans, Stripe, PayPal, Adyen, Checkout.com, Razorpay, Square, PayU, Braintree, 2Checkout**.
+
+### 2. Cek Saldo Merchant
+
+```typescript
+const balance = await buayar.checkBalance();
+
+if (balance.success) {
+  console.log("Saldo:", balance.balance, balance.currency);
+}
+```
+
+Mendukung: **Midtrans, Duitku, iPaymu, Xendit, OY!, Stripe, PayPal, Checkout.com, Razorpay, Square**.
+
+### 3. Payout / Transfer Dana (Disbursement)
+
+```typescript
+const payout = await buayar.disburse({
+  externalId: "DISB-001",   // ID unik merchant untuk transfer ini
+  bankCode: "BCA",          // kode bank tujuan (ikuti aturan provider aktif)
+  accountHolderName: "Budi Santoso", // wajib untuk beberapa provider
+  accountNumber: "1234567890",
+  amount: 500000,
+  description: "Penarikan saldo mitra",
+});
+
+if (payout.success) {
+  console.log("Transfer diproses:", payout.reference);
+}
+```
+
+Mendukung: **Duitku, Xendit, OY!**.
+
+---
+
+## 🔄 Zero-Code PG Switch
+
+Beralih provider **tanpa mengubah satu baris pun** di controller/service Anda — cukup ubah kredensial di `.env`:
+
+```env
+# Sebelum: Midtrans
+PROVIDER_PG=midtrans
+MIDTRANS_SERVER_KEY=SB-Mid-server-xxxx
+
+# Sesudah: Stripe — kode aplikasi TIDAK berubah
+PROVIDER_PG=stripe
+STRIPE_SECRET_KEY=sk_test_51...
+STRIPE_WEBHOOK_SECRET=whsec_...
+```
+
+---
+
+## 🏦 Fitur Khusus Provider (`<X>Client`)
+
+Refund, saldo, dan payout sudah tersedia secara **unified** di atas. Namun untuk **fitur yang benar-benar eksklusif** tiap PG yang tidak masuk interface umum (subscription, payment link, tokenisasi GoPay, billing invoice, dsb.), pakai getter client per provider:
+
+```typescript
+const xendit = buayar.getXenditClient();
+const balance = await xendit.checkBalance("CASH");
+```
+
+Rangkuman kemampuan ekstra tiap provider:
+
+| Provider | Getter | Kemampuan ekstra |
+| :--- | :--- | :--- |
+| Midtrans | `getMidtransClient()` | cancel/refund/expire/approve/deny/capture, GoPay tokenization, Subscription, Payment Link, IRIS balance |
+| Duitku | `getDuitkuClient()` | balance, listBanks, inquiryBankAccount, disburse, checkDisbursementStatus |
+| iPaymu | `getIpaymuClient()` | balance, checkTransaction |
+| Xendit | `getXenditClient()` | balance, expireInvoice, createDisbursement |
+| DOKU | `getDokuClient()` | checkTransaction |
+| PrismaLink | `getPrismalinkClient()` | checkTransaction |
+| Faspay | `getFaspayClient()` | cancelTransaction, checkTransaction |
+| Finpay | `getFinpayClient()` | checkTransaction |
+| Nicepay | `getNicepayClient()` | cancelTransaction, checkTransaction |
+| OY! Bisnis | `getOyClient()` | checkTransaction, balance, remit (transfer dana) |
+| Stripe | `getStripeClient()` | balance, createRefund, retrieveCheckoutSession, retrievePaymentIntent |
+| PayPal | `getPaypalClient()` | captureOrder, getOrder, refundCapture, checkBalance, verifyWebhookSignature |
+| Adyen | `getAdyenClient()` | capturePayment, cancelPayment, refundPayment, getPaymentDetails, getAvailablePaymentMethods |
+| Checkout.com | `getCheckoutComClient()` | balance, refundPayment, voidPayment, getPaymentDetails, listPaymentLinks |
+| Razorpay | `getRazorpayClient()` | capturePayment, createRefund, checkBalance, fetchPayment, listPayments |
+| Square | `getSquareClient()` | retrieveBalance, refundPayment, cancelPayment, getPayment, listLocations |
+| PayU | `getPayuClient()` | cancelOrder, getOrder, refundOrder |
+| Braintree | `getBraintreeClient()` | getClientToken, findTransaction, refundTransaction, voidTransaction |
+| 2Checkout | `getTwoCheckoutClient()` | getOrder, listOrders, getSubscription, refundOrder |
+
+---
+
+## 📚 Kamus Variabel `.env` per Provider
+
+Anda hanya perlu mengisi kredensial provider yang **sedang aktif**. Gunakan variabel universal (`BUAYAR_*`) bila ingin kode benar-benar provider-agnostic, atau variabel spesifik di bawah.
+
+| Provider | Variabel `.env` |
+| :--- | :--- |
+| Midtrans | `MIDTRANS_SERVER_KEY`, `MIDTRANS_CLIENT_KEY` |
+| Duitku | `DUITKU_API_KEY`, `DUITKU_MERCHANT_CODE` |
+| iPaymu | `IPAYMU_API_KEY`, `IPAYMU_VA` |
+| Xendit | `XENDIT_SECRET_KEY`, `XENDIT_WEBHOOK_TOKEN` |
+| DOKU | `DOKU_CLIENT_ID`, `DOKU_SECRET_KEY` |
+| PrismaLink | `PRISMALINK_MERCHANT_ID`, `PRISMALINK_SECRET_KEY` |
+| Faspay | `FASPAY_MERCHANT_ID`, `FASPAY_USER_ID`, `FASPAY_PASSWORD`, `FASPAY_MERCHANT_NAME` |
+| Finpay | `FINPAY_MERCHANT_ID`, `FINPAY_MERCHANT_KEY` |
+| Nicepay | `NICEPAY_IMID`, `NICEPAY_KEY` |
+| OY! Bisnis | `OY_USERNAME`, `OY_API_KEY` |
+| Stripe | `STRIPE_SECRET_KEY`, `STRIPE_PUBLIC_KEY`, `STRIPE_WEBHOOK_SECRET` |
+| PayPal | `PAYPAL_CLIENT_ID`, `PAYPAL_CLIENT_SECRET`, `PAYPAL_WEBHOOK_ID` |
+| Adyen | `ADYEN_API_KEY`, `ADYEN_MERCHANT_ACCOUNT`, `ADYEN_CLIENT_KEY`, `ADYEN_HMAC_KEY`, `ADYEN_LIVE_URL_PREFIX` |
+| Checkout.com | `CHECKOUTCOM_SECRET_KEY`, `CHECKOUTCOM_PUBLIC_KEY`, `CHECKOUTCOM_WEBHOOK_SECRET` |
+| Razorpay | `RAZORPAY_KEY_ID`, `RAZORPAY_KEY_SECRET`, `RAZORPAY_WEBHOOK_SECRET` |
+| Square | `SQUARE_ACCESS_TOKEN`, `SQUARE_APPLICATION_ID`, `SQUARE_LOCATION_ID`, `SQUARE_WEBHOOK_SIGNATURE_KEY` |
+| PayU | `PAYU_POS_ID`, `PAYU_MD5_KEY`, `PAYU_OAUTH_CLIENT_ID`, `PAYU_OAUTH_CLIENT_SECRET` |
+| Braintree | `BRAINTREE_MERCHANT_ID`, `BRAINTREE_PUBLIC_KEY`, `BRAINTREE_PRIVATE_KEY` |
+| 2Checkout | `TWOCHECKOUT_MERCHANT_CODE`, `TWOCHECKOUT_SECRET_KEY`, `TWOCHECKOUT_SECRET_WORD` |
+
+Sandbox: otomatis terdeteksi dari `BUAYAR_SANDBOX`/`NODE_ENV`, atau set per-provider (mis. `STRIPE_SANDBOX=true`, `MIDTRANS_SANDBOX=true`).
+
+---
+
+## 🏷️ Daftar Canonical Payment Methods
+
+| Kategori | Canonical Code |
+| :--- | :--- |
+| **Virtual Account** | `bca_va`, `mandiri_va`, `bni_va`, `bri_va`, `permata_va`, `cimb_va`, `danamon_va`, `bsi_va`, `seabank_va` |
+| **QRIS** | `qris`, `gopay_qris`, `shopeepay_qris`, `nobu_qris` |
+| **E-Wallet** | `gopay`, `shopeepay`, `ovo`, `dana`, `linkaja`, `jenius` |
+| **Retail** | `alfamart`, `indomaret`, `pos` |
+| **Kartu Kredit** | `credit_card` |
+| **Paylater** | `kredivo`, `akulaku`, `indodana` |
+| **International** | `apple_pay`, `google_pay`, `paypal`, `klarna`, `sepa` |
+
+> Tidak semua canonical code tersedia di semua provider. Selalu gunakan `getPaymentMethods()` untuk memfilter channel yang benar-benar aktif pada provider Anda.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediblemark/buayar",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "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",
@@ -51,6 +51,7 @@
   ],
   "files": [
     "dist",
+    "docs",
     "package.json",
     "README.md"
   ],