@crediblemark/buayar 0.3.2 → 0.5.1

package/dist/index.mjs

@@ -1980,11 +1980,11 @@ var XenditProvider = class extends BasePaymentProvider {
           amount: integerAmount,
           reference_id: orderId,
           description: productDetails,
-          customer: {
-            given_names: customer.name,
-            email: customer.email,
-            mobile_number: customer.phone || ""
-          },
+          // Xendit Payment Requests API rejects the inline `customer` object
+          // with API_VALIDATION_ERROR. Attribution is only supported via a
+          // pre-created `customer_id` (Customer API), so we forward that when
+          // provided through providerParams and otherwise omit customer data.
+          ...params.providerParams?.customer_id ? { customer_id: params.providerParams.customer_id } : {},
           payment_method: paymentMethodPayload,
           ...params.providerParams
         };
@@ -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,10 +1,13 @@
 {
   "name": "@crediblemark/buayar",
-  "version": "0.3.2",
+  "version": "0.5.1",
   "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",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "buayar": "./dist/cli/index.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -68,14 +71,19 @@
   },
   "license": "MIT",
   "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
+    "build": "tsup src/index.ts --format cjs,esm --dts && tsup src/cli/index.ts --format cjs --platform node --out-dir dist/cli && node -e \"const fs=require('fs');const f='dist/cli/index.js';const s=fs.readFileSync(f,'utf8');if(!s.startsWith('#!'))fs.writeFileSync(f,'#!/usr/bin/env node\\n'+s);fs.chmodSync(f,0o755);\"",
+    "dev": "tsup src/index.ts src/cli/index.ts --format cjs,esm --dts --out-dir dist --watch",
+    "init": "node ./dist/cli/index.js init",
+    "postinstall": "echo \"🐊 Buayar terpasang! Jalankan \\\"npx buayar init\\\" untuk membuat boilerplate payment yang siap pakai.\"",
+    "test": "bun test"
   },
   "devDependencies": {
     "@types/bun": "^1.4.0",
     "@types/node": "^24.12.2",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0"
   }
 }
-

package/docs/adyen.md

@@ -1,60 +0,0 @@
-# 💳 Integrasi Adyen (`adyen`)
-
-Panduan lengkap integrasi Payment Gateway **Adyen Checkout Sessions API v71** dengan `@crediblemark/buayar`.
-
----
-
-## ⚙️ Konfigurasi Kredensial
-
-Kredensial Adyen dapat diperoleh melalui [ca-test.adyen.com](https://ca-test.adyen.com):
-
-```env
-# Menggunakan .env (Direkomendasikan)
-PROVIDER_PG=adyen
-ADYEN_API_KEY=AQE...
-ADYEN_MERCHANT_ACCOUNT=YourMerchantAccount
-ADYEN_CLIENT_KEY=test_...
-ADYEN_HMAC_KEY=4A6...
-ADYEN_SANDBOX=true
-```
-
-Atau inisialisasi manual:
-
-```typescript
-import { Buayar } from "@crediblemark/buayar";
-
-const buayarAdyen = new Buayar({
-  provider: "adyen",
-  apiKey: "AQE...",
-  merchantCode: "YourMerchantAccount",
-  extra: {
-    hmacKey: "4A6...",
-  },
-  sandbox: true,
-});
-```
-
----
-
-## 🛠️ Membuat Transaksi
-
-```typescript
-import { buayar } from "@crediblemark/buayar";
-
-const invoice = await buayar.createInvoice({
-  orderId: "ORDER-ADYEN-001",
-  amount: 150000,
-  currency: "IDR",
-  productDetails: "Annual Cloud Hosting",
-  customer: {
-    name: "Alex",
-    email: "alex@example.com",
-  },
-  returnUrl: "https://myapp.com/payment/return",
-});
-
-if (invoice.success) {
-  console.log("Checkout URL:", invoice.paymentUrl);
-  console.log("Session ID:", invoice.reference);
-}
-```