@crediblemark/buayar 0.7.0 → 0.8.1

package/dist/index.mjs

@@ -123,6 +123,9 @@ var CANONICAL_TO_IPAYMU = {
   permata_va: { paymentMethod: "va", paymentChannel: "permata" },
   danamon_va: { paymentMethod: "va", paymentChannel: "danamon" },
   bsi_va: { paymentMethod: "va", paymentChannel: "bsi" },
+  bag_va: { paymentMethod: "va", paymentChannel: "bag" },
+  muamalat_va: { paymentMethod: "va", paymentChannel: "bmi" },
+  bmi_va: { paymentMethod: "va", paymentChannel: "bmi" },
   qris: { paymentMethod: "qris", paymentChannel: "mpm" },
   gopay_qris: { paymentMethod: "qris", paymentChannel: "mpm" },
   shopeepay_qris: { paymentMethod: "qris", paymentChannel: "mpm" },
@@ -1548,8 +1551,8 @@ var MidtransProvider = class extends BasePaymentProvider {
 // src/providers/ipaymu/signature.ts
 function generateIpaymuSignature(method, va, apiKey, body) {
   const timestamp = Date.now().toString();
-  const bodyString = body ? typeof body === "string" ? body : JSON.stringify(body) : "";
-  const bodyHash = body ? sha256(bodyString).toLowerCase() : "";
+  const bodyString = body ? typeof body === "string" ? body : JSON.stringify(body) : "{}";
+  const bodyHash = sha256(bodyString).toLowerCase();
   const stringToSign = `${method.toUpperCase()}:${va}:${bodyHash}:${apiKey}`;
   const signature = hmacSha256(stringToSign, apiKey);
   return { signature, timestamp };
@@ -1580,35 +1583,51 @@ var IpaymuProvider = class extends BasePaymentProvider {
     const baseUrl = this.getBaseUrl(sandbox);
     const endpoint = isDirect ? "/payment/direct" : "/payment";
     const url = `${baseUrl}${endpoint}`;
+    const notifyUrl = callbackUrl || config.callbackUrl || "https://localhost/callback";
+    const redirectUrl = returnUrl || config.returnUrl || "https://localhost/return";
+    const feeDirection = params.feeDirection || params.extra?.feeDirection || config.extra?.feeDirection;
+    const escrow = params.escrow !== void 0 ? params.escrow : params.extra?.escrow !== void 0 ? params.extra?.escrow : config.extra?.escrow;
+    const subAccount = params.subAccountId || params.extra?.subAccountId || params.extra?.account || params.extra?.childAccount || params.account || config.extra?.account;
     let payload;
     if (isDirect) {
       payload = {
         name: customer.name,
         email: customer.email,
-        phone: customer.phone || "",
+        phone: customer.phone || "081234567890",
         amount: integerAmount,
-        notifyUrl: callbackUrl || config.callbackUrl || "",
+        notifyUrl,
         expired: 24,
         expiredType: "hours",
         comments: productDetails,
         referenceId: orderId,
         paymentMethod: ipaymuMethod.paymentMethod,
         ...ipaymuMethod.paymentChannel ? { paymentChannel: ipaymuMethod.paymentChannel } : {},
+        ...feeDirection ? { feeDirection } : {},
+        ...escrow !== void 0 ? { escrow } : {},
+        ...subAccount ? { account: subAccount } : {},
         ...params.providerParams
       };
     } else {
+      const hasItems = params.items && params.items.length > 0;
+      const product = hasItems ? params.items.map((i) => i.name) : [productDetails.length > 50 ? productDetails.substring(0, 47) + "..." : productDetails];
+      const qty = hasItems ? params.items.map((i) => i.quantity) : [1];
+      const price = hasItems ? params.items.map((i) => Math.round(i.price)) : [integerAmount];
+      const description = hasItems ? params.items.map((i) => i.description || i.name) : [productDetails];
       payload = {
-        product: [productDetails.length > 50 ? productDetails.substring(0, 47) + "..." : productDetails],
-        qty: [1],
-        price: [integerAmount],
-        description: [productDetails],
-        returnUrl: returnUrl || config.returnUrl || "",
-        notifyUrl: callbackUrl || config.callbackUrl || "",
-        cancelUrl: returnUrl || config.returnUrl || "",
+        product,
+        qty,
+        price,
+        description,
+        returnUrl: redirectUrl,
+        notifyUrl,
+        cancelUrl: redirectUrl,
         referenceId: orderId,
         buyerName: customer.name,
         buyerEmail: customer.email,
-        buyerPhone: customer.phone || "",
+        buyerPhone: customer.phone || "081234567890",
+        ...feeDirection ? { feeDirection } : {},
+        ...escrow !== void 0 ? { escrow } : {},
+        ...subAccount ? { account: subAccount } : {},
         ...params.providerParams
       };
     }
@@ -1648,8 +1667,8 @@ var IpaymuProvider = class extends BasePaymentProvider {
           provider: "ipaymu",
           orderId,
           amount: integerAmount,
-          reference: resData.TransactionId ? String(resData.TransactionId) : String(resData.SessionId || ""),
-          paymentUrl: resData.Url,
+          reference: resData.TransactionId ? String(resData.TransactionId) : String(resData.SessionId || resData.SessionID || ""),
+          paymentUrl: resData.Url || resData.url,
           rawResponse: data
         };
         if (resData.PaymentNo) {
@@ -1708,126 +1727,109 @@ var IpaymuProvider = class extends BasePaymentProvider {
     };
   }
   async getPaymentMethods(params, config) {
-    const staticMethods = [
-      {
-        paymentMethod: "bca_va",
-        code: "bca_va",
-        paymentName: "BCA Virtual Account",
-        paymentImage: "https://my.ipaymu.com/images/banks/bca.png",
-        totalFee: "IDR 3,500",
-        category: "Virtual Account"
-      },
-      {
-        paymentMethod: "mandiri_va",
-        code: "mandiri_va",
-        paymentName: "Mandiri Virtual Account",
-        paymentImage: "https://my.ipaymu.com/images/banks/mandiri.png",
-        totalFee: "IDR 3,500",
-        category: "Virtual Account"
-      },
-      {
-        paymentMethod: "bni_va",
-        code: "bni_va",
-        paymentName: "BNI Virtual Account",
-        paymentImage: "https://my.ipaymu.com/images/banks/bni.png",
-        totalFee: "IDR 3,500",
-        category: "Virtual Account"
-      },
-      {
-        paymentMethod: "bri_va",
-        code: "bri_va",
-        paymentName: "BRI Virtual Account",
-        paymentImage: "https://my.ipaymu.com/images/banks/bri.png",
-        totalFee: "IDR 3,500",
-        category: "Virtual Account"
-      },
-      {
-        paymentMethod: "cimb_va",
-        code: "cimb_va",
-        paymentName: "CIMB Niaga Virtual Account",
-        paymentImage: "https://my.ipaymu.com/images/banks/cimb.png",
-        totalFee: "IDR 3,500",
-        category: "Virtual Account"
-      },
-      {
-        paymentMethod: "permata_va",
-        code: "permata_va",
-        paymentName: "Permata Virtual Account",
-        paymentImage: "https://my.ipaymu.com/images/banks/permata.png",
-        totalFee: "IDR 3,500",
-        category: "Virtual Account"
-      },
-      {
-        paymentMethod: "danamon_va",
-        code: "danamon_va",
-        paymentName: "Danamon Virtual Account",
-        paymentImage: "https://my.ipaymu.com/images/banks/danamon.png",
-        totalFee: "IDR 3,500",
-        category: "Virtual Account"
-      },
-      {
-        paymentMethod: "bsi_va",
-        code: "bsi_va",
-        paymentName: "BSI Virtual Account",
-        paymentImage: "https://my.ipaymu.com/images/banks/bsi.png",
-        totalFee: "IDR 3,500",
-        category: "Virtual Account"
-      },
-      {
-        paymentMethod: "qris",
-        code: "qris",
-        paymentName: "QRIS (GoPay, ShopeePay, DANA, OVO, LinkAja)",
-        paymentImage: "https://my.ipaymu.com/images/banks/qris.png",
-        totalFee: "0.7%",
-        category: "QRIS"
-      },
-      {
-        paymentMethod: "alfamart",
-        code: "alfamart",
-        paymentName: "Alfamart",
-        paymentImage: "https://my.ipaymu.com/images/banks/alfamart.png",
-        totalFee: "IDR 5,000",
-        category: "Retail / Gerai"
-      },
-      {
-        paymentMethod: "indomaret",
-        code: "indomaret",
-        paymentName: "Indomaret",
-        paymentImage: "https://my.ipaymu.com/images/banks/indomaret.png",
-        totalFee: "IDR 5,000",
-        category: "Retail / Gerai"
-      },
-      {
-        paymentMethod: "credit_card",
-        code: "credit_card",
-        paymentName: "Credit / Debit Card (Visa, Mastercard)",
-        paymentImage: "https://my.ipaymu.com/images/banks/cc.png",
-        totalFee: "2.9% + IDR 2,000",
-        category: "Kartu Kredit"
-      },
-      {
-        paymentMethod: "akulaku",
-        code: "akulaku",
-        paymentName: "Akulaku Paylater",
-        paymentImage: "https://my.ipaymu.com/images/banks/akulaku.png",
-        totalFee: "1.7%",
-        category: "Paylater / Cicilan"
-      }
-    ];
-    const categories = {};
-    for (const item of staticMethods) {
-      if (!categories[item.category]) {
-        categories[item.category] = [];
+    const va = config.merchantCode || config.merchantId || "";
+    const apiKey = config.apiKey || "";
+    const sandbox = !!config.sandbox;
+    if (!va || !apiKey) {
+      return {
+        success: false,
+        provider: "ipaymu",
+        methods: [],
+        categories: {},
+        error: "Missing iPaymu credentials (BUAYAR_MERCHANT_CODE/VA or BUAYAR_API_KEY)",
+        rawResponse: null
+      };
+    }
+    try {
+      const url = `${this.getBaseUrl(sandbox)}/payment-channels`;
+      const { signature, timestamp } = generateIpaymuSignature("GET", va, apiKey);
+      const response = await fetch(url, {
+        method: "GET",
+        headers: {
+          "Content-Type": "application/json",
+          "Accept": "application/json",
+          "va": va,
+          "signature": signature,
+          "timestamp": timestamp
+        }
+      });
+      const data = await response.json().catch(() => null);
+      if (response.ok && data?.Data && Array.isArray(data.Data)) {
+        const methods = [];
+        const categories = {};
+        for (const group of data.Data) {
+          const groupCode = (group.Code || "").toLowerCase();
+          const groupName = group.Name || group.Description || "Lainnya";
+          const channels = group.Channels || [];
+          let category = "Lainnya";
+          if (groupCode === "va") category = "Virtual Account";
+          else if (groupCode === "cstore") category = "Retail / Gerai";
+          else if (groupCode === "qris") category = "QRIS";
+          else if (groupCode === "cc") category = "Kartu Kredit";
+          else if (groupCode === "paylater") category = "Paylater / Cicilan";
+          else if (groupCode === "cod") category = "COD";
+          else category = groupName;
+          for (const ch of channels) {
+            const chCode = (ch.Code || "").toLowerCase();
+            let canonicalCode = chCode;
+            if (groupCode === "va") {
+              canonicalCode = chCode === "bag" ? "bag_va" : chCode === "bmi" ? "muamalat_va" : `${chCode}_va`;
+            } else if (groupCode === "cc") {
+              canonicalCode = "credit_card";
+            }
+            let totalFee = "-";
+            if (ch.TransactionFee) {
+              if (ch.TransactionFee.ActualFeeType === "PERCENT") {
+                totalFee = `${ch.TransactionFee.ActualFee}%`;
+              } else if (ch.TransactionFee.ActualFee !== void 0) {
+                totalFee = `IDR ${Number(ch.TransactionFee.ActualFee).toLocaleString()}`;
+              }
+            }
+            const pm = {
+              paymentMethod: canonicalCode,
+              code: canonicalCode,
+              paymentName: ch.Name || ch.Description || canonicalCode,
+              paymentImage: ch.Logo || `https://my.ipaymu.com/images/banks/${chCode}.png`,
+              totalFee,
+              category,
+              extra: {
+                healthStatus: ch.HealthStatus,
+                featureStatus: ch.FeatureStatus,
+                instructionsDoc: ch.PaymentInstructionsDoc,
+                feeDetail: ch.TransactionFee
+              }
+            };
+            methods.push(pm);
+            if (!categories[category]) categories[category] = [];
+            categories[category].push(pm);
+          }
+        }
+        return {
+          success: true,
+          provider: "ipaymu",
+          methods,
+          categories,
+          rawResponse: data
+        };
       }
-      categories[item.category].push(item);
+      return {
+        success: false,
+        provider: "ipaymu",
+        methods: [],
+        categories: {},
+        error: data?.Message || data?.message || `Failed to fetch payment channels (HTTP ${response.status})`,
+        rawResponse: data
+      };
+    } catch (err) {
+      return {
+        success: false,
+        provider: "ipaymu",
+        methods: [],
+        categories: {},
+        error: err.message || "Failed to fetch iPaymu payment channels",
+        rawResponse: null
+      };
     }
-    return {
-      success: true,
-      provider: "ipaymu",
-      methods: staticMethods,
-      categories,
-      rawResponse: staticMethods
-    };
   }
   async checkTransaction(params, config) {
     const { merchantOrderId } = params;
@@ -1874,11 +1876,14 @@ var IpaymuProvider = class extends BasePaymentProvider {
         };
       }
       const txData = data.Data || {};
-      const statusText = (txData.Status || txData.status || "").toString().toLowerCase();
-      const isPaid = statusText === "berhasil" || statusText === "success" || txData.StatusCode === 1;
-      const isPending = statusText === "pending" || txData.StatusCode === 0;
-      const isFailed = !isPaid && !isPending;
-      const isExpired = statusText === "expired";
+      const rawStatus = txData.Status !== void 0 ? txData.Status : txData.status;
+      const statusDesc = (txData.StatusDesc || "").toString().toLowerCase();
+      const paidStatus = (txData.PaidStatus || "").toString().toLowerCase();
+      const statusCode = txData.StatusCode !== void 0 ? Number(txData.StatusCode) : rawStatus !== void 0 ? Number(rawStatus) : void 0;
+      const isPaid = statusCode === 1 || paidStatus === "paid" || statusDesc.includes("berhasil") || statusDesc.includes("success");
+      const isPending = statusCode === 0 || paidStatus === "unpaid" || statusDesc.includes("menunggu") || statusDesc.includes("pending");
+      const isExpired = statusCode === 2 || statusDesc.includes("expired") || statusDesc.includes("kadaluarsa");
+      const isFailed = !isPaid && !isPending && !isExpired;
       const status = isPaid ? "paid" : isPending ? "pending" : isExpired ? "expired" : "failed";
       return {
         success: true,
@@ -8094,6 +8099,137 @@ var IpaymuClient = class {
   async checkTransaction(transactionId) {
     return this.request("POST", "/transaction", { transactionId });
   }
+  /**
+   * Ambil daftar channel pembayaran aktif milik merchant (Official v2: GET /payment-channels)
+   */
+  async getPaymentMethods() {
+    return this.request("GET", "/payment-channels");
+  }
+  /**
+   * Alias untuk getPaymentMethods (Official v2)
+   */
+  async getPaymentChannels() {
+    return this.request("GET", "/payment-channels");
+  }
+  /**
+   * Ambil riwayat transaksi merchant berpaginasi (Official v2: POST /history)
+   */
+  async getHistory(params) {
+    const payload = {
+      account: this.va,
+      page: params?.page || 1,
+      limit: params?.limit || 10,
+      ...params
+    };
+    return this.request("POST", "/history", payload);
+  }
+  /**
+   * Ambil daftar seluruh bank di Indonesia (Official v2: POST /banklist)
+   */
+  async getBankList() {
+    return this.request("POST", "/banklist", { account: this.va });
+  }
+  /**
+   * Cari jangkauan area pengiriman COD (Official v2: GET /cod/area?area=keyword)
+   */
+  async getCodArea(area) {
+    const query = { area };
+    return this.request("GET", `/cod/area?area=${encodeURIComponent(area)}`, query);
+  }
+  /**
+   * Hitung tarif ongkir pengiriman COD (Official v2: POST /cod/shipping-calculate)
+   */
+  async getCodRate(params) {
+    const { pickupArea, deliveryArea, ...rest } = params;
+    const pickupId = params.pickup_area_id !== void 0 ? params.pickup_area_id : pickupArea;
+    const destId = params.destination_area_id !== void 0 ? params.destination_area_id : deliveryArea;
+    const payload = {
+      ...rest,
+      pickup_area_id: pickupId !== void 0 ? String(pickupId) : void 0,
+      destination_area_id: destId !== void 0 ? String(destId) : void 0,
+      amount: params.amount || 0
+    };
+    return this.request("POST", "/cod/shipping-calculate", payload);
+  }
+  /**
+   * Request pickup kurir COD (Official v2: POST /cod/pickup)
+   */
+  async getCodPickup(params) {
+    const { transactionId, ...rest } = params;
+    const payload = {
+      ...rest,
+      transaction_id: params.transaction_id || transactionId
+    };
+    return this.request("POST", "/cod/pickup", payload);
+  }
+  /**
+   * Unduh label pengiriman / AWB COD (Official v2: GET /cod/download-label/:transaction_id)
+   */
+  async getCodAwb(transactionId) {
+    return this.request("GET", `/cod/download-label/${transactionId}`);
+  }
+  /**
+   * Lacak status pengiriman kurir COD berdasarkan no resi / AWB (Official v2: POST /cod/tracking)
+   */
+  async getCodTracking(params) {
+    const payload = typeof params === "string" ? { awb: params } : {
+      awb: params.awb,
+      transaction_id: params.transaction_id || params.transactionId
+    };
+    return this.request("POST", "/cod/tracking", payload);
+  }
+  // ==========================================
+  // Public Area Lookup API (docs.ipaymu.com/en/docs/area-api)
+  // Read-only endpoint untuk provinsi, kota/kabupaten, kecamatan, dan kelurahan
+  // ==========================================
+  /**
+   * Ambil daftar seluruh provinsi di Indonesia
+   */
+  async getAreasProvince() {
+    const res = await fetch("https://my.ipaymu.com/api/areas/province");
+    return res.json();
+  }
+  /**
+   * Ambil daftar kota / kabupaten berdasarkan ID provinsi
+   */
+  async getAreasCity(provinceId) {
+    const res = await fetch(`https://my.ipaymu.com/api/areas/city/${provinceId}`);
+    return res.json();
+  }
+  /**
+   * Ambil daftar kecamatan berdasarkan ID kota / kabupaten
+   */
+  async getAreasDistrict(cityId) {
+    const res = await fetch(`https://my.ipaymu.com/api/areas/district/${cityId}`);
+    return res.json();
+  }
+  /**
+   * Ambil daftar kelurahan berdasarkan ID kecamatan
+   */
+  async getAreasVillage(districtId) {
+    const res = await fetch(`https://my.ipaymu.com/api/areas/village/${districtId}`);
+    return res.json();
+  }
+  // ==========================================
+  // Split Payment — Single Register API
+  // https://ipaymu.com/en/split-payment/
+  // ==========================================
+  /**
+   * Daftarkan agen / reseller / mitra baru untuk Split Payment (Single Register API: POST /api/v2/register)
+   * Mengembalikan VA child account yang siap digunakan untuk parameter `subAccountId` saat membuat transaksi.
+   */
+  async registerUser(params) {
+    const { name, email, phone, password, ...rest } = params;
+    const payload = {
+      ...rest,
+      account: this.va,
+      name,
+      email,
+      phone,
+      password: password || "Password123!"
+    };
+    return this.request("POST", "/register", payload);
+  }
 };
 
 // src/clients/xendit.ts

package/docs/guide.md

@@ -19,7 +19,8 @@ Panduan ini adalah **satu-satunya** panduan yang Anda butuhkan untuk mengintegra
 9. [Provider Dinamis & Autodetect](#-provider-dinamis--autodetect)
 10. [Cek Capability Provider (Portabilitas)](#-cek-capability-provider-portabilitas)
 11. [Fitur Khusus Provider (`<X>Client`)](#-fitur-khusus-provider-xclient)
-12. [Kamus Variabel `.env` per Provider](#-kamus-variabel-env-per-provider)
+12. [Panduan Pengisian Variabel Universal (`BUAYAR_*`) per Provider](#-panduan-pengisian-variabel-universal-buayar_-per-provider)
+13. [Daftar Canonical Payment Methods](#-daftar-canonical-payment-methods)
 
 ---
 
@@ -370,57 +371,59 @@ 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 |
+| Provider | Status | 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](ipaymu.md) | Tested | `getIpaymuClient()` | balance, checkTransaction, getHistory, getBankList, getPaymentMethods/getPaymentChannels, Split Payment (registerUser / subAccountId), COD logistics (getArea, getRate, getPickup, getAwb, getTracking), Public Area API (Province, City, District, Village). *Lihat [panduan lengkap iPaymu](ipaymu.md)* |
+| 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`).
+## 📚 Panduan Pengisian Variabel Universal (`BUAYAR_*`) per Provider
+
+Anda **tidak perlu** membuat nama variabel khusus per provider (seperti `IPAYMU_API_KEY`, `DUITKU_API_KEY`, dsb.). Cukup gunakan set variabel seragam **`BUAYAR_*`**.
+
+Tabel berikut menunjukkan data apa dari dashboard masing-masing payment gateway yang perlu Anda masukkan ke variabel `BUAYAR_*`:
+
+| Provider | `BUAYAR_PROVIDER` | `BUAYAR_API_KEY` | `BUAYAR_MERCHANT_CODE` | `BUAYAR_CLIENT_KEY` / Tambahan |
+| :--- | :--- | :--- | :--- | :--- |
+| **Midtrans** | `midtrans` | Server Key | *(opsional)* | Client Key |
+| **Duitku** | `duitku` | API Key | Merchant Code | *(tidak perlu)* |
+| **iPaymu** | `ipaymu` | API Key | Nomor Virtual Account (VA) | *(tidak perlu)* |
+| **Xendit** | `xendit` | Secret Key | *(opsional)* | Webhook Verification Token (`BUAYAR_WEBHOOK_SECRET`) |
+| **DOKU Jokul** | `doku` | Secret Key | Client ID / Merchant ID | Client ID |
+| **PrismaLink** | `prismalink` | Secret Key | Merchant ID | *(tidak perlu)* |
+| **Faspay** | `faspay` | Password | Merchant ID | User ID |
+| **Finpay** | `finpay` | Merchant Key | Merchant ID | *(tidak perlu)* |
+| **Nicepay** | `nicepay` | Server Key (Secret) | I-MID (Merchant ID) | *(tidak perlu)* |
+| **OY! Bisnis** | `oy` | API Key | Username | Username |
+| **Stripe** | `stripe` | Secret Key (`sk_...`) | *(tidak perlu)* | Publishable Key (`pk_...`) / Webhook Secret |
+| **PayPal** | `paypal` | Client Secret | Client ID | Client ID |
+| **Adyen** | `adyen` | API Key | Merchant Account Name | Client Key / HMAC Key (`BUAYAR_WEBHOOK_SECRET`) |
+| **Checkout.com** | `checkoutcom` | Secret Key (`sk_...`) | *(tidak perlu)* | Public Key (`pk_...`) / Webhook Secret |
+| **Razorpay** | `razorpay` | Key Secret | Key ID | Key ID |
+| **Square** | `square` | Access Token | Application ID | Location ID (`BUAYAR_PROJECT_ID`) |
+| **PayU** | `payu` | MD5 Key / Secret | POS ID | POS ID |
+| **Braintree** | `braintree` | Private Key | Merchant ID | Public Key |
+| **2Checkout** | `twocheckout` | Secret Key | Merchant Code | Secret Word (`BUAYAR_WEBHOOK_SECRET`) |
+
+> 💡 **Mode Sandbox:** Cukup tambahkan `BUAYAR_SANDBOX=true` (atau `false` saat production), SDK otomatis menyesuaikan URL endpoint API seluruh provider di atas tanpa perlu konfigurasi tambahan.
 
 ---
 
@@ -428,7 +431,7 @@ Sandbox: otomatis terdeteksi dari `BUAYAR_SANDBOX`/`NODE_ENV`, atau set per-prov
 
 | Kategori | Canonical Code |
 | :--- | :--- |
-| **Virtual Account** | `bca_va`, `mandiri_va`, `bni_va`, `bri_va`, `permata_va`, `cimb_va`, `danamon_va`, `bsi_va`, `seabank_va` |
+| **Virtual Account** | `bca_va`, `mandiri_va`, `bni_va`, `bri_va`, `permata_va`, `cimb_va`, `danamon_va`, `bsi_va`, `seabank_va`, `bag_va`, `muamalat_va` |
 | **QRIS** | `qris`, `gopay_qris`, `shopeepay_qris`, `nobu_qris` |
 | **E-Wallet** | `gopay`, `shopeepay`, `ovo`, `dana`, `linkaja`, `jenius` |
 | **Retail** | `alfamart`, `indomaret`, `pos` |