@crediblemark/buayar 0.3.1 → 0.3.2

package/docs/adyen.md

@@ -0,0 +1,60 @@
+# 💳 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);
+}
+```

package/docs/braintree.md

@@ -0,0 +1,57 @@
+# 💳 Integrasi Braintree (`braintree`)
+
+Panduan lengkap integrasi Payment Gateway **Braintree (PayPal Service)** dengan `@crediblemark/buayar`.
+
+---
+
+## ⚙️ Konfigurasi Kredensial
+
+Kredensial Braintree dapat diperoleh melalui dashboard [sandbox.braintreegateway.com](https://sandbox.braintreegateway.com):
+
+```env
+# Menggunakan .env (Direkomendasikan)
+PROVIDER_PG=braintree
+BRAINTREE_MERCHANT_ID=...
+BRAINTREE_PUBLIC_KEY=...
+BRAINTREE_PRIVATE_KEY=...
+BRAINTREE_SANDBOX=true
+```
+
+Atau inisialisasi manual:
+
+```typescript
+import { Buayar } from "@crediblemark/buayar";
+
+const buayarBraintree = new Buayar({
+  provider: "braintree",
+  merchantCode: "...", // Merchant ID
+  clientKey: "...",    // Public Key
+  apiKey: "...",       // Private Key
+  sandbox: true,
+});
+```
+
+---
+
+## 🛠️ Membuat Transaksi
+
+```typescript
+import { buayar } from "@crediblemark/buayar";
+
+// Menghasilkan client token untuk Braintree Drop-in UI
+const invoice = await buayar.createInvoice({
+  orderId: "ORDER-BT-001",
+  amount: 2000, // minor units ($20.00)
+  currency: "USD",
+  productDetails: "Annual Premium Tier",
+  customer: {
+    name: "Bruce Wayne",
+    email: "bruce@example.com",
+  },
+});
+
+if (invoice.success) {
+  // Client token untuk dioper ke Drop-in UI Braintree di frontend
+  console.log("Client Token:", invoice.paymentUrl || invoice.reference);
+}
+```

package/docs/checkoutcom.md

@@ -0,0 +1,59 @@
+# 💳 Integrasi Checkout.com (`checkoutcom`)
+
+Panduan lengkap integrasi Payment Gateway **Checkout.com (Payment Links API)** dengan `@crediblemark/buayar`.
+
+---
+
+## ⚙️ Konfigurasi Kredensial
+
+Kredensial Checkout.com dapat diperoleh melalui [dashboard.checkout.com](https://dashboard.checkout.com):
+
+```env
+# Menggunakan .env (Direkomendasikan)
+PROVIDER_PG=checkoutcom
+CHECKOUTCOM_SECRET_KEY=sk_sbox_...
+CHECKOUTCOM_PUBLIC_KEY=pk_sbox_...
+CHECKOUTCOM_WEBHOOK_SECRET=...
+CHECKOUTCOM_SANDBOX=true
+```
+
+Atau inisialisasi manual:
+
+```typescript
+import { Buayar } from "@crediblemark/buayar";
+
+const buayarCko = new Buayar({
+  provider: "checkoutcom",
+  apiKey: "sk_sbox_...",
+  clientKey: "pk_sbox_...",
+  extra: {
+    webhookSecret: "...",
+  },
+  sandbox: true,
+});
+```
+
+---
+
+## 🛠️ Membuat Transaksi
+
+```typescript
+import { buayar } from "@crediblemark/buayar";
+
+const invoice = await buayar.createInvoice({
+  orderId: "ORDER-CKO-001",
+  amount: 5000, // minor units (misal $50.00 / GBP 50.00)
+  currency: "GBP",
+  productDetails: "Design Consultation Fee",
+  customer: {
+    name: "Oliver Twist",
+    email: "oliver@example.com",
+  },
+  returnUrl: "https://myapp.com/payment/success",
+});
+
+if (invoice.success) {
+  console.log("Hosted Payment Link:", invoice.paymentUrl);
+  console.log("Payment Reference:", invoice.reference);
+}
+```

package/docs/doku.md

@@ -0,0 +1,102 @@
+# 💳 Integrasi DOKU Jokul (`doku`)
+
+Panduan lengkap integrasi Payment Gateway **DOKU (Jokul v2)** dengan `@crediblemark/buayar`.
+
+---
+
+## ⚙️ Konfigurasi Kredensial
+
+Kredensial DOKU dapat diperoleh melalui dashboard [jokul.doku.com](https://jokul.doku.com):
+
+```env
+# Menggunakan .env (Direkomendasikan)
+PROVIDER_PG=doku
+DOKU_CLIENT_ID=MALL-ID-xxxxxxxx
+DOKU_SECRET_KEY=SK-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
+DOKU_SANDBOX=true
+```
+
+Atau inisialisasi manual:
+
+```typescript
+import { Buayar } from "@crediblemark/buayar";
+
+const buayarDoku = new Buayar({
+  provider: "doku",
+  merchantCode: "MALL-ID-xxxxxxxx", // Client ID
+  apiKey: "SK-xxxxxxxxxxxxxxxxxxxxxxxxxxxx", // Secret Key
+  sandbox: true,
+});
+```
+
+---
+
+## 🛠️ Membuat Transaksi
+
+### 1. Semi Integrasi (Jokul Checkout Page)
+Kosongkan parameter `paymentMethod`:
+
+```typescript
+import { buayar } from "@crediblemark/buayar";
+
+const invoice = await buayar.createInvoice({
+  orderId: "ORDER-DOKU-001",
+  amount: 250000,
+  productDetails: "Sepatu Olahraga Pria",
+  customer: {
+    name: "Budi Santoso",
+    email: "budi@example.com",
+    phone: "081234567890",
+  },
+  returnUrl: "https://myapp.com/payment/finish",
+});
+
+if (invoice.success) {
+  // Arahkan user ke URL Checkout Jokul DOKU
+  console.log("Checkout URL:", invoice.paymentUrl);
+}
+```
+
+### 2. Full Integrasi (Direct VA / QRIS / Retail / E-Wallet)
+Berikan parameter `paymentMethod` (misal: `bca_va`, `mandiri_va`, `bri_va`, `qris`, `alfamart`, `indomaret`, `ovo`, `dana`):
+
+```typescript
+// Direct Virtual Account (Jokul v2)
+const va = await buayar.createInvoice({
+  orderId: "ORDER-DOKU-002",
+  amount: 150000,
+  paymentMethod: "bca_va",
+  productDetails: "Top Up Game",
+  customer: { name: "Budi", email: "budi@example.com" },
+});
+
+console.log("Nomor VA BCA:", va.vaNumber);
+console.log("Panduan Bayar:", va.paymentUrl);
+console.log("Expired At:", va.expiresAt);
+
+// Direct QRIS
+const qris = await buayar.createInvoice({
+  orderId: "ORDER-DOKU-003",
+  amount: 50000,
+  paymentMethod: "qris",
+  productDetails: "Kopi",
+  customer: { name: "Budi", email: "budi@example.com" },
+});
+
+console.log("Raw QRIS (EMVCo):", qris.qrString);
+console.log("QR Image URL:", qris.qrCodeUrl);
+```
+
+---
+
+## 🏦 Ekstensi `DokuClient` (Cek Status Pesanan)
+
+```typescript
+import { buayar } from "@crediblemark/buayar";
+
+const dokuClient = buayar.getDokuClient();
+
+// Cek status pesanan via Invoice Number
+const orderStatus = await dokuClient.checkTransaction("ORDER-DOKU-001");
+console.log("Status Pesanan:", orderStatus);
+```

package/docs/duitku.md

@@ -0,0 +1,219 @@
+# 💳 Integrasi Duitku (`duitku`)
+
+Halaman ini berisi panduan lengkap untuk menggunakan provider **Duitku** dengan `@crediblemark/buayar`.
+
+---
+
+## ⚙️ Konfigurasi Kredensial
+Untuk menggunakan provider Duitku, Anda perlu menyiapkan objek konfigurasi berikut:
+
+```typescript
+const providerConfig = {
+  merchantCode: "DXXXX",         // Merchant Code dari dashboard Duitku Anda
+  apiKey: "xxxxxxxxxxxxxxxx",    // API Key / Merchant Key Anda
+  sandbox: true,                 // Set true untuk development / testing
+};
+```
+
+---
+
+## 🛠️ Membuat Transaksi (Invoice)
+
+### 1. Mode Redirect Checkout (Duitku Checkout Page)
+Jika Anda ingin mengarahkan pelanggan ke halaman pembayaran yang disediakan oleh Duitku (di mana pelanggan dapat memilih sendiri metode pembayaran mereka):
+
+```typescript
+import { paymentManager } from "@crediblemark/buayar";
+
+const invoiceParams = {
+  orderId: "ORDER-100249",
+  amount: 150000,                // Nominal dalam Rupiah (integer)
+  productDetails: "Pembelian Template Landing Page Premium",
+  customer: {
+    name: "Rasyiqi Crediblemark",
+    email: "rasyiqi@crediblemark.com",
+    phone: "081234567890",
+  },
+  returnUrl: "https://situsbisnis.com/payment/success",
+  callbackUrl: "https://api.situsbisnis.com/v1/payment/callback",
+};
+
+async function checkoutRedirect() {
+  try {
+    const result = await paymentManager.createInvoice(
+      "duitku",
+      invoiceParams,
+      providerConfig
+    );
+
+    if (result.success) {
+      console.log("Invoice Berhasil Dibuat! 🎉");
+      console.log("Halaman Pembayaran:", result.paymentUrl); // Redirect pelanggan ke URL ini
+      console.log("Referensi Duitku:", result.reference);
+    } else {
+      console.error("Gagal membuat invoice:", result.error);
+    }
+  } catch (error) {
+    console.error("Terjadi kesalahan:", error);
+  }
+}
+```
+
+### 2. Mode Direct Inquiry (Dapatkan VA / QRIS Instan)
+Jika Anda ingin menampilkan nomor Virtual Account atau kode QRIS langsung di website/aplikasi Anda tanpa mengarahkan pelanggan keluar dari situs Anda, sertakan opsi `paymentMethod`:
+
+```typescript
+const directParams = {
+  orderId: "ORDER-100249",
+  amount: 150000,
+  productDetails: "Pembelian Template Landing Page Premium",
+  customer: {
+    name: "Rasyiqi Crediblemark",
+    email: "rasyiqi@crediblemark.com",
+    phone: "081234567890",
+  },
+  returnUrl: "https://situsbisnis.com/payment/success",
+  callbackUrl: "https://api.situsbisnis.com/v1/payment/callback",
+  paymentMethod: "BCA", // Contoh kode pembayaran Duitku untuk BCA Virtual Account
+};
+
+async function checkoutDirect() {
+  try {
+    const result = await paymentManager.createInvoice(
+      "duitku",
+      directParams,
+      providerConfig
+    );
+
+    if (result.success) {
+      console.log("Nomor Virtual Account:", result.vaNumber);
+      console.log("Referensi Duitku:", result.reference);
+    } else {
+      console.error("Gagal memproses direct inquiry:", result.error);
+    }
+  } catch (error) {
+    console.error("Error:", error);
+  }
+}
+```
+
+---
+
+## 🔔 Verifikasi Webhook Callback
+Gunakan fungsi ini di endpoint API notifikasi Duitku untuk memverifikasi keaslian signature data:
+
+```typescript
+import { paymentManager } from "@crediblemark/buayar";
+
+async function handleDuitkuCallback(req: any, res: any) {
+  const callbackPayload = req.body; // Payload POST dari Duitku
+
+  try {
+    const verification = await paymentManager.verifyCallback(
+      "duitku",
+      callbackPayload,
+      providerConfig
+    );
+
+    if (verification.isValid) {
+      console.log(`Signature valid untuk Order ID: ${verification.orderId}`);
+      
+      if (verification.status === "paid") {
+        console.log("Status: PEMBAYARAN LUNAS! ✅");
+        // Update status order di database Anda menjadi LUNAS/SUCCESS
+      } else if (verification.status === "failed") {
+        console.log("Status: PEMBAYARAN GAGAL ❌");
+        // Update status order di database Anda menjadi GAGAL
+      }
+      
+      // Duitku memerlukan respon plaintext "OK" jika callback berhasil diproses
+      res.status(200).send("OK");
+    } else {
+      console.warn("Peringatan: Signature callback tidak valid!");
+      res.status(400).send("Bad Signature");
+    }
+  } catch (error) {
+    console.error("Gagal memproses callback:", error);
+    res.status(500).send("Internal Server Error");
+  }
+}
+```
+
+---
+
+## 🔍 Cek Status Transaksi Manual
+Anda dapat melakukan polling atau pemeriksaan status transaksi secara manual:
+
+```typescript
+async function checkTransactionStatus() {
+  const result = await paymentManager.checkTransaction(
+    "duitku",
+    { merchantOrderId: "ORDER-100249" },
+    providerConfig
+  );
+
+  if (result.success) {
+    console.log("Status Transaksi:", result.status); // "paid" | "pending" | "failed"
+    console.log("Detail Status:", result.statusMessage);
+  }
+}
+```
+
+---
+
+## 📋 Mendapatkan Daftar Metode Pembayaran Aktif
+Anda dapat mengambil daftar metode pembayaran yang tersedia secara dinamis beserta rincian biaya (fee) transaksi:
+
+```typescript
+async function loadDuitkuMethods() {
+  const result = await paymentManager.getPaymentMethods(
+    "duitku",
+    { amount: 150000 },
+    providerConfig
+  );
+
+  if (result.success) {
+    console.log("Metode Pembayaran Aktif:", result.methods);
+    // SDK secara otomatis mengelompokkan ke dalam kategori terstandarisasi untuk UI:
+    // "Virtual Account", "QRIS", "E-Wallet", "Retail / Gerai", "Lainnya"
+```
+
+---
+
+## 🏦 Ekstensi `DuitkuClient` (Disbursement & Saldo)
+
+Selain alur transaksi reguler, SDK menyediakan **`DuitkuClient`** untuk mengelola pengecekan saldo dan transfer dana / payout (*disbursement*):
+
+```typescript
+import { buayar, DuitkuClient } from "@crediblemark/buayar";
+
+// Opsi 1: Dari instance buayar
+const client = buayar.getDuitkuClient();
+
+// Opsi 2: Inisialisasi mandiri
+// const client = new DuitkuClient({ merchantCode: "DXXXX", apiKey: "...", sandbox: true });
+
+// 1. Cek Saldo Merchant
+const balanceResult = await client.checkBalance();
+console.log("Saldo Merchant:", balanceResult.balance);
+
+// 2. Daftar Bank yang Didukung Payout
+const banks = await client.listBanks();
+console.log("Daftar Bank:", banks);
+
+// 3. Validasi Pemilik Rekening Bank (Inquiry)
+const accountInfo = await client.inquiryBankAccount("BCA", "1234567890");
+console.log("Nama Pemilik:", accountInfo.accountName);
+
+// 4. Eksekusi Transfer Dana (Disbursement)
+const disburseResult = await client.disburse({
+  merchantOrderId: "DISBURSE-001",
+  bankCode: "BCA",
+  bankAccount: "1234567890",
+  amount: 500000,
+  purpose: "Penarikan Saldo Mitra",
+  senderName: "PT Bisnis Anda",
+});
+console.log("Status Transfer:", disburseResult);
+```
+

package/docs/faspay.md

@@ -0,0 +1,109 @@
+# 💳 Integrasi Faspay (`faspay`)
+
+Panduan lengkap integrasi Payment Gateway **Faspay** dengan `@crediblemark/buayar`.
+
+---
+
+## ⚙️ Konfigurasi Kredensial
+
+Kredensial Faspay dapat diperoleh melalui dashboard [merchant.faspay.co.id](https://merchant.faspay.co.id):
+
+```env
+# Menggunakan .env (Direkomendasikan)
+PROVIDER_PG=faspay
+FASPAY_MERCHANT_ID=31112
+FASPAY_USER_ID=db31112
+FASPAY_PASSWORD=faspay-password-xxxxxxxx
+FASPAY_MERCHANT_NAME="Toko Saya"
+FASPAY_SANDBOX=true
+```
+
+Atau inisialisasi manual:
+
+```typescript
+import { Buayar } from "@crediblemark/buayar";
+
+const buayarFaspay = new Buayar({
+  provider: "faspay",
+  merchantCode: "31112", // Merchant ID
+  clientKey: "db31112", // User ID
+  apiKey: "faspay-password-xxxxxxxx", // Password
+  sandbox: true,
+});
+```
+
+---
+
+## 🛠️ Membuat Transaksi
+
+### 1. Semi Integrasi (Faspay Payment Page)
+Kosongkan parameter `paymentMethod`:
+
+```typescript
+import { buayar } from "@crediblemark/buayar";
+
+const invoice = await buayar.createInvoice({
+  orderId: "ORDER-FASPAY-001",
+  amount: 250000,
+  productDetails: "Sepatu Olahraga",
+  customer: {
+    name: "Budi Santoso",
+    email: "budi@example.com",
+    phone: "081234567890",
+  },
+  returnUrl: "https://myapp.com/payment/finish",
+});
+
+if (invoice.success) {
+  // Arahkan user ke URL Pembayaran Faspay
+  console.log("Payment URL:", invoice.paymentUrl);
+}
+```
+
+### 2. Full Integrasi (Direct VA / QRIS / Retail)
+Berikan parameter `paymentMethod` (misal: `bca_va`, `mandiri_va`, `bri_va`, `qris`, `alfamart`, `indomaret`):
+
+```typescript
+// Direct Virtual Account (Post Data Transaction)
+const va = await buayar.createInvoice({
+  orderId: "ORDER-FASPAY-002",
+  amount: 150000,
+  paymentMethod: "bca_va",
+  productDetails: "Top Up Diamond",
+  customer: { name: "Budi", email: "budi@example.com" },
+});
+
+console.log("Nomor VA BCA:", va.vaNumber);
+console.log("Payment URL:", va.paymentUrl);
+console.log("Expired At:", va.expiresAt);
+
+// Direct QRIS
+const qris = await buayar.createInvoice({
+  orderId: "ORDER-FASPAY-003",
+  amount: 50000,
+  paymentMethod: "qris",
+  productDetails: "Kopi Gula Aren",
+  customer: { name: "Budi", email: "budi@example.com" },
+});
+
+console.log("Raw QRIS (EMVCo):", qris.qrString);
+console.log("QR Image URL:", qris.qrCodeUrl);
+```
+
+---
+
+## 🏦 Ekstensi `FaspayClient` (Inquiry & Cancel)
+
+```typescript
+import { buayar } from "@crediblemark/buayar";
+
+const faspayClient = buayar.getFaspayClient();
+
+// 1. Cek status pembayaran tagihan
+const status = await faspayClient.checkTransaction("ORDER-FASPAY-001");
+console.log("Status Pesanan:", status);
+
+// 2. Batalkan tagihan
+const cancel = await faspayClient.cancelTransaction("ORDER-FASPAY-001", "402");
+console.log("Hasil Pembatalan:", cancel);
+```

package/docs/finpay.md

@@ -0,0 +1,102 @@
+# 💳 Integrasi Finpay (`finpay`)
+
+Panduan lengkap integrasi Payment Gateway **Finpay (PT Finnet Indonesia - Telkom Group)** dengan `@crediblemark/buayar`.
+
+---
+
+## ⚙️ Konfigurasi Kredensial
+
+Kredensial Finpay dapat diperoleh melalui dashboard [dashboard.finpay.id](https://dashboard.finpay.id):
+
+```env
+# Menggunakan .env (Direkomendasikan)
+PROVIDER_PG=finpay
+FINPAY_MERCHANT_ID=FINPAY-MERCHANT-001
+FINPAY_MERCHANT_KEY=finpay-secret-key-xxxxxxxxxxxxxxxx
+FINPAY_SANDBOX=true
+```
+
+Atau inisialisasi manual:
+
+```typescript
+import { Buayar } from "@crediblemark/buayar";
+
+const buayarFinpay = new Buayar({
+  provider: "finpay",
+  merchantCode: "FINPAY-MERCHANT-001", // Merchant ID
+  apiKey: "finpay-secret-key-xxxxxxxxxxxxxxxx", // Merchant Key / Signature Key
+  sandbox: true,
+});
+```
+
+---
+
+## 🛠️ Membuat Transaksi
+
+### 1. Semi Integrasi (Finpay Checkout Link)
+Kosongkan parameter `paymentMethod`:
+
+```typescript
+import { buayar } from "@crediblemark/buayar";
+
+const invoice = await buayar.createInvoice({
+  orderId: "ORDER-FINPAY-001",
+  amount: 250000,
+  productDetails: "Tagihan Langganan Internet",
+  customer: {
+    name: "Budi Santoso",
+    email: "budi@example.com",
+    phone: "081234567890",
+  },
+  returnUrl: "https://myapp.com/payment/finish",
+});
+
+if (invoice.success) {
+  // Arahkan user ke URL Checkout Finpay
+  console.log("Payment URL:", invoice.paymentUrl);
+}
+```
+
+### 2. Full Integrasi (Direct VA / QRIS / Retail / Pos)
+Berikan parameter `paymentMethod` (misal: `bca_va`, `mandiri_va`, `bri_va`, `qris`, `pos`, `alfamart`, `indomaret`):
+
+```typescript
+// Direct Virtual Account
+const va = await buayar.createInvoice({
+  orderId: "ORDER-FINPAY-002",
+  amount: 150000,
+  paymentMethod: "bca_va",
+  productDetails: "Top Up Saldo",
+  customer: { name: "Budi", email: "budi@example.com" },
+});
+
+console.log("Nomor VA BCA:", va.vaNumber);
+console.log("Payment URL:", va.paymentUrl);
+console.log("Expired At:", va.expiresAt);
+
+// Direct QRIS
+const qris = await buayar.createInvoice({
+  orderId: "ORDER-FINPAY-003",
+  amount: 50000,
+  paymentMethod: "qris",
+  productDetails: "Kopi",
+  customer: { name: "Budi", email: "budi@example.com" },
+});
+
+console.log("Raw QRIS (EMVCo):", qris.qrString);
+console.log("QR Image URL:", qris.qrCodeUrl);
+```
+
+---
+
+## 🏦 Ekstensi `FinpayClient` (Cek Status Pembayaran)
+
+```typescript
+import { buayar } from "@crediblemark/buayar";
+
+const finpayClient = buayar.getFinpayClient();
+
+// Cek status pembayaran
+const status = await finpayClient.checkTransaction("ORDER-FINPAY-001");
+console.log("Status Pesanan:", status);
+```